10 Beaming (Infrared Communication)

The Palm OS^® provides two levels of support for beaming, or infrared communication (IR):

• The Exchange Manager provides a high-level interface that handles all of the communication details transparently.
  
  
• The IR Library provides a low-level, direct interface to the IR communications capabilities of the Palm OS. It is designed for applications that want more direct access to the IR capabilities than the exchange manager provides.
  

This chapter discusses these two facilities for IR communication.

Exchange Manager

The Palm OS exchange manager provides a simple interface for Palm OS applications to send and receive typed data from any number of remote devices and protocols. The device at the remote end of a connection does not need to know it is talking to a Palm OS device. The exchange manager can be used with industry standard protocols and data formats. The burden of understanding the protocols and data formats is on the Palm OS application using the exchange manager.

The exchange manager was developed to provide a facility by which Palm OS applications could communicate directly with external devices and foreign data formats, without having to be tied to the HotSync^® mechanism and conduits. In the increasingly complex world of the Internet, wireless communications, and infrared communications, it cannot be expected that all these modes of communication must support HotSync and provide the appropriate conduits on the other end. The Palm OS device must be able to deal directly with foreign data formats since there will not be conduits on the remote end to prepare the data. The data may also be sent without regard to the version or even the existence of particular software on the device.

Overview

The exchange manager is designed as a generic communications facility by which typed data objects can be sent and received. It is designed to support a variety of underlying transport mechanisms. Currently, the exchange manager supports only the IR (beaming) capability of the Palm III^™ and later devices (and upgraded PalmPilot^™ devices).

---

NOTE:  

When used for IR communication, the exchange manager uses the OBEX IrDA protocol. The only level of OBEX supported currently is for the Put operation. The Palm III can act as both a client and a server.

---

The exchange manager API provides a mechanism for exchanging typed data objects between applications. An object is a stream of bytes with some information about its contents attached. The content information includes a creator ID, a MIME data type, and a filename. An application that wants to send data using the exchange manager must provide at least one of these pieces of information. An application that is able to receive an object registers itself with the exchange manager (ExgRegisterData) and specifies what data types and file extensions it can accept.

A key data structure used by the exchange manager is the ExgSocketType data type. This exchange socket structure defines information about the connection and the type of data to be exchanged. When you are sending data, you must supply this structure with the appropriate information filled in. When you are receiving, this structure gives you information about the connection and the incoming data. (Note that the use of the term "socket" in the exchange manager API is not related to the term "socket" as used in sockets communication programming.)

---

NOTE:  

The current implementation of the IR library does not send data type information, but it may do so in the future. It is recommended that you write information for the data type field of the socket, but do not expect to receive type information. Instead, use a filename including the extension to identify content. When registering, register for a file extension.

---

Exchange Manager and Launch Codes

When receiving incoming data, the exchange manager communicates with applications via launch codes. The exchange manager sends an application a series of three launch codes when it receives data for it. These are:

• sysAppLaunchCmdExgAskUser
  
  
• sysAppLaunchCmdExgReceiveData
  
  
• sysAppLaunchCmdGoto
  

The exchange manager sends the first launch code, sysAppLaunchCmdExgAskUser, when it has determined that incoming data is destined for a particular application (based on which application has registered to receive data of that type). This launch code lets the application tell the exchange manager whether or not to display a dialog asking the user if they want to accept the data. If the application chooses not to handle this launch command, the default course of action is that the exchange manager displays a dialog asking the user if they want to accept the incoming data. In most cases, applications won't need to handle this launch code, since the default action is the preferred alternative.

Palm OS 3.5 and higher provide an alternative version of the dialog that displays a category pop-up list so that users can file the incoming data at the same time it is received. The pop-up list is only displayed if you handle the launch code and call ExgDoDialog directly. See that function's description in the Palm OS SDK Reference for more information.

The application can respond to this launch code by setting the result field in the parameter block to the appropriate value. If it wants to allow the exchange manager to display a dialog, it should leave the result field set to exgAskDialog (the default value). To disable display of the dialog and to automatically accept the incoming data (as if the user had pressed OK in the dialog), set the result field to exgAskOk. To disable display of the dialog and to automatically reject the incoming data (as if the user had pressed Cancel in the dialog), set the result field to exgAskCancel. In the later case, the data is discarded and no further action is taken by the exchange manager.

