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

9    IrDA Reference

Low-Level Communications

Exploring Palm OS®

IrDA Constants ^TOP^

IASAttribTypeType Enum ^TOP^

Purpose

Define IAS attribute types.

Declared In

IAS.h

Constants

Constant

Definition

iasAttribMissing

The attribute is missing.

iasAttribInteger

The attribute is an integer.

iasAttribOctetString

The attribute is a string of bytes.

iasAttribUserString

The attribute is a user string.

IASCharSetType Enum ^TOP^

Purpose

Define character sets supported by IAS.

Declared In

IAS.h

Constants

Constant

Definition

iasCharSetASCII

ASCII.

iasCharSetISO8859_1

ISO 8859-1.

iasCharSetISO8859_2

ISO 8859-2.

iasCharSetISO8859_3

ISO 8859-3.

isaCharSetISO8859_4

ISO 8859-4.

isaCharSetISO8859_5

ISO 8859-5.

isaCharSetISO8859_6

ISO 8859-6.

isaCharSetISO8859_7

ISO 8859-7.

isaCharSetISO8859_8

ISO 8859-8.

isaCharSetISO8859_9

ISO 8859-9.

isaCharSetUnicode

Unicode.

IrDA Protocol Identifier Constants ^TOP^

Purpose

Define IrDA protocols when using the Sockets API.

Declared In

IrDA.h

Constants

Constant

Definition

IRPROTO_LAP

The IrLAP protocol.

IRPROTO_LMP

The IrLMP protocol.

IRPROTO_TTP

The TinyTP protocol.

IrDA Socket Address Family Constant ^TOP^

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 ^TOP^

Purpose

Define values for the discovery method specified in the IrLmpDeviceInfoType structure.

Declared In

IrDA.h

Constants

Constant

Definition

irLmpSniffing

The device was discovered while it was performing an IrLAP sniffing procedure, which is a special low-power discovery procedure.

irLmpActiveDiscovery

The device was discovered during an IrLAP discovery procedure initiated by the current device.

irLmpPassiveDiscovery

The device was discovered as the result of an IrLAP discovery procedure initiated by the discovered device.

IAS Constants ^TOP^

Purpose

Constants pertaining to IAS.

Declared In

IAS.h

Constants

Constant

Definition

iasMaxAttribNameLen

The maximum number of characters in an IAS attribute's name.

iasMaxClassNameLen

The maximum number of characters in an IAS object's class name.

iasMaxOctetStringLen

The maximum number of bytes in an octet-string IAS attribute.

iasMaxUserStringLen

The maximum number of characters in an IAS user-string attribute.

setsockopt() commands ^TOP^

Purpose

Define IrDA-specific setockopt() commands.

Declared In

IrDA.h

Constants

Constant

Definition

SO_IRIDLE

Invokes the LM_Idle.Request.

SO_IREXCLUSIVE

Invokes the LM_AccessMode.Request.

SO_IRMTU

Gets the MTU for the socket.

SO_IRMRU

Sets or gets the socket's MRU.

Special IrDA Device Addresses ^TOP^

Purpose

Define special-purpose IrDA device addresses.

Declared In

IrDA.h

Constants

Constant

Definition

IRADDR_ANY

Refers to any available device.

IRADDR_BROADCAST

The IrDA device broadcast address.


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 ^TOP^

Purpose

Describe Service Access Points (SAPs) to which connection-oriented sockets can be bound.

Declared In

IrDA.h

Constants

Constant

Definition

irLsapIAS

The IAS query management interface.

irLsapUnitdata

The Unitdata interface.

irLsapAny

Any SAP.

IrDA Data Types and Structures ^TOP^

IASAttribValueType Typedef ^TOP^

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. The length field indicates the number of bytes in the attribute string, and bytes is the string itself.
userString
The value of the attribute if it's of type iasAttribUserString. The charSet field indicates an IASCharSetType value specifying the character set in which the string is defined, length indicates the length of the string in bytes (not characters), and chars is a length-byte long array containing the string itself.

IASObjectType Struct ^TOP^

Purpose

Describes an IAS object.

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 ^TOP^

Purpose

Describes an IAS query.

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 or IRADDR_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 ^TOP^

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 ^TOP^

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 ^TOP^

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

IrLmpSAPType

sockaddr_irda Struct ^TOP^

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 to bind(), 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 the sir_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, an IRPROTO_LMP socket would be "IrDA:IrLMP:LsapSel".
If the sockaddr_irda passed to connect() contains a non-null sir_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 the sir_name field specifies which class to query, and the attribute name is based on the socket's protocol. If the sir_name field is empty (the first character is '\0'), the IrDA stack will simply connect to the remote LSAP specified by the sir_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 ^TOP^

IASGetValueByClass Function ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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() or IASRegisterService().

IrDADiscoverDevices Function ^TOP^

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.


NOTE: IrLMP will never find more than six devices, so you don't need to look for more than that.

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.