IrDA Constants
IASAttribTypeType Enum
Purpose
Declared In
IAS.h
Constants
IASCharSetType Enum
Purpose
Define character sets supported by IAS.
Declared In
IAS.h
Constants
IrDA Protocol Identifier Constants
Purpose
Define IrDA protocols when using the Sockets API.
Declared In
IrDA.h
Constants
IrDA Socket Address Family Constant
Purpose
Defines the address family used by IrDA socket connections.
Declared In
posix/sys/socket.h
Constants
AF_IRDA
Comments
When creating a socket for use in IrDA communications, use the AF_IRDA
constant to indicate that the address is an IrDA device address.
IrLmpDiscoveryMethodType Enum
Purpose
Define values for the discovery method specified in the IrLmpDeviceInfoType
structure.
Declared In
IrDA.h
Constants
IAS Constants
Purpose
Declared In
IAS.h
Constants
setsockopt() commands
Purpose
Define IrDA-specific setockopt()
commands.
Declared In
IrDA.h
Constants
Special IrDA Device Addresses
Purpose
Define special-purpose IrDA device addresses.
Declared In
IrDA.h
Constants
NOTE: Connecting to
IRADDR_BROADCAST
causes IrLMP to automatically perform a discovery procedure, then connect to one of the devices it discovers. Connecting to IRADDR_ANY
will initiate an IrLMP connection to whatever device is currently at the other end of an established IrLAP connection; if IrLAP isn't already connected, the connect()
will fail.
Special IrLMP SAP Values
Purpose
Describe Service Access Points (SAPs) to which connection-oriented sockets can be bound.
Declared In
IrDA.h
Constants
IrDA Data Types and Structures
IASAttribValueType Typedef
Purpose
Describes the type and value of an IAS attribute.
Declared In
IAS.h
Prototype
typedef PACKED struct IASAttribValueTag { uint8_t attribType; PACKED union { uint32_t integer; PACKED struct { uint16_t length; uint8_t bytes[0]; } octetString; PACKED struct { uint8_t charSet; uint8_t length; uint8_t chars[1]; } userString; } value; } IASAttribValueType;
Fields
-
attribType
- An
IASAttribTypeType
value specifying the type of attribute the structure represents. -
value
- A union containing the value of the attribute, depending on the attribute type:
-
integer
- The value of the attribute if it's of type
iasAttribInteger
. -
octetString
- The value of the attribute if it's of type
iasAttribOctetString
. Thelength
field indicates the number of bytes in the attribute string, andbytes
is the string itself. -
userString
- The value of the attribute if it's of type
iasAttribUserString
. ThecharSet
field indicates anIASCharSetType
value specifying the character set in which the string is defined,length
indicates the length of the string in bytes (not characters), andchars
is alength
-byte long array containing the string itself.
IASObjectType Struct
Purpose
Declared In
IAS.h
Prototype
typedef struct IASObjectTag { const char *className; const uint8_t *hintBits; uint16_t attribCount; const char **attribNames; IASAttribValueType **attribValues; } IASObjectType;
Fields
-
className
- The user-supplied class name.
-
hintBits
- Bits to be included in IrLMP's "IrLMPSupport" attribute.
-
attribCount
- The number of attributes included in the object.
-
attribNames
- An array of
attribCount
strings naming each of the object's attributes. -
attribValues
- An array of
attribCount
IASAttribValueType
structures, each describing the value of the corresponding attribute.
IASQueryType Struct
Purpose
Declared In
IAS.h
Prototype
typedef struct IASQueryTag { IrLapDeviceAddrType addr; const char *className; const char *attribName; uint8_t *resultBuf; uint32_t resultBufLen; uint16_t attribCount; IASAttribValueType **attribValues; uitn16_t *objectIDs; uint32_t resultSize; } IASQueryType;
Fields
-
addr
- Address of the device to query. Can be
IRADDR_ANY
orIRADDR_BROADCAST
. -
className
- The name of the class to look for.
-
attribName
- The name of the attribute to look for.
-
resultBuf
- A pointer to a buffer to store the results into. This must point to a buffer before using the structure in a query.
-
resultBufLen
- The length of the
resultBuf
buffer in bytes. This must be set to the length of the buffer before using the structure in a query. -
atttribCount
- The
IASGetValueByClass()
function fills in this value with the number of attributes retrieved as a result of the query. -
attribValues
- The
IASQueryValueByClass()
function fills this out to point to an array of the retrieved attribute values. -
objectIDs
- The
IASGetValueByClass()
function fills this field out with a pointer to an array of the object IDs of all the found attributes. -
resultSize
- The
IASGetValueByClass()
function fills out this field with the size of the result in bytes.
IrLapDeviceAddrType Typedef
Purpose
Specifies the address of an IrDA device.
Declared In
IrDA.h
Prototype
typedef uint32_t IrLapDeviceAddrType;
Comments
IrDA device addresses are 32-bit integer values. A device's IrDA address is generated internally by its IrDA stack, and can be changed by the stack without warning.
Additionally, a device address' byte order is not defined; currently addresses are in little-endian format, but that could change in the future. Applications should therefore treat device addresses as an opaque identifier with short lifespans. For example, the sockaddr_irda
structure's sir_addr
field should only be populated with the results of a discovery procedure, and this should be done soon after the discovery procedure has completed.
There are two special device addresses that are exempt to this rule: IRADDR_ANY
and IRADDR_BROADCAST
are never returned by a discovery procedure, and can be used in sockaddr_irda
at any time.
IrLmpDeviceInfoType Struct
Purpose
Provides information describing an IrDA device.
Declared In
IrDA.h
Prototype
typedef struct IrLmpDeviceInfoTag { IrLapDeviceAddrType deviceAddr; uint8_t method; uint8_t __pad0[2]; uint8_t infoLen; uint8_t deviceInfo[32]; } IrLmpDeviceInfoType;
Fields
-
deviceAddr
- The 32-bit IrLAP device address of the device described by the structure.
-
method
- The method by which the device was discovered. This will be one of the values specified by the
IrLmpDiscoveryMethodType
enum. -
__pad0
- Reserved for system use. Do not use this field.
-
infoLen
- The number of bytes of valid data in the
deviceInfo
array. -
deviceInfo
- Information about the device. Usually this is the name of the device, with the first byte indicating the character set in which the name is encoded, followed by a null-terminated string naming the device. Only the first
infoLen
bytes contain valid data.
IrLmpSAPType Typedef
Purpose
Selects the Service Access Point (SAP) for IrLMP and TinyTP.
Declared In
IrDA.h
Prototype
typedef uint8_t IrLmpSAPType;
Comments
The IrLmpSAPType
is an 8-bit value that describes an IrLMP Service Access Point. Constants for special SAPs (the IAS server SAP and the unitdata SAP) are provided.
See Also
sockaddr_irda Struct
Purpose
Describes an IrLMP address for use with the Sockets API.
Declared In
IrDA.h
Prototype
struct sockaddr_irda { sa_family_t sir_family; char sir_name[25]; IrLmpSAPType sir_lsap; IrLapDeviceAddrType sir_addr; };
Fields
-
sir_family
- The IrDA address family; this must be set to AF_IRDA.
-
sir_name
- Provides a simplified interface to the IrDA stack's IAS query and IAS entry management functionality. If this field is non-null when the
sockaddr_irda
structure is passed tobind()
, the IrDA stack will add an IAS entry to the information base and associate it with the specified LSAP. The IAS entry's class will be the value of thesir_name
field, and the entry will contain a single attribute specifying the socket's LSAP selector. The attribute name will depend on the socket's protocol; for example, anIRPROTO_LMP
socket would be "IrDA:IrLMP:LsapSel
". - If the
sockaddr_irda
passed toconnect()
contains a non-nullsir_name
field, the IrDA stack will perform an IAS query to resolve the specified name into an LSAP identifier. A get-value-by-class query is used to perform the resolution; the value of thesir_name
field specifies which class to query, and the attribute name is based on the socket's protocol. If thesir_name
field is empty (the first character is '\0
'), the IrDA stack will simply connect to the remote LSAP specified by thesir_lsap
field. -
sir_lsap
- Specifies the LSAP the connection should use.
-
sir_addr
- Specifies the IrDA device address to which the connection is to be established.
IrDALib Functions
IASGetValueByClass Function
Purpose
Queries the Information Access Service (IAS) to find devices matching the specified query parameters.
Declared In
IAS.h
Prototype
status_t IASGetValueByClass( IASQueryType *ioQuery )
Parameters
-
↔ ioQuery
- A pointer to an
IASQueryType
structure describing the query to perform. On return, the structure is filled out with information about the results of the query.
Returns
errNone
if no error occurred; otherwise returns an appropriate error code.
IASRegisterObject Function
Purpose
Registers an IAS object into the handheld's IAS directory.
Declared In
IAS.h
Prototype
int32_t IASRegisterObject( int iSocket, const IASObjectType *iObject, Boolean iExclusive )
Parameters
-
→ iSocket
- The socket number of an IrDA socket with which to associate the new IAS service entry.
-
→ iObject
- The object to register into the IAS directory.
-
→ iExclusive
- Specify
true
to create an exclusive-access entry in the IAS directory.
Returns
Returns the object ID of the newly-registered IAS object. If the returned value is negative, it's an error code.
NOTE: An object ID is always in the range
0x0000
through 0xffff
, so it can be safely cast to a uint16_t
and passed to IASUnregisterObject()
as needed.
IASRegisterService Function
Purpose
Registers a service name in the handheld's IAS directory.
Declared In
IAS.h
Prototype
int32_t IASRegisterService( int iSocket, const char *iServiceClass, const uint8_t *iHintsBits, Boolean iExclusive )
Parameters
-
→ iSocket
- The socket number of an IrDA socket with which to associate the new IAS service entry.
-
→ iServiceClass
- The name of the service class to register with IAS.
-
→ iHintsBits
- Bits to be included in IrLMP's "IrLMPSupport" attribute in the new IAS entry.
-
→ iExclusive
- Specify
true
to create an exclusive-access entry in the IAS directory.
Returns
Returns the object ID of the newly-created IAS directory entry. If the returned value is negative, it's an error code.
NOTE: An object ID is always in the range
0x0000
through 0xffff
, so it can be safely cast to a uint16_t
and passed to IASUnregisterObject()
as needed.
IASUnregisterObject Function
Purpose
Unregisters an IAS object from the IAS directory.
Declared In
IAS.h
Prototype
status_t IASUnregisterObject( int iSocket, uint16_t iObjectID )
Parameters
-
→ iSocket
- The socket number of the IrDA service to be unregistered.
-
→ iObjectID
- The object ID of the service to unregister, as returned by either
IASRegisterObject()
orIASRegisterService()
.
IrDADiscoverDevices Function
Purpose
Discovers available IrDA devices within range of the handheld's IrDA transceiver.
Declared In
IrDALib.h
Prototype
status_t IrDADiscoverDevices( uint32_t *ioNumLogs, IrLmpDeviceInfoType *oLogs, Boolean *oCached )
Parameters
-
↔ ioNumLogs
- On input, this should point to an integer indicating the size of the
oLogs
array. On output, this value has been changed to indicate how many devices were successfully discovered. -
← oLogs
- Points to an array of
IrLmpDeviceInfoType
structures that the function will fill out with information about the discovered devices. -
← oCached
- On return, indicates whether the returned device list is from the cache (
true
) or a fresh discovery procedure (false
).
Returns
errNone
if no error. Otherwise an appropriate error code.
Comments
Discovery is performed through the IrLMP protocol module. If discovery is requested while an IrLAP link is established, IrLMP will return the results of the last discovery procedure, and oCached
will be set to true
. If there is not an established link, IrDADiscoverDevices()
will perform a new discovery procedure and will return false
in the oCached
field.
Although the IrDA specification doesn't require it, the deviceInfo field in a discovery log usually contains the name of the IrDA device. On a Palm OS device, this is the HotSync® ID assigned by the user the first time the device is synchronized. This name is usually presented as a null-terminated string and is prefixed with a byte indicating the string's character set.