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
Driver Class Constants
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
Comments
At this time, you cannot add additional classes. A driver may only belong to one class.
Driver Attribute Functions
Declared In
IOSAttributes.h
IOSGetNumDrivers Function
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
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
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
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
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
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 theioBuflen
parameter. -
iosErrDriverNotFound
- A matching driver could not be found at that class and index.