If the application sets the result field to exgAskOk, or the dialog is displayed and the user presses the OK button, then the exchange manager sends the application the next launch code, sysAppLaunchCmdExgReceiveData, so that it can actually receive the data. This launch code notifies the application that it should receive the data.

The application should use the exchange manager functions ExgAccept, ExgReceive, and ExgDisconnect to receive the data and store it or do whatever it needs to with the data.

The parameter block sent with this launch code is of the ExgSocketPtr data type. It is a pointer to the ExgSocketType structure corresponding to the exchange manager connection via which the data is arriving. You will need to pass this pointer to the ExgAccept function to begin receiving the data. Note that in the socket structure, the length field may not be accurate, so in your receive loop you should be flexible in handling more or less data than length specifies.

After you have finished receiving the data and before you return from the PilotMain routine, you must set up the goToCreator and goToParams fields in the socket structure. Set in the goToCreator field the creator ID of the application that should be launched to view the received data (normally the same application that received the data). If no application should be launched, then set this to NULL. Set in the goToParams structure information that identifies the record to go to when the application is launched. It is recommended that you use a unique ID to identify the record, rather than the record index, since indexes might change. You can put unique ID information into the goToParams.matchCustom field.

Note that the application may not be the active application, and thus may not have globals available when it is launched with this launch code. Be sure to check if you have globals available and don't try to access them if they are not available. In addition, if the application has multiple code segments, you cannot access code outside of segment 0 (the first segment) if the application is launched with this launch code.

Assuming that everything has proceeded normally, the exchange manager again launches the application identified in the goToCreator field of the socket structure with the sysAppLaunchCmdGoto launch code. This allows the user to view the received item.

IR Library

The IR (InfraRed) library is a shared library that provides a direct interface to the IR communications capabilities of the Palm OS. It is designed for applications that want more direct access to the IR capabilities than the exchange manager provides.

The IR support provided by the Palm OS is compliant with the IrDA specifications. IrDA (Infrared Data Association), is an industry body consisting of representatives from a number of companies involved in IR development. For a good introduction to the IrDA standards, see the IrDA web site at:

http://www.IrDA.org.

IrDA Stack

The IrDA stack comprises a number of protocol layers, of which some are required and some are optional. The complete stack looks something like Figure 10.1.

Figure 10.1 IrDA Protocol Stack

The SIR/FIR layer is purely hardware. The SIR (Serial IR) layer supports speeds up to 115k bps while the FIR (Fast IR) layer supports speeds up to 4M bps. IrLAP is the IR Link Access Protocol that provides a data pipe between IrDA devices. IrLMP, the IR Link Management Protocol, manages multiple sessions using the IrLAP. Tiny TP is a lightweight transfer protocol on which some higher-level IrDA layers are built.

One or more of SIR/FIR must be implemented, and Tiny TP, IrLMP and IrLAP must also be implemented. IrComm provides serial and parallel port emulation over an IR link and is optional (it is not currently supported in the Palm OS). IrLAN provides an access point to Local Area Network protocol adapters. It too is optional (and is not supported in the Palm OS).

OBEX is an object exchange protocol that can be used (for instance) to transfer business cards, calendar entries or other objects between devices. It too is optional and is supported in the Palm OS. The capabilities of OBEX are made available through the exchange manager; there is no direct API for it.

The Palm OS implements all the required protocol layers (SIR, IrLAP, IrLMP, and Tiny TP), as well as the OBEX layer, to support the Exchange Manager. Palm III devices provide SIR (Serial IR) hardware supporting the following speeds: 2400, 9600, 19200, 38400, 57600, and 115200 bps. The software (IrOpen) currently limits bandwidth to 57600 bps by default, but you can specify a connection speed of up to 115200 bps if desired.

The stack is capable of connection-based or connectionless sessions.

IrLMP Information Access Service (IAS) is a component of the IrLMP protocol that you will see mentioned in the interface. IAS provides a database service through which devices can register information about themselves and retrieve information about other devices and the services they offer.

Accessing the IR Library

Before you can use the IR library, you must obtain a reference number for it by calling the function SysLibFind, as in this example:

err = SysLibFind(irLibName, &refNum);

This function returns the library reference number in the refNum parameter. This parameter is passed to most of the other functions in the IR library.

Summary of Beaming