Infrared

Infrared is a wireless data connection that uses infrared radiation as the physical bearer. Series 60 support for infrared is provided through an implementation of the IrDA protocol stack. IrDA is an example of "directed" infrared ”meaning that it is a point-to-point communications system, offering secure transmission and receipt of data and requiring the communicating devices to have a line-of-sight connection. The connection range is limited ”the IrDA standard specifies that a range of up to 1m must be supported, but many devices do exceed this capability.

IrDA Stack

Before looking in detail at the Series 60 implementation of IrDA, this subsection briefly outlines the role of the various layers of the IrDA stack. You should note that although implementation of some of the protocols is optional, Series 60 does support all of them. The layers of the IrDA stack are shown in Figure 9-3.

Figure 9-3. The IrDA protocol stack.

The physical layer of the stack specifies the optical characteristics and deals with the encoding of data. The Link Access Protocol (IrLAP) layer provides reliable data transfer over the physical layer. It ensures that either data is safely delivered or else, if not, the protocols higher up the stack are informed so that they can take appropriate action. Note that as the success of a transaction is dependent upon the physical line of sight between devices being maintained , failure can be fairly common. The Link Management Protocol (IrLMP) provides multiple-session support, enabling multiple clients to run over a single IrLAP link. It is also responsible for high-level device discovery and provides the Information Access Service ( IAS ) , often termed the "yellow pages," of services available for incoming connections. Conflicts in addressing are also resolved at this level.

The two main jobs carried out by the Tiny Transport Protocol (IrTinyTP) layer are flow control, at the IrLMP level, and data stream segmentation and reassembly. Flow control is important to allow the multiplexing capabilities of the IrLMP layer to be used, as it allows each IrLMP connection to stop its data stream without interfering with other clients. Sending large streams of data across a connection is not desirable, as a failure means the whole lot will have to be resent . By breaking the data into smaller chunks before sending, efficiency can be improved. Error checking is performed on each segment, with segments being resent if necessary. The receiving device is able to reassemble the constituent parts to produce the original stream ”the technical term for this is Segmentation And Reassembly ( SAR ) .

At the top of the stack are protocols to deal with specific situations. The Infrared OBject EXchange (IrOBEX) protocol is designed to facilitate the exchange of simple objects via IR. It is commonly used to exchange vCard and vCal files ( open file formats for transferring business cards and calendar entries, respectively, between diverse devices). This standard is well defined and details what a packet should contain to enable two devices to communicate. The Infrared Communications (IrCOMM) protocol emulates both the serial and parallel ports and was designed as a legacy protocol for use by existing applications. Its use is not encouraged for new applications, as it hides some of the useful features of the lower protocols, such as negotiation of parameters. Infrared Local Area Network (IrLAN) , as the name suggests, enables a device to connect to a local network using infrared.

Further information on the IrDA protocol stack and infrared communication, in general, can be found at http://www.irda.org.

Programming Infrared on a Series 60 Device

The earlier sections of this chapter concerning Serial Communication and Sockets programming cover most of the practical basics of infrared programming. It is recommended that you read them before continuing with this section.

Whether you use the IrDA Sockets API or the IrDA Serial API, the general concepts are the same ”namely: loading a protocol, discovery, connection, transfer of data and disconnection. Examples of using both APIs were covered in the sections mentioned above, so rather than repeat this information here, this subsection just summarizes the important points and adds further details as required.

Other methods of infrared communication, specifically using the protocols IrTranP and IrOBEX, will also be described in this section.

IrDA Sockets API

The Sockets section in this chapter describes the Sockets API for Series 60, using the IrTinyTP protocol in its example application ”refer to that section for more detailed coverage of infrared sockets.

IrTinyTP is a connection-oriented protocol which is commonly used for infrared sockets programming. Series 60 provides sockets support for another infrared protocol, IrMUX . This is a connectionless protocol ”in other words, it does not provide guaranteed or ordered delivery of data packets. This is much less useful over infrared, and so is far less commonly used. Its use is not fully covered here. However, if you wish to use IrMUX, you need to start by loading the appropriate protocol module instead of IrTinyTP, as follows :

 _LIT(KProtocol, "Irmux"); TProtocolDesc protocolInfo; User::LeaveIfError(socketServ.FindProtocol(KProtocol, protocolInfo)); 

Pay close attention to the string being passed in here to specify the IrMUX protocol. Specifying "IrMUX" (with the last three letters in uppercase) will not work ”it has to be specified exactly as shown here.

