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 and Macros
- 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 Struct
Purpose
The IrConnect
structure is used to manage an IrLMP or Tiny TP connection.
Prototype
typedef struct _hconnect {
UInt8 lLsap;
UInt8 rLsap;
UInt8 flags;
UInt8 reserved;
IrCallBack callBack;
IrPacket
packet;
ListEntry packets;
UInt16 sendCredit;
UInt8 availCredit;
UInt8 dataOff;
} _hconnect;
Fields
-
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 Struct
Purpose
The IrPacket
structure is used for sending IrDA packets.
Prototype
typedef struct _IrPacket { ListEntry node; UInt8 *buff; UInt16 len; IrConnect *origin; UInt8 headerLen; UInt8 header[14]; UInt8 reserved; } IrPacket;
Fields
-
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 Struct
Purpose
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.
Prototype
typedef struct _IrIasObject { UInt8 *name; UInt8 len; UInt8 nAttribs; IrIasAttribute *attribs; } IrIasObject;
Fields
-
name
- Pointer to name of object.
-
len
- Length of object name.
-
nAttribs
- Number of attributes.
-
attribs
- Pointer to an array of attributes.
IrIasQuery Struct
Purpose
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()
.
Prototype
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;
Fields
-
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 Struct
Purpose
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.
Prototype
typedef struct {
IrEvent event;
UInt8 reserved1;
UInt8 *rxBuff;
UInt16 rxLen;
IrPacket
*packet;
IrDeviceList *deviceList;
IrStatus status;
UInt8 reserved2;
} IrCallBackParms;
Fields
-
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 Struct
Purpose
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.
Prototype
typedef struct { UInt16 recLineErrors; UInt16 crcErrors; } IrStatsType;
Fields
-
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.
Returns |
||
|
||
Re-enables beaming after an |
||
This operation differs from |
||
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 |
||
|
Sets the possible baud rates that the IR Library will use to those specified in |
|
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 |
||
If you change the baud rate, your changes are until the device is reset or you perform this operation again. |
||
If the specified value is |
||
If |
||
Temporarily disables beam receive. This operation keeps track of the number of requests that beaming be disabled and re-enables beaming (through |
||
This operation differs from |
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 therxBuff
andrxLen
fields. -
IR_STATUS_FAILED
indicates that no TEST response was received. The packet passed to perform the test command is passed back in thepacket
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 Function
Purpose
Advances the credit to the other side of the connection.
Declared In
IrLib.h
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.
Returns
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 Function
Purpose
Obtains a local LSAP selector and registers the connection with the protocol stack.
Declared In
IrLib.h
Prototype
IrStatus IrBind ( UInt16 refNum, IrConnect *con, IrCallBack callBack )
Parameters
-
→
refnum
- IR library refNum.
-
↔
con
- Pointer to
IrConnect
structure. -
→
callBack
- Pointer to a callBack function that handles the indications and confirmation from the protocol stack.
Returns
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:
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 Function
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.
Declared In
IrLib.h
Prototype
Err IrClose ( UInt16 refnum )
Parameters
Returns
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 Function
Purpose
Declared In
IrLib.h
Prototype
IrStatus IrConnectIrLap ( UInt16 refNum, IrDeviceAddr deviceAddr )
Parameters
-
→
refnum
- IR library refNum.
-
→
deviceAddr
- 32-bit address of device to which connection should be made.
Returns
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 Function
Purpose
Requests an IrLMP or Tiny TP connection.
Declared In
IrLib.h
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. TherLsap
field must contain the LSAP selector for the peer on the other device. Also the type of the connection must be set. UseIR_SetConTypeLMP
to set the type to an IrLMP connection orIR_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 theLEVENT_PACKET_HANDLED
event if no errors occur. The maximum size of the packet isIR_MAX_CON_PACKET
for an IrLMP connection orIR_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.
Returns
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 Function
Purpose
Accepts an incoming connection that has been signaled by way of the callback with the event LEVENT_LM_CON_IND
.
Declared In
IrLib.h
Prototype
IrStatus IrConnectRsp ( UInt16 refNum, IrConnect *con, IrPacket *packet, UInt8 credit )
Parameters
-
→
refnum
- IR library refNum.
-
→
con
- Pointer to
IrConnect
structure. -
→
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 theLEVENT_PACKET_HANDLED
event if no errors occur. The maximum size of the packet isIR_MAX_CON_PACKET
for an IrLMP connection orIR_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.
Returns
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 Function
Purpose
Declared In
IrLib.h
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 withIrMaxTxSize()
.
Returns
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 Function
Purpose
Disconnects an IrLAP connection.
Declared In
IrLib.h
Prototype
IrStatus IrDisconnectIrLap ( UInt16 refNum )
Parameters
Returns
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 Function
Purpose
Starts an IrLMP discovery process.
Declared In
IrLib.h
Prototype
IrStatus IrDiscoverReq ( UInt16 refNum, IrConnect *con )
Parameters
-
→
refnum
- IR library refNum.
-
→
con
- Pointer to a bound
IrConnect
structure.
Returns
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 Function
Purpose
Determines if an IrLAP connection exists.
Declared In
IrLib.h
Prototype
BOOL IrIsIrLapConnected ( UInt16 refNum )
Parameters
Returns
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 Function
Purpose
Determines if the IR media is busy.
Declared In
IrLib.h
Prototype
BOOL IrIsMediaBusy ( UInt16 refNum )
Parameters
Returns
true
if IR media is busy, false
otherwise.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIsNoProgress Function
Purpose
Determines if IrLAP is not making progress.
Declared In
IrLib.h
Prototype
BOOL IrIsNoProgress ( UInt16 refNum )
Parameters
Returns
ture
if IrLAP is not making progress, false
otherwise.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIsRemoteBusy Function
Purpose
Determines if IrLAP of the other device is busy.
Declared In
IrLib.h
Prototype
BOOL IrIsRemoteBusy ( UInt16 refNum )
Parameters
Returns
ture
if IrLAP of the other device is busy, false
otherwise.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrLocalBusy Function
Purpose
Sets the IrLAP local busy flag.
Declared In
IrLib.h
Prototype
void IrLocalBusy ( UInt16 refNum, BOOL flag )
Parameters
Returns
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 Function
Purpose
Returns the maximum size buffer that can be sent by the other device.
Declared In
IrLib.h
Prototype
UInt16 IrMaxRxSize ( UInt16 refNum, IrConnect *con )
Parameters
-
→
refnum
- IR library refNum.
-
→
con
- Pointer to
IrConnect
structure that represents an active connection.
Returns
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 Function
Purpose
Returns the maximum size allowed for a transmit packet.
Declared In
IrLib.h
Prototype
UInt16 IrMaxTxSize ( UInt16 refNum, IrConnect *con )
Parameters
-
→
refnum
- IR library refNum.
-
→
con
- Pointer to
IrConnect
structure that represents an active connection.
Returns
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 Function
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.
Declared In
IrLib.h
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.
Returns
Comments
The following flags can be specified for the options
parameter to set the speed of the connection:
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrSetConTypeLMP Function
Purpose
Sets the type of the connection to IrLMP. This function must be called after the IrConnect
structure is bound to the stack.
Declared In
IrLib.h
Prototype
void IrSetConTypeLMP ( IrConnect *con )
Parameters
-
→
con
- Pointer to
IrConnect
structure.
Returns
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrSetConTypeTTP Function
Purpose
Sets the type of the connection to Tiny TP. This function must be called after the IrConnect
structure is bound to the stack.
Declared In
IrLib.h
Prototype
void IrSetConTypeTTP ( IrConnect *con )
Parameters
-
→
con
- Pointer to
IrConnect
structure.
Returns
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrSetDeviceInfo Function
Purpose
Sets the XID info string used during discovery to the given string and length.
Declared In
IrLib.h
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
.
Returns
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 Function
Purpose
Requests a TEST command frame be sent in the NDM (Normal Disconnect Mode) state.
Declared In
IrLib.h
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 isIR_MAX_TEST_PACKET
. Even if no data is to be sent, a valid packet must be passed.
Returns
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.
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 Function
Purpose
Unbinds the IrConnect
structure from the protocol stack, freeing its LSAP selector.
Declared In
IrLib.h
Prototype
IrStatus IrUnbind ( UInt16 refNum, IrConnect *con )
Parameters
-
→
refnum
- IR library refNum.
-
→
con
- Pointer to
IrConnect
structure to unbind.
Returns
IR_STATUS_SUCCESS
means the operation completed successfully.
IR_STATUS_FAILED
means the operation failed for one of the following reasons:
Compatibility
Implemented only if 3.0 New Feature Set is present.
IAS Functions and Macros
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 Function
Purpose
Adds an IAS object to the IAS Database.
Declared In
IrLib.h
Prototype
IrStatus IrIAS_Add ( UInt16 refNum, IrIasObject *obj )
Parameters
-
→
refnum
- IR library refNum.
-
→
obj
- Pointer to an
IrIASObject
structure.
Returns
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 exceedsIR_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 Macro
Purpose
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.)
Declared In
IrLib.h
Prototype
#define IrIAS_GetInteger ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Integer value returned as a UInt32
.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetIntLsap Macro
Purpose
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.
Declared In
IrLib.h
Prototype
#define IrIAS_GetIntLsap ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Integer value returned as a UInt8
.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetObjectID Macro
Purpose
Return the unique object ID of the current result item.
Declared In
IrLib.h
Prototype
#define IrIAS_GetObjectID ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Returns the object ID as a UInt16
type.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetOctetString Macro
Purpose
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.)
Declared In
IrLib.h
Prototype
#define IrIAS_GetOctetString ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Pointer to octet string of type UInt8
.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetOctetStringLen Macro
Purpose
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.)
Declared In
IrLib.h
Prototype
#define IrIAS_GetOctetStringLen ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Length of octet string returned as a UInt16
.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetType Macro
Purpose
Return the type of the current result item.
Declared In
IrLib.h
Prototype
#define IrIAS_GetType ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
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 Macro
Purpose
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.)
Declared In
IrLib.h
Prototype
#define IrIAS_GetUserString ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Pointer to result string of type UInt8
.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetUserStringCharSet Macro
Purpose
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.)
Declared In
IrLib.h
Prototype
#define IrIAS_GetUserStringCharSet ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Character set returned as an IrCharSet
value.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_GetUserStringLen Macro
Purpose
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.)
Declared In
IrLib.h
Prototype
#define IrIAS_GetUserStringLen ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
Length of user string returned as a UInt8
value.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_Next Function
Purpose
Moves the internal pointer to the next result item.
Declared In
IrLib.h
Prototype
UInt8 *IrIAS_Next ( UInt16 refNum, IrIasQuery *token )
Parameters
-
→
refnum
- IR library refNum.
-
→
token
- Pointer to an
IrIasQuery
structure.
Returns
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 Function
Purpose
Makes an IAS query of the IAS database of another device.
Declared In
IrLib.h
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.
Returns
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 oftoken
is 0. - The
resultBufSize
field oftoken
is 0. - The
callback
field oftoken
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 inqueryBuf
. The length must not exceedIR_MAX_QUERY_LEN
.
Compatibility
Implemented only if 3.0 New Feature Set is present.
IrIAS_SetDeviceName Function
Purpose
Sets the value
field of the device name attribute of the "Device" object in the IAS database.
Declared In
IrLib.h
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. Thisvalue
field should be a constant and the pointer must remain valid untilIrIAS_SetDeviceName
is called with another pointer. -
→
len
- Total length of the
value
field. Maximum size allowed isIR_MAX_IAS_ATTR_SIZE
.
Returns
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 Macro
Purpose
Put the internal pointer to the start of the result buffer.
Declared In
IrLib.h
Prototype
#define IrIAS_StartResult ( t )
Parameters
-
→
t
- Pointer to an
IrIasQuery
structure.
Returns
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 Function
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.
Declared In
IrLib.h
Prototype
void IrIasQueryCallBack ( IrStatus status )