The IR (InfraRed) library is a shared library that provides a direct interface to the IR communications capabilities of the Palm OS®. This chapter provides reference material for the IR library API:
IR Library Data Structures
IR Library Constants
IR Stack Callback Events
IR Library Functions
IAS Functions
Application-Defined Functions
The header file irlib.h declares the IR library API. For more information on the IR library, see the chapter "Beaming (Infrared Communication)" in the Palm OS Programmer's Companion, vol. II, Communications.
IR Library Data Structures

This section lists some of the more important data types used by the IR library functions.
IrConnect

The IrConnect structure is used to manage an IrLMP or Tiny TP connection.
typedef struct _hconnect {
UInt8 lLsap;
UInt8 rLsap;
UInt8 flags;
UInt8 reserved;
IrCallBack callBack;
IrPacket packet;
ListEntry packets;
UInt16 sendCredit;
UInt8 availCredit;
UInt8 dataOff;
} _hconnect;
Field Descriptions
lLsap |
The local LSAP on which this connection listens. |
rLsap |
The LSAP assigned to the remote side. |
flags |
For system use only. |
reserved |
Reserved for future use. |
callBack |
Pointer to callback function. For system use only. |
packet |
For system use only. |
packets |
List of packets to send. |
sendCredit |
Amount of credit from peer. |
availCredit |
Amount of credit to give to peer. |
dataOff |
Amount of data less than IrLAP size. |
IrPacket

The IrPacket structure is used for sending IrDA packets.
typedef struct _IrPacket {
ListEntry node;
UInt8 *buff;
UInt16 len;
IrConnect* origin;
UInt8 headerLen;
UInt8 header[14];
UInt8 reserved;
} IrPacket;
Field Descriptions
node |
For system use only. |
buff |
Pointer to the send data buffer. |
len |
Number of bytes in data buffer. |
origin |
Pointer to connection that owns the packet. For system use only. |
headerLen |
Number of bytes contained in the header. For system use only. |
header |
Storage for header. For system use only. |
reserved |
Reserved for future use. |
IMPORTANT: The node field must be the first field in the structure. It is used internally by the stack.
IrIASObject

The IrIASObject structure is used as storage for an IAS object managed by the local IAS server. An object of this type is passed as the obj parameter to the IrIAS_Add function.
typedef struct _IrIasObject {
UInt8 *name;
UInt8 len;
UInt8 nAttribs;
IrIasAttribute* attribs;
} IrIasObject;
Field Descriptions
name |
Pointer to name of object. |
len |
Length of object name. |
nAttribs |
Number of attributes. |
attribs |
Pointer to an array of attributes. |
IrIasQuery

The IrIasQuery structure is used to perform IAS queries. The IrIasQuery object is passed as the token parameter to functions such as IrIAS_Query and IrIAS_Next.
typedef struct _IrIasQuery {
UInt8 queryLen;
UInt8 reserved;
UInt8 *queryBuf;
UInt16 resultBufSize;
UInt16 resultLen;
UInt16 listLen;
UInt16 offset;
UInt8 retCode;
UInt8 overFlow;
UInt8 *result;
IrIasQueryCallBack callBack;
} _IrIasQuery;
Field Descriptions
queryLen |
Total length of the query. |
reserved |
Reserved for future use. |
queryBuf |
Pointer to buffer containing the query. |
resultBufSize |
Size of the result buffer. |
resultLen |
Actual number of bytes in the result buffer. |
listLen |
Number of items in the result list. |
offset |
Offset into the results buffer. |
retCode |
Return code of operation. |
overFlow |
Set to true if result exceeded result buffer size. |
result |
Pointer to buffer containing result. |
callBack |
Pointer to query callback function. |
IrCallbackParms

The IrCallbackParms structure is used to pass information from the stack to the upper layer of the stack (application). Not all fields are valid at any given time. The type of event determines which fields are valid. The IrCallbackParms object is passed as the second parameter to the IrCallback function.
typedef struct {
IrEvent event;
UInt8 reserved1;
UInt8 *rxBuff;
UInt16 rxLen;
IrPacket* packet;
IrDeviceList* deviceList;
IrStatus status;
UInt8 reserved2;
} IrCallBackParms;
Field Descriptions
event |
Event causing the callback. |
reserved1 |
Reserved for future use. |
rxBuff |
Received data buffer. |
rxLen |
Length of data in received buffer. |
packet |
Pointer to packet being returned. |
deviceList |
Pointer to discovery device list. |
status |
Status of stack. |
reserved2 |
Reserved for future use. |
IrStatsType

The IrStatsType structure defines performance statistics for the IR Library. Use the ExgControl function with an irGetStatistics operation to retrieve these statistics. See IR Control Constants for more information.
typedef struct {
UInt16 recLineErrors;
UInt16 crcErrors;
} IrStatsType;
Field Descriptions
recLineErrors |
The number of serial errors since the library opened. |
crcErrors |
The number of CRC errors since the library opened. |
IR Library Constants

IR Control Constants

The IR control constants define operations that the IR Exchange Library can perform. You pass these constants as the operation parameter to ExgControl. The following table lists the operation constants, the data that should be passed as the valueP parameter to ExgControl, and what operation is performed in response.
Operation Constant |
value Data Type |
Description |
irGetScanningMode |
Boolean. Output only. |
Returns true in *valueP if beaming is enabled or false if beaming is disabled. |
irGetStatistics |
IrStatsType. Output only. |
Returns performance statistics. |
irRestoreScanning |
None |
Re-enables beaming after an irSuppressScanning operation. This operation keeps track of the number of requests that beaming be disabled and re-enables beaming only when the count reaches 0. |
|
|
This operation differs from irSetScanningMode in that it does not update the saved preferences. |
irSetScanningMode |
Boolean. Input only. |
Enables or disables beaming.
This operation modifies the saved preferences database, which is back up during a HotSync® operation. Because of this, beaming may remain disabled after a reset if you use this operation to disable it. If you want to temporarily disable beaming use irSuppressScanning and irRestoreScanning instead. |
irSetBaudMask |
UInt16 containing a mask of the irOpenOptSpeed... constants defined in IrLib.h. Input only. |
Sets the possible baud rates that the IR Library will use to those specified in *valueP. OR the irOpenOptSpeed... constants together to specify more than one. The default rate is 0, which causes the baud rate to be determined by the hardware. |
|
|
This operation is sometimes useful for debugging connections. Generally, you should set all bits up to the fastest rate you want to allow. To reset, use this operation again and pass 0 in *valueP. |
|
|
If you change the baud rate, your changes are until the device is reset or you perform this operation again. |
irSetSerialMode |
Boolean. Input only. |
If the specified value is true, the IR Library uses the serial port instead of the infrared port until the device is reset. This option is useful for debugging. You can run your application in POSE and use the IR Library to communicate with a device connected in the cradle. |
irSetSupported |
Boolean. Input only. |
If true, IR is supported on this device. If false, IR is not supported. You can use this constant to disable the unsupported dialog that normally displays when a beam is attempted and no IR support is available. |
irSuppressScanning |
None |
Temporarily disables beam receive. This operation keeps track of the number of requests that beaming be disabled and re-enables beaming (through irRestoreScanning) only when the count reaches 0. |
|
|
This operation differs from irSetScanningMode in that it does not update the saved preferences. |
IR Stack Callback Events

The IR stack calls the application by way of a callback function stored in each IrConnect structure. The callback function is called with a pointer to the IrConnect structure and a pointer to a parameter structure. The parameter structure contains an event field, which indicates the reason the callback is called, and other parameters, which have meaning based on the event.
The meaning of the events is described in the following sections.
LEVENT_DATA_IND

Data has been received. The received data is accessed using fields rxBuff and rxLen.
LEVENT_DISCOVERY_CNF

Indicates the completion of a discovery operation. The field deviceList points to the discovery list.
LEVENT_LAP_CON_CNF

The requested IrLAP connection has been made successfully. The callback function of all bound IrConnect structures is called.
LEVENT_LAP_CON_IND

Indicates that the IrLAP connection has come up. The callback of all bound IrConnect structures is called.
LEVENT_LAP_DISCON_IND

Indicates that the IrLAP connection has gone down. This means that all IrLMP connections are also down. A callback with event LEVENT_LM_CON_IND is not given. The callback function of all bound IrConnect structures is called.
LEVENT_LM_CON_CNF

The requested IrLMP/Tiny TP connection has been made successfully. Connection data from the other side is found using fields rxBuff and rxLen.
LEVENT_LM_CON_IND

Other device has initiated a connection. IrConnectRsp should be called to accept the connection. Any data associated with the connection request can be found using fields rxBuff and rxLen, data pointer and length, respectively.
LEVENT_LM_DISCON_IND

The IrLMP/Tiny TP connection has been disconnected. Any data associated with the disconnect indication can be found using fields rxBuff and rxLen, data pointer and length, respectively.
LEVENT_PACKET_HANDLED

A packet is being returned. A pointer to the packet exists in field packet.
LEVENT_STATUS_IND

Indicates that a status event from the stack has occurred. The status field indicates the status generating the event. Possible status values are as follows:
IR_STATUS_NO_PROGRESS which means that IrLAP has no progress for 3 seconds threshold time (for example, the beam is blocked).
IR_STATUS_LINK_OK which indicates that the no progress condition has cleared.
IR_STATUS_MEDIA_NOT_BUSY which indicates that the IR media has transitioned from busy to not busy.
LEVENT_TEST_CNF

Indicates that a TEST command has completed. The status field indicates if the test was successful.
IR_STATUS_SUCCESS indicates that the operation was successful and the data in the test response can be found by using the rxBuff and rxLen fields.
IR_STATUS_FAILED indicates that no TEST response was received. The packet passed to perform the test command is passed back in the packet field and is now available (no separate packet handled event occurs).
LEVENT_TEST_IND

Indicates that a TEST command frame has been received. A pointer to the received data is in rxBuff and rxLen. A pointer to the packet that is sent in response to the test command is in the packet field. The packet is currently set up to respond with the same data sent in the command TEST frame. If different data is desired as a response, then you need to modify the packet structure. This event is sent to the callback function in all bound IrConnect structures. The IAS connections ignore this event.
IR Library Functions

IrAdvanceCredit

Purpose
Advances the credit to the other side of the connection.
Prototype
void IrAdvanceCredit (IrConnect* con, UInt8 credit)
Parameters
--> con | Pointer to IrConnect structure representing connection to which credit is advanced. |
--> credit | Amount of credit to advance. |
Result
Returns nothing.
Comments
The credit passed by this function is added to the existing available credit, which must not exceed 127. This function only makes sense for a Tiny TP connection.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrBind

Purpose
Obtains a local LSAP selector and registers the connection with the protocol stack.
Prototype
IrStatus IrBind (UInt16 refNum, IrConnect* con, IrCallBack callBack)
Parameters
--> refnum | IR library refNum. |
--> callBack | Pointer to a callBack function that handles the indications and confirmation from the protocol stack. |
Result
IR_STATUS_SUCCESS means the operation completed successfully. The assigned LSAP can be found in con->lLsap.
IR_STATUS_FAILED means the operation failed for one of the following reasons:
con is already bound to the stack.
There is no room in the connection table.
Comments
The IrConnect structure is re-initialized. Any values stored in the structure are lost. The assigned LSAP is returned in the lLsap field of con. The type of the connection is set to IrLMP. The IrConnect must be bound to the stack before it can be used.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrClose

Purpose
Closes the IR library. This releases the global memory for the IR stack and any system resources it uses. This must be called when an application is done with the IR library.
Prototype
Err IrClose (UInt16 refnum)
Parameters
--> refnum | IR library refNum. |
Result
Returns 0 if successful.
Comments
Do not call this function unless the call to IrOpen was successful.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrConnectIrLap

Purpose
Starts an IrLAP connection.
Prototype
IrStatus IrConnectIrLap (UInt16 refNum, IrDeviceAddr deviceAddr)
Parameters
--> refnum | IR library refNum. |
--> deviceAddr | 32-bit address of device to which connection should be made. |
Result
IR_STATUS_PENDING means the operation started successfully; the result is returned by way of a callback.
IR_STATUS_MEDIA_BUSY means the operation failed because the media is busy. Media busy is caused by one of the following reasons:
Other devices are using the IR medium.
An IrLAP connection already exists.
A discovery process is in progress.
Comments
The result is signaled to all bound IrConnect structures by way of the callback function. The callback event is LEVENT_LAP_CON_CNF if successful or LEVENT_LAP_DISCON_IND if unsuccessful.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrConnectReq

Purpose
Requests an IrLMP or Tiny TP connection.
Prototype
IrStatus IrConnectReq (UInt16 refNum, IrConnect* con, IrPacket* packet, UInt8 credit)
Parameters
--> refnum | IR library refNum. |
--> con | Pointer to IrConnect structure for handling the connection. The rLsap field must contain the LSAP selector for the peer on the other device. Also the type of the connection must be set. Use IR_SetConTypeLMP to set the type to an IrLMP connection or IR_SetConTypeTTP to set the type to a Tiny TP connection. |
--> packet | Pointer to a packet that contains connection data. Even if no connection data is needed, the packet must point to a valid IrPacket structure. The packet is returned by way of the callback function with the LEVENT_PACKET_HANDLED event if no errors occur. The maximum size of the packet is IR_MAX_CON_PACKET for an IrLMP connection or IR_MAX_TTP_CON_PACKET for a Tiny TP connection. |
--> credit | Initial amount of credit advanced to the other side. Must be less than 127. It is ANDed with 0x7f, so if it is greater than 127, unexpected results occur. This parameter is ignored if the connection is an IrLMP connection. |
Result
IR_STATUS_PENDING means the operation has been started successfully and the result is returned by way of the callback function with the event LEVENT_LM_CON_CNF if the connection is made or LEVENT_LM_DISCON_IND if connection fails. The packet is returned by way of the callback with the event LEVENT_PACKET_HANDLED.
IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.
The connection is busy (already involved in a connection).
The IrConnect structure is not bound to the stack.
The packet size exceeds maximum allowed.
IR_STATUS_NO_IRLAP means the operation failed because there is no IrLAP connection (the packet is available immediately).
Comments
The result is signaled by way of the callback specified in the IrConnect structure. The callback event LEVENT_LM_CON_CNF indicates that the connection is up and LEVENT_LM_DISCON_IND indicates that the connection failed. Before calling this function the fields in the con structure must be properly set.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrConnectRsp

Purpose
Accepts an incoming connection that has been signaled by way of the callback with the event LEVENT_LM_CON_IND.
Prototype
IrStatus IrConnectRsp (UInt16 refNum, IrConnect* con, IrPacket* packet, UInt8 credit)
Parameters
--> refnum | IR library refNum. |
--> packet | Pointer to a packet that contains connection data. Even if no connection data is needed, the packet must point to a valid IrPacket structure. The packet is returned by way of the callback with the LEVENT_PACKET_HANDLED event if no errors occur. The maximum size of the packet is IR_MAX_CON_PACKET for an IrLMP connection or IR_MAX_TTP_CON_PACKET for a Tiny TP connection. |
--> credit | Initial amount of credit advanced to the other side. Must be less than 127. It is ANDed with 0x7f, so if it is greater than 127, unexpected results occur. This parameter is ignored if the connection is an IrLMP connection. |
Result
IR_STATUS_PENDING means the operation has been started successfully and the packet is returned by way of the callback function with the event LEVENT_PACKET_HANDLED.
IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.
The connection is not in the proper state to require a response.
The IrConnect structure is not bound to the stack.
The packet size exceeds the maximum allowed.
IR_STATUS_NO_IRLAP means the operation failed because there is no IrLAP connection (the packet is available immediately).
Comments
IrConnectRsp can be called during the callback or later to accept the connection. The type of the connection must already have been set to IrLMP or Tiny TP before the LEVENT_LM_CON_IND event.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrDataReq

Purpose
Sends a data packet.
Prototype
IrStatus IrDataReq (UInt16 refNum, IrConnect* con, IrPacket* packet)
Parameters
--> refnum | IR library refNum. |
--> con | Pointer to IrConnect structure that specifies the connection over which the packet should be sent. |
--> packet | Pointer to a valid IrPacket structure that contains data to send. The packet should not exceed the maximum size found with IrMaxTxSize. |
Result
IR_STATUS_PENDING means the packet has been queued by the stack. The packet is returned by way of the callback with event LEVENT_PACKET_HANDLED.
IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.
The IrConnect structure is not bound to the stack.
The packet size exceeds the maximum allowed.
The IrConnect structure does not represent an active connection.
Comments
The packet is owned by the stack until it is returned by way of the callback with event LEVENT_PACKET_HANDLED. The largest packet that can be sent is found by calling IrMaxTxSize.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrDisconnectIrLap

Purpose
Disconnects an IrLAP connection.
Prototype
IrStatus IrDisconnectIrLap (UInt16 refNum)
Parameters
--> refnum | IR library refNum. |
Result
IR_STATUS_PENDING means the operation started successfully and all bound IrConnect structures are called back when complete.
IR_STATUS_NO_IRLAP means the operation failed because no IrLAP connection exists.
Comments
When the IrLAP connection goes down, the callback of all bound IrConnect structures is called with event LEVENT_LAP_DISCON_IND.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrDiscoverReq

Purpose
Starts an IrLMP discovery process.
Prototype
IrStatus IrDiscoverReq (UInt16 refNum, IrConnect* con)
Parameters
--> refnum | IR library refNum. |
--> con | Pointer to a bound IrConnect structure. |
Result
IR_STATUS_PENDING means the operation is started successfully; the result is returned by way of callback.
IR_STATUS_MEDIA_BUSY means the operation failed because the media is busy. Media busy is caused by one of the following reasons:
Other devices are using the IR medium.
A discovery process is already in progress.
An IrLAP connection exists.
IR_STATUS_FAILED means the operation failed because the IrConnect structure is not bound to the stack.
Comments
The result is signaled by way of the callback function specified in the IrConnect structure with the event LEVENT_DISCOVERY_CNF. Only one discovery can be invoked at a time.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIsIrLapConnected

Purpose
Determines if an IrLAP connection exists.
Prototype
BOOL IrIsIrLapConnected (UInt16 refNum)
Parameters
--> refnum | IR library refNum. |
Result
true if IrLAP is connected, false otherwise.
Comments
Only available if IR_IS_LAP_FUNCS is defined.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIsMediaBusy

Purpose
Determines if the IR media is busy.
Prototype
BOOL IrIsMediaBusy (UInt16 refNum)
Parameters
--> refnum | IR library refNum. |
Result
true if IR media is busy, false otherwise.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIsNoProgress

Purpose
Determines if IrLAP is not making progress.
Prototype
BOOL IrIsNoProgress (UInt16 refNum)
Parameters
--> refnum | IR library refNum. |
Result
ture if IrLAP is not making progress, false otherwise.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIsRemoteBusy

Purpose
Determines if IrLAP of the other device is busy.
Prototype
BOOL IrIsRemoteBusy (UInt16 refNum)
Parameters
--> refnum | IR library refNum. |
Result
ture if IrLAP of the other device is busy, false otherwise.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrLocalBusy

Purpose
Sets the IrLAP local busy flag.
Prototype
void IrLocalBusy (UInt16 refNum, BOOL flag)
Parameters
--> refnum | IR library refNum. |
--> flag | Value (true or false) to set for local busy flag of IrLAP. |
Result
Returns nothing.
Comments
If local busy is set to true, then the local IrLAP layer sends RNR (Receive Not Ready) frames to the other side indicating it cannot receive any more data. If the local busy is set to false, IrLAP is ready to receive frames.
The setting takes effect the next time IrLAP sends an RR (Receive Ready) frame. If IrLAP has data to send, the data is sent first, so it should be used carefully.
This function should not be used when using Tiny TP or when multiple connections exist.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrMaxRxSize

Purpose
Returns the maximum size buffer that can be sent by the other device.
Prototype
UInt16 IrMaxRxSize (UInt16 refNum, IrConnect* con)
Parameters
--> refnum | IR library refNum. |
--> con | Pointer to IrConnect structure that represents an active connection. |
Result
Returns the maximum size buffer that can be sent by the other device (maximum bytes that can be received). The value returned is only valid for active connections. The maximum size varies for each connection and is based on the negotiated IrLAP parameters and the type of the connection.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrMaxTxSize

Purpose
Returns the maximum size allowed for a transmit packet.
Prototype
UInt16 IrMaxTxSize (UInt16 refNum, IrConnect* con)
Parameters
--> refnum | IR library refNum. |
--> con | Pointer to IrConnect structure that represents an active connection. |
Result
Returns the maximum size allowed for a transmit packet. The value returned is only valid for active connections. The maximum size varies for each connection and is based on the negotiated IrLAP parameters and the type of the connection.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrOpen

Purpose
Opens the IR library. This allocates the global memory for the IR stack and reserves the system resources it requires. This must be done before any other IR library calls are made.
Prototype
Err IrOpen (UInt16 refnum, UInt32 options)
Parameters
--> refnum | IR library refNum. This value is returned from the function SysLibFind, which you must call first to load the IR library. |
--> options | Open options flags. See the Comments section for details. |
Result
Returns 0 if successful.
Comments
The following flags can be specified for the options parameter to set the speed of the connection:
irOpenOptSpeed115200 |
Set to maximum negotiated baud rate. |
irOpenOptSpeed57600 |
Set to 57600 bps (default if no flags given). |
irOpenOptSpeed9600 |
Set to 9600 bps. |
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrSetConTypeLMP

Purpose
Sets the type of the connection to IrLMP. This function must be called after the IrConnect structure is bound to the stack.
Prototype
void IrSetConTypeLMP (IrConnect* con)
Parameters
Result
Returns nothing.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrSetConTypeTTP

Purpose
Sets the type of the connection to Tiny TP. This function must be called after the IrConnect structure is bound to the stack.
Prototype
void IrSetConTypeTTP (IrConnect* con)
Parameters
Result
Returns nothing.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrSetDeviceInfo

Purpose
Sets the XID info string used during discovery to the given string and length.
Prototype
IrStatus IrSetDeviceInfo (UInt16 refNum, UInt8 *info, UInt8 len)
Parameters
--> refnum | IR library refNum. |
--> info | Pointer to array of bytes. |
--> len | Number of bytes pointed to by info. |
Result
IR_STATUS_SUCCESS means the operation is successful.
IR_STATUS_FAILED means the operation failed because info is too big.
Comments
The XID info string contains hints and the nickname of the device. The size cannot exceed IR_MAX_DEVICE_INFO bytes.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrTestReq

Purpose
Requests a TEST command frame be sent in the NDM (Normal Disconnect Mode) state.
Prototype
IrStatus IrTestReq (UInt16 refNum, IrDeviceAddr devAddr, IrConnect* con, IrPacket* packet)
Parameters
--> refnum | IR library refNum. |
--> devAddr | Address of device where TEST is sent. This address is not checked so it can be the broadcast address or 0. |
--> con | Pointer to IrConnect structure specifying the callback function to call to report the result. |
--> packet | Pointer to an IrPacket structure that contains the data to send in the TEST command packet. The maximum size data that can be sent is IR_MAX_TEST_PACKET. Even if no data is to be sent, a valid packet must be passed. |
Result
IR_STATUS_PENDING means the operation has been started successfully and the result is returned by way of the callback function with the event LEVENT_TEST_CNF. This is also the indication returning the packet.
IR_STATUS_FAILED means the operation failed because of one of the following reasons. Note that the packet is available immediately.
The IrConnect structure is not bound to the stack.
The packet size exceeds the maximum allowed.
IR_STATUS_MEDIA_BUSY means the operation failed because the media is busy or the stack is not in the NDM state (the packet is available immediately).
Comments
The result is signaled by way of the callback specified in the IrConnect structure. The callback event is LEVENT_TEST_CNF and the status field indicates the result of the operation. IR_STATUS_SUCCESS indicates success and IR_STATUS_FAILED indicates no response was received. A packet must be passed containing the data to send in the TEST frame. The packet is returned when the LEVENT_TEST_CNF event is given.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrUnbind

Purpose
Unbinds the IrConnect structure from the protocol stack, freeing its LSAP selector.
Prototype
IrStatus IrUnbind (UInt16 refNum, IrConnect* con)
Parameters
--> refnum | IR library refNum. |
--> con | Pointer to IrConnect structure to unbind. |
Result
IR_STATUS_SUCCESS means the operation completed successfully.
IR_STATUS_FAILED means the operation failed for one of the following reasons:
The IrConnect structure was not bound.
The lLsap field contained an invalid number.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IAS Functions

This section describes the following functions and macros related to IAS database:
IrIAS_Add
IrIAS_GetInteger
IrIAS_GetIntLsap
IrIAS_GetObjectID
IrIAS_GetOctetString
IrIAS_GetOctetStringLen
IrIAS_GetType
IrIAS_GetUserString
IrIAS_GetUserStringCharSet
IrIAS_GetUserStringLen
IrIAS_Next
IrIAS_Query
IrIAS_SetDeviceName
IrIAS_StartResult
IrIAS_Add

Purpose
Adds an IAS object to the IAS Database.
Prototype
IrStatus IrIAS_Add (UInt16 refNum, IrIasObject* obj)
Parameters
--> refnum | IR library refNum. |
Result
IR_STATUS_SUCCESS means the operation is successful.
IR_STATUS_FAILED means the operation failed for one of the following reasons:
There is no space in the database.
An entry with the same class name already exists.
The attributes of the object violate the IrDA Lite rules (attribute name exceeds IR_MAX_IAS_NAME, or attribute value exceeds IR_MAX_IAS_ATTR_SIZE).
The class name exceeds IR_MAX_IAS_NAME.
Comments
The object is not copied, so the memory for the object must exist for as long as the object is in the database. The IAS database is designed to allow only objects with unique class names, and it checks for this. Class names and attributes names must not exceed IR_MAX_IAS_NAME. Also, attribute values must not exceed IR_MAX_IAS_ATTR_SIZE.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetInteger

Purpose
Macro to return an integer value, assuming that the current result item is of type IAS_ATTRIB_INTEGER. (Call IrIAS_GetType to determine the type of the current result item.)
Prototype
IrIAS_GetInteger (t)
Parameters
Result
Integer value returned as a UInt32.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetIntLsap

Purpose
Macro to return an integer value that represents an LSAP, assuming that the current result item is of type IAS_ATTRIB_INTEGER. (Call IrIAS_GetType to determine the type of the current result item.) Usually integer values returned in a query are LSAP selectors.
Prototype
IrIAS_GetIntLsap (t)
Parameters
Result
Integer value returned as a UInt8.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetObjectID

Purpose
Macro to return the unique object ID of the current result item.
Prototype
IrIAS_GetObjectID (t)
Parameters
Result
Returns the object ID as a UInt16 type.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetOctetString

Purpose
Macro to return a pointer to an octet string, assuming that the current result item is of type IAS_ATTRIB_OCTET_STRING. (Call IrIAS_GetType to determine the type of the current result item.)
Prototype
IrIAS_GetOctetString (t)
Parameters
Result
Pointer to octet string of type UInt8.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetOctetStringLen

Purpose
Macro to return the length of an octet string, assuming that the current result item is of type IAS_ATTRIB_OCTET_STRING. (Call IrIAS_GetType to determine the type of the current result item.)
Prototype
IrIAS_GetOctetStringLen (t)
Parameters
Result
Length of octet string returned as a UInt16.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetType

Purpose
Macro to return the type of the current result item.
Prototype
IrIAS_GetType (t)
Parameters
Result
Type of result item, such as IAS_ATTRIB_INTEGER, IAS_ATTRIB_OCTET_STRING or IAS_ATTRIB_USER_STRING. The return value is of type UInt8.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetUserString

Purpose
Macro to return a pointer to a user string, assuming that the current result item is of type IAS_ATTRIB_USER_STRING. (Call IrIAS_GetType to determine the type of the current result item.)
Prototype
IrIAS_GetUserString (t)
Parameters
Result
Pointer to result string of type UInt8.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetUserStringCharSet

Purpose
Macro to return the character set of the user string, assuming that the current result item is of type IAS_ATTRIB_USER_STRING. (Call IrIAS_GetType to determine the type of the current result item.)
Prototype
IrIAS_GetUserStringCharSet (t)
Parameters
Result
Character set returned as an IrCharSet value.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetUserStringLen

Purpose
Macro to return the length of a user string, assuming that the current result item is of type IAS_ATTRIB_USER_STRING. (Call IrIAS_GetType to determine the type of the current result item.)
Prototype
IrIAS_GetUserStringLen (t)
Parameters
Result
Length of user string returned as a UInt8 value.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_Next

Purpose
Moves the internal pointer to the next result item.
Prototype
UInt8* IrIAS_Next (UInt16 refNum, IrIasQuery* token)
Parameters
--> refnum | IR library refNum. |
Result
Pointer to the next result item, or 0 if there are no more items.
Comments
This function returns a pointer to the start of the next result item. If the pointer is 0, then there are no more result items.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_Query

Purpose
Makes an IAS query of the IAS database of another device.
Prototype
IrStatus IrIAS_Query (UInt16 refNum, IrIasQuery* token)
Parameters
--> refnum | IR library refNum. |
--> token | Pointer to an IrIasQuery structure initialized as described in the Comments section. |
Result
IR_STATUS_SUCCESS means the operation is started successfully and the result is signaled by way of the callback function.
IR_STATUS_FAILED means the operation failed for one of the following reasons:
The query exceeds IR_MAX_QUERY_LEN.
The result field of token is 0.
The resultBufSize field of token is 0.
The callback field of token is 0.
A query is already in progress.
IR_STATUS_NO_IRLAP means the operation failed because there is no IrLAP connection.
Comments
An IrLAP connection must exist to the other device. The IAS query token must be initialized as described below. The result is signaled by calling the callback function whose pointer exists in the IrIasQuery structure. Only one query can be made at a time.
The IrIasQuery structure passed in the token parameter must be initialized as follows:
Assign a pointer to a callback function in which the result is signaled.
Set result to point to a buffer large enough to hold the result of the query.
Set resultBufSize to the size of the result buffer.
Set queryBuf to point to a valid query.
Set queryLen to the number of bytes in queryBuf. The length must not exceed IR_MAX_QUERY_LEN.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_SetDeviceName

Purpose
Sets the value field of the device name attribute of the "Device" object in the IAS database.
Prototype
IrStatus IrIAS_SetDeviceName (UInt16 refNum, UInt8 *name, UInt8 len)
Parameters
--> refnum | IR library refNum. |
--> name | Pointer to an IAS value field for the device name attribute of the device object. It includes the attribute type, character set and device name. This value field should be a constant and the pointer must remain valid until IrIAS_SetDeviceName is called with another pointer. |
--> len | Total length of the value field. Maximum size allowed is IR_MAX_IAS_ATTR_SIZE. |
Result
IR_STATUS_SUCCESS means the operation is successful.
IR_STATUS_FAILED means len is too big, or the value field is not a valid user string.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_StartResult

Purpose
Macro to put the internal pointer to the start of the result buffer.
Prototype
IrIAS_StartResult (t)
Parameters
Result
Returns nothing.
Compatibility
Implemented only if 3.0 New Feature Set is present.
Application-Defined Functions

The functions in this section are supplied by the developer and can be named anything.
IrIasQueryCallBack

Purpose
Signals the result of IAS query. The result of IAS queries is signaled by calling this callback function which is pointed to by the callBack field of the IrIasQuery structure.
Prototype
void IrIasQueryCallBack (IrStatus status)
Parameters
--> status | The status of the query operation. The following values can be passed: |
IR_STATUS_SUCCESS means the query operation finished successfully and the results can be parsed. |
IR_STATUS_DISCONNECT means the link or IrLMP connection was disconnected during the query, so the results are not valid. |
Result
Returns nothing.
|