IAS Queries

One important component of the IrDA API that has not yet been discussed is the Information Access Service (IAS) database. This can be viewed as an advertising service for all the IrDA-capable applications on a device. Applications register themselves with the IAS, and then, by interrogating this database, other devices can determine whether they are interested in what is on offer.

In Series 60, the RNetDatabase class implements the IAS database, and entries take the form of a TIASDatabaseEntry . The following code sets the attributes for a particular entry and then adds it to the IAS database:

 _LIT8(KIrClassName, "com:emcc:ir:IRTest"); _LIT8(KIrAttributeName, "IrDA:TinyTP:LsapSel"); iIASEntry.SetClassName(KIrClassName); iIASEntry.SetAttributeName(KIrAttributeName); iIASEntry.SetToInteger(iListenSocket.LocalPort()); TInt ret = iNetDatabase.Add(iIASEntry); if (ret != KErrNone && ret != KErrAlreadyExists)    {    User::Leave(ret);    } 

There are a few points you should note here. First, the class name must be unique within the database, so you should bear that in mind when you are choosing it. SetToInteger() sets the response type as an integer and should be set to the port number of your listening socket. Also, you should open the database before you try to add your entry to it, and you must also check whether the attempted addition was successful.

To query the database of another device, you need to construct a query using the TIASQuery class and then interrogate the database.

 // TIASResponse iResponse; defined in member data. TIASQuery query(KIrClassName, KIrAttributeName, GetRemoteDevAddr()); iNetDatabase.Query(query, iResponse, iStatus); 

The TIASQuery takes the class name and attribute parameters set when constructing the TIASEntry , and also the address of the remote device (a TUInt ). Querying the database is performed asynchronously. You pass through a TIASResponse object that, on return, will have been populated . If the query completes successfully, the value of iStatus will be KErrNone . A value of KErrBadName means the class name was not present. KErrUnknown signifies that the class was present but not the attribute.

The value stored in TIASResponse will depend upon the response type set in the database entry. In the above example, response.Type() would return EIASDataInteger . The port number could then be retrieved using response.GetInteger().

IrDA Serial API

Series 60 allows you to treat the IR port as a serial port and use the APIs that relate to serial programming to perform transactions over infrared. The Serial Communication section of this chapter describes in detail the steps to take, so you should read that information and look at the IrSerial application.

IrTranP

The IrTranP protocol was introduced to handle the transfer of digital images and as such is obviously relevant to Series 60. As yet, however, only the ability to receive digital images is supported by Series 60.

Implementation of the protocol is through the CTranpSession class, with the abstract class MTRanpNotification providing an observer mechanism. To use the API, you need to create your own notification class, derived from MTRanpNotification , and implement all of the callback functions.

The general sequence of events when receiving a picture is as follows:

1. The notification object is created.

2. The CTranpSession object is created and the notification object registered.

3. The device is put into receive mode through a call to CTranpSession::Get() .

4. The remote device makes a connection. You will be notified through the callback function MTRanpNotification::Connected() .

5. The remote device sends the picture. You will be updated on the progress of the transaction through repeated calls to MTRanpNotification::ProgressIndication() and then, when the picture has been fully received, a call to MtranpNotification::GetComplete() .

6. The connection is broken. You will be notified through a call to MtranpNotification::Disconnected() .

7. The appropriate clean-up is performed.

IrOBEX

The IrOBEX protocol is designed for the exchange of objects ”for example, vCard and vCal objects. This protocol is supported in Series 60 by the OBEX Client/Server framework. Although a detailed description of IrOBEX is beyond the scope of the book, some of the implementation details are introduced here.

The classes CObexServer and CObexClient represent the OBEX server and OBEX client, respectively. OBEX is not exclusive to infrared communication, so when you construct these objects you need to specify the protocol you wish to use. The class TObexIrProtocolInfo should be used for this purpose, specifying the class name and the attribute name of the service you are interested in. For the default OBEX server use " OBEX " and " IrDA:TinyTP:LsapSel ".

The interface MObexServerNotify should also be implemented, so that notification of server events, such as connection and error occurrence, is received. Functions on the client and server are called to perform the transactions, with the data being transported using sockets.

The objects that can be transported using this protocol are of type CObexBaseObject . Specialized classes are also defined ”namely, CObexNullObject (for use if only headers are required), CObexFileObject and CObexBufObject.