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

64    IR Library

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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:

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

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

IrConnect Struct ^TOP^

Purpose

The IrConnect structure is used to manage an IrLMP or Tiny TP connection.

Prototype

typedef struct _hconnect {
UInt8lLsap;
UInt8rLsap;
UInt8flags;
UInt8reserved;
IrCallBackcallBack;
IrPacket packet;
ListEntrypackets;
UInt16sendCredit;
UInt8availCredit;
UInt8dataOff;
} _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 ^TOP^

Purpose

The IrPacket structure is used for sending IrDA packets.

Prototype

typedef struct _IrPacket {
ListEntrynode;
UInt8*buff;
UInt16len;
IrConnect*origin;
UInt8headerLen;
UInt8header[14];
UInt8reserved;
} 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 ^TOP^

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;
UInt8len;
UInt8nAttribs;
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 ^TOP^

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 {
UInt8queryLen;
UInt8reserved;
UInt8*queryBuf;
UInt16resultBufSize;
UInt16resultLen;
UInt16listLen;
UInt16offset;
UInt8retCode;
UInt8overFlow;
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 ^TOP^

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 {
IrEventevent;
UInt8reserved1;
UInt8*rxBuff;
UInt16rxLen;
IrPacket*packet;
IrDeviceList*deviceList;
IrStatusstatus;
UInt8reserved2;
} 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 ^TOP^

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

IR Control Constants ^TOP^

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

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

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

LEVENT_DISCOVERY_CNF ^TOP^

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

LEVENT_LAP_CON_CNF ^TOP^

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

LEVENT_LAP_CON_IND ^TOP^

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

LEVENT_LAP_DISCON_IND ^TOP^

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

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

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

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

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

LEVENT_STATUS_IND ^TOP^

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

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

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

IrAdvanceCredit Function ^TOP^

Purpose

Advances the credit to the other side of the connection.

Declared In

IrLib.h

Prototype

void IrAdvanceCredit (
   IrConnect*con,
   UInt8credit
)

Parameters

con
Pointer to IrConnect structure representing connection to which credit is advanced.
credit
Amount of credit to advance.

Returns

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

Purpose

Obtains a local LSAP selector and registers the connection with the protocol stack.

Declared In

IrLib.h

Prototype

IrStatus IrBind (
   UInt16refNum,
   IrConnect*con,
   IrCallBackcallBack
)

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:

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

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 (
   UInt16refnum
)

Parameters

refnum
IR library refNum.

Returns

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

Purpose

Starts an IrLAP connection.

Declared In

IrLib.h

Prototype

IrStatus IrConnectIrLap (
   UInt16refNum,
   IrDeviceAddrdeviceAddr
)

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

Purpose

Requests an IrLMP or Tiny TP connection.

Declared In

IrLib.h

Prototype

IrStatus IrConnectReq (
   UInt16refNum,
   IrConnect*con,
   IrPacket*packet,
   UInt8credit
)

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.

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

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 (
   UInt16refNum,
   IrConnect*con,
   IrPacket*packet,
   UInt8credit
)

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 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.

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

Purpose

Sends a data packet.

Declared In

IrLib.h

Prototype

IrStatus IrDataReq (
   UInt16refNum,
   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().

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

Purpose

Disconnects an IrLAP connection.

Declared In

IrLib.h

Prototype

IrStatus IrDisconnectIrLap (
   UInt16refNum
)

Parameters

refnum
IR library refNum.

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

Purpose

Starts an IrLMP discovery process.

Declared In

IrLib.h

Prototype

IrStatus IrDiscoverReq (
   UInt16refNum,
   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 ^TOP^

Purpose

Determines if an IrLAP connection exists.

Declared In

IrLib.h

Prototype

BOOL IrIsIrLapConnected (
   UInt16refNum
)

Parameters

refnum
IR library refNum.

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

Purpose

Determines if the IR media is busy.

Declared In

IrLib.h

Prototype

BOOL IrIsMediaBusy (
   UInt16refNum
)

Parameters

refnum
IR library refNum.

Returns

true if IR media is busy, false otherwise.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIsNoProgress Function ^TOP^

Purpose

Determines if IrLAP is not making progress.

Declared In

IrLib.h

Prototype

BOOL IrIsNoProgress (
   UInt16refNum
)

Parameters

refnum
IR library refNum.

Returns

ture if IrLAP is not making progress, false otherwise.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrIsRemoteBusy Function ^TOP^

Purpose

Determines if IrLAP of the other device is busy.

Declared In

IrLib.h

Prototype

BOOL IrIsRemoteBusy (
   UInt16refNum
)

Parameters

refnum
IR library refNum.

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

Purpose

Sets the IrLAP local busy flag.

Declared In

IrLib.h

Prototype

void IrLocalBusy (
   UInt16refNum,
   BOOLflag
)

Parameters

refnum
IR library refNum.
flag
Value (true or false) to set for local busy flag of IrLAP.

Returns

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

Purpose

Returns the maximum size buffer that can be sent by the other device.

Declared In

IrLib.h

Prototype

UInt16 IrMaxRxSize (
   UInt16refNum,
   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 ^TOP^

Purpose

Returns the maximum size allowed for a transmit packet.

Declared In

IrLib.h

Prototype

UInt16 IrMaxTxSize (
   UInt16refNum,
   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 ^TOP^

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 (
   UInt16refnum,
   UInt32options
)

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

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

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

Returns nothing.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrSetConTypeTTP Function ^TOP^

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

Returns nothing.

Compatibility

Implemented only if 3.0 New Feature Set is present.

IrSetDeviceInfo Function ^TOP^

Purpose

Sets the XID info string used during discovery to the given string and length.

Declared In

IrLib.h

Prototype

IrStatus IrSetDeviceInfo (
   UInt16refNum,
   UInt8*info,
   UInt8len
)

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

Purpose

Requests a TEST command frame be sent in the NDM (Normal Disconnect Mode) state.

Declared In

IrLib.h

Prototype

IrStatus IrTestReq (
   UInt16refNum,
   IrDeviceAddrdevAddr,
   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.

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.

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

Purpose

Unbinds the IrConnect structure from the protocol stack, freeing its LSAP selector.

Declared In

IrLib.h

Prototype

IrStatus IrUnbind (
   UInt16refNum,
   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:

  • 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 and Macros ^TOP^

This section describes the following functions and macros related to IAS database:

IrIAS_Add Function ^TOP^

Purpose

Adds an IAS object to the IAS Database.

Declared In

IrLib.h

Prototype

IrStatus IrIAS_Add (
   UInt16refNum,
   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 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 Macro ^TOP^

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

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

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

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

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

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

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

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

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

Purpose

Moves the internal pointer to the next result item.

Declared In

IrLib.h

Prototype

UInt8 *IrIAS_Next (
   UInt16refNum,
   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 ^TOP^

Purpose

Makes an IAS query of the IAS database of another device.

Declared In

IrLib.h

Prototype

IrStatus IrIAS_Query (
   UInt16refNum,
   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 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 Function ^TOP^

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 (
   UInt16refNum,
   UInt8*name,
   UInt8len
)

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.

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

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

Returns nothing.

Compatibility

Implemented only if 3.0 New Feature Set is present.

Application-Defined Functions ^TOP^

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

IrIasQueryCallBack Function ^TOP^

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
)

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.

Returns

Returns nothing.