Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

21    Driver Installation API

Low-Level Communications

Exploring Palm OS®

All drivers are installed into the I/O Process using the I/O Subsystem's Driver Installation API. A driver's installation software must make use of the installation functions provided by this API.

This chapter discusses the following topics:

IOS Installation Functions

IOS Installation Functions ^TOP^

IOSInstallDriver Function ^TOP^

Purpose

Installs a driver into the I/O Process.

Declared In

SDK/headers/IOSInstall.h

Prototype

status_t IOSInstallDriver(
   uint32_t typeId,
   uint32_t creatorId,
   uint32_t resourceID
)

Parameters

typeId
The type for the driver PRC. For example, 'mydr'.

NOTE: The Device Loader will automatically install drivers of type 'drvr'. Drivers of this type will not call IOSInstallDriver() explicitly. For drivers with a different database type, the program that installs the driver should call this function.
creatorId
The creator ID for the driver PRC. For example, 'MYDR'.
resourceID
The resource ID of the driver to be installed. This is the ID that was assigned to the driver when the PRC was created. This ID should be the same as that declared in the PRC's SLD file.

Returns

iosErrDriverNotFound
The PRC was not found (or no driver with those attributes was found in the PRC).
iosErrInvalidArg
The name of the driver is missing (or is not a string).
iosErrAuthFailed
The driver was not signed in the manner required by Palm OS.

Comments

If the device's security policy requires a signature, Palm OS will verify the signature of the driver when this function is called. For more information about signing your drivers, see Exploring Palm OS: Security and Cryptography.

IOSRemoveDriver Function ^TOP^

Purpose

Requests the removal of a driver from the I/O Process. Note that a driver with an active session cannot be removed.

Declared In

SDK/headers/IOSInstall.h

Prototype

Status_t IOSRemoveDriver(
   uint32_t type,
   uint32_t creator,
   uint32_t resourceID
)

Parameters

typeId
The type for the driver PRC. For example, 'drvr'.
creatorId
The creator ID for the driver PRC. For example, 'MYDR'.
resourceID
The resource ID of the driver to be removed. This is the ID that was assigned to the driver when the PRC was created. This ID should be the same as that declared in the PRC's SLD file.

Returns

iosErrDriverNotFound
The PRC was not found (or no driver with those attributes was found in the PRC).
iosErrInvalidArg
The name of the driver is missing (or is not a string).
iosErrDeviceInUse
The driver has an active session and cannot be removed at this time.

Comments

Calling IOSRemoveDriver() only removes the driver from the
I/O Process—it does not delete the driver's PRC. After the driver has been removed, the uninstallation software may delete the PRC using DmDeleteDatabase().


WARNING! A driver that has an active session cannot be removed. All active sessions with the driver must be closed before you can request removal of the driver.