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

20    Driver Attributes API

Low-Level Communications

Exploring Palm OS®

Applications can use the functions described in this section to query IOS about drivers. These C-language functions are are not meant for use by STREAMS drivers, but by the clients that depend upon them.

This chapter discusses the following topics:

Driver Attribute Constants
Driver Attribute Functions

Driver Attribute Constants ^TOP^

Driver Class Constants ^TOP^

Purpose

Driver classes are used to classify groups of drivers. Not all drivers need to be classified. Certain classes of drivers, such as the drivers that need to work with the Serial Manager, should be classified. All driver classes are reserved creator codes.

Declared In

SDK/headers/IOSAttributes.h

Table 20.1  Driver Classes

Class Name

Creator ID

Description

iosDriverClassGeneric

'cgen'

A generic class used for drivers that have an attributes block or a description but do not belong to a defined class.

iosDriverClassSerial

'cser'

Drivers that are designed to work with Serial Manager should use this class.

iosDriverClassEthernet

'ceth'

Drivers that are designed to support the Ethernet interface.

iosDriverClassSlot

'cslt'

Drivers that support expansion card slots.

iosDriverClassVolume

'cvol'

Volumes that support a specific file system implementation.

iosDriverClassAdmin

'cadm'

Drivers that are responsible for configuration or administration within IOS.

iosDriverClassWifi

'wifi'

Drivers that are associated with wireless ("Wi-Fi") communication.

iosDriverClassAll

'call'

Drivers can not use iosDriverClassAll as their class ID. This class ID is used in the Driver Attributes API to get attributes or a description for all installed drivers.

Comments

At this time, you cannot add additional classes. A driver may only belong to one class.

Driver Attribute Functions ^TOP^

Declared In

IOSAttributes.h

IOSGetNumDrivers Function ^TOP^

Purpose

Returns the number of drivers registered in IOS for the specified class. The class value CLASS_ALL is reserved to indicate all drivers.

Prototype

status_t IOSGetNumDrivers(
   uint32_t iClassID,
   uint16_t *oCount
)

Parameters

iClassID
The class ID for the group of drivers you want to count. For the list of available class IDs, see "Driver Attribute Constants."
oCount
The number of drivers in the specified class.

Returns

If the call is unsuccessful, this function returns an error code. Otherwise, it returns errNone.

IOSGetDriverAttributesByIndex Function ^TOP^

Purpose

Returns the class-specific attributes block for a driver in the specified class at the given index. The class value CLASS_ALL is reserved to indicate all drivers.

Prototype

status_t IOSGetDriverAttributesByIndex(
   uint32_t iClassID,
   int16_t iIndex,
   MemPtr ioBuf,
   uint16_t* ioBufLen
)

Parameters

iClassID
The driver's class ID. For the list of available class IDs, see "Driver Attribute Constants."
iIndex
The index of the driver in the set of drivers contained in the class. Applications can get the number of drivers in the class (using IOSGetNumDrivers()) and loop over this function to get the attributes for each of the drivers in the class.
ioBuf
A buffer in the user's memory space. The attributes block will be copied into this space.
ioBuflen
When calling this function, set this parameter to the number of bytes in the user buffer. Upon return, this parameter will be set to the length of the attributes block.

Returns

errNone
The operation completed successfully.
iosErrNotEnoughSpace
The buffer was too small to contain the attributes block. The length of the attribute block is in the ioBuflen parameter.
iosErrDriverNotFound
A matching driver could not be found at that class and index.

IOSGetDriverAttributesByName Function ^TOP^

Purpose

Returns the class-specific attributes block for a driver, given its driver name.

Prototype

status_t IOSGetDriverAttributesByName(
   Char const * iIOSName,
   MemPtr ioBuf,
   uint16_t* ioBufLen
)

Parameters

iIOSName
The name of a registered driver in IOS. A driver can be a device driver, a STREAMS module, or STREAMS driver.

WARNING! This function does not use partial name matching. The function will only return the attributes if iIOSName contains a complete match.
ioBuf
A buffer in the user's memory space. The attributes block will be copied into this space.
ioBuflen
When calling this function, set this parameter to the number of bytes in the user buffer. Upon return, this parameter will be set to the length of the attributes block.

Returns

errNone
The operation completed successfully.
iosErrNotEnoughSpace
The buffer was too small to contain the attributes block. The length of the attribute block is in the ioBuflen parameter.
iosErrDriverNotFound
A matching driver could not be found for that driver name.

IOSGetDriverDescriptionByIndex Function ^TOP^

Purpose

Returns the descriptive name for a driver in the specified class at the given index. The class value CLASS_ALL is reserved to indicate all drivers.

Prototype

status_t IOSGetDriverDescriptionByIndex(
   uint32_t iClassID,
   int16_t iIndex,
   Char* ioBuf,
   uint16_t* ioBufLen
)

Parameters

iClassID
The driver's class ID. For the list of available class IDs, see "Driver Attribute Constants."
iIndex
The index of the driver in the set of drivers contained in the class. Applications can get the number of drivers in the class (using IOSGetNumDrivers()) and loop over this function to get the description for each of the drivers in the class.
ioBuf
A buffer in the user's memory space. The descriptive name string will be copied into this space.
ioBuflen
When calling this function, set this parameter to the number of bytes in the user buffer. Upon return, this parameter will be set to the length of the descriptive name string plus the null character.

Returns

errNone
The operation completed successfully.
iosErrNotEnoughSpace
The buffer was too small to contain the descriptive name string. The length of the descriptive name string + 1 is in the ioBuflen parameter.
iosErrDriverNotFound
A matching driver could not be found at that class and index.

Comments

An installed driver may not have a descriptive name. In that case, the buffer will contain a zero-length string.

IOSGetDriverDescriptionByName Function ^TOP^

Purpose

Returns the descriptive name string for a driver, given the driver's name in IOS.

Prototype

status_t IOSGetDriverDescriptionByName(
   Char const * iIOSName,
   Char* ioBuf,
   uint16_t* ioBufLen
)

Parameters

iIOSName
The name of a registered driver in IOS. A driver can be a device driver, a STREAMS module, or STREAMS driver.

WARNING! This function does not use partial name matching. The function will only return the attributes if iIOSName contains a complete match.
ioBuf
A buffer in the user's memory space. The descriptive name string will be copied into this space.
ioBuflen
When calling this function, set this parameter to the number of bytes in the user buffer. Upon return, this parameter will be set to the length of the descriptive name string plus the null character.

Returns

errNone
The operation completed successfully.
iosErrNotEnoughSpace
The buffer was too small to contain the descriptive name string. The length of the descriptive name string + 1 is in the ioBuflen parameter.
iosErrDriverNotFound
A matching driver could not be found at that driver name.

IOSGetDriverNameByIndex Function ^TOP^

Purpose

Returns the driver name in IOS for a driver in the specified class, given the index. The class value CLASS_ALL is reserved to indicate all drivers.

Prototype

status_t IOSGetDriverDescriptionByIndex(
   uint32_t iClassID,
   int16_t iIndex,
   Char* ioBuf,
   uint16_t* ioBufLen
)
iClassID
The driver's class ID. For the list of available class IDs, see "Driver Attribute Constants."
iIndex
The index of the driver in the set of drivers contained in the class. Applications can get the number of drivers in the class (using IOSGetNumDrivers()) and loop over this function to get the description for each of the drivers in the class.
ioBuf
A buffer in the user's memory space. The driver name string will be copied into this space.
ioBuflen
When calling this function, set this parameter to the number of bytes in the user buffer. Upon return, this parameter will be set to the length of the driver name string plus the NULL.

Returns

errNone
The operation completed successfully.
iosErrNotEnoughSpace
The buffer was too small to contain the descriptive name string. The length of the descriptive name string + 1 is in the ioBuflen parameter.
iosErrDriverNotFound
A matching driver could not be found at that class and index.