Objective

To manage infra-red communications and add beaming features to an application.

 Concepts

To beam or not to beam?

In order to beam data, you need two devices: a sender and a receiver. In this tutorial, we will deal with Palm OS Exchange Manager, which provides the developer with high-level APIs. You won't have to set up low level parameters, open ports, yada yada yada.

Who does what?

In a nutshell, here's how beaming works. On the sender's side:

1. user initiates beaming by tapping a button, menu item, shortcut...
2. sender initializes an ExgSocketType structure with the right values (creator ID, packet size, description, file name...)
3. sender calls ExgPut() passing the socket as an argument
4. sender calls ExgSend() passing the socket and data packet as arguments
5. sender checks return code and lets user know about beaming status
6. sender calls ExgDisconnect() passing the socket as an argument

On the receiver's side, things are a bit more tricky:

1. Ask user
   • on receiving device, Palm OS launches the application with a sysAppLaunchCmdExgAskUser launch code
   • the app may prompt the receiving user whether s/he accepts incoming data
   • usually, you let Palm reply "OK" for you, or you implicitly return exgAskOk
2. Receive incoming data
   • provided you accepted incoming data, Palm OS relaunches the app with a sysAppLaunchCmdExgReceiveData launch code and passes an ExgSocketPtr
   • receiver invokes ExgAccept() on this socket
   • receiver invokes ExgReceive() on this socket and a local buffer, and checks return code to inform user
   • receiver does an ExgDisconnect() on socket
3. Show data
   • Palm OS launches the app with a sysAppLaunchCmdGoTo launch code
   • your app may display the data, do a beeeeeeeep, flash a smiley, play your country's anthem or keep quiet

 Exercise

Download the ZIP file.

This app shows how to do basic beam I/O. You need another pocket device or desktop with beaming capabilities.

In beaming.h:

• add ID MainBeamBtn with a value of your choice
• same for ID MainClearBtn
• same for ID MainStatus

In beaming.rcp:

• we forgot to include something...
• add labels for name, ID, description and quantity
• add fields for those same guys
• in ReceivedDataAlert, add this chunk of code that pops up an alert form to which you pass 3 arguments (ID, name, quantity):
  INFORMATION
  BEGIN
    TITLE "You just received 1 record"
    MESSAGE "Id: ^1\n" \
    "Name: ^2\n" \
    "Quantity: ^3"
    BUTTONS "Ok"
  END
• add ICON "beam.bmp" and SMALLICON "beamsmall.bmp"
• add LAUNCHERCATEGORY with an ID of 1000 and literal that equals "Tutorial"

In beaming.c:

• hey... looks like we also forgot to include something here...
• define CreatorID as 'TuBe' (beware single quotes, not double)
• define ExtensionID as "TUT" (this one will tell Palm OS that if it receives some TUT data, then it's for our app)
• define Filename as "Beaming.tut" (it'll be the default filename on target device)
• declare socket like ExgSocketType socket;
• in BeamRecord(), initialize our socket with this:
  MemSet(&socket, sizeof(socket), 0); // let's zero it up!
  socket.target = CreatorID; // target application
  socket.count = 1; // just 1 object
  socket.length = sizeof(record); // how many bytes to send per object
  socket.goToCreator = CreatorID; // use same application on target for the GoTo launch code
  socket.localMode = 0; // data will be sent to remote device, not local
  socket.packetMode = 0; // connected mode
  socket.noGoTo = 0; // we want the GoTo to be executed when testing in local mode
  socket.description = GetField(MainForm, MainName); // will display while device is beaming, to inform user
  socket.name = filename; // filename on target device (try to beam from this app to a desktop ;)
• add call to ExgPut: ExgPut(&socket)
• add call to ExgSend: ExgSend(&socket, &record, sizeof(record), &err) != sizeof(record)
• add call to ExgDisconnect: ExgDisconnect(&socket, err)
• in MainFormHandleEvent() add call to BeamRecord()
• same in AppHandleEvent(), case MainRecordBeamCmd
• in PilotMain, add ((ExgAskParamPtr)cmdPBP)->result = exgAskOk;
• a bit further, declare this:
  ExgSocketPtr pSocket = (ExgSocketPtr)cmdPBP;
  FakeRecordType buffer;
• call ExgAccept(pSocket)
• call ExgReceive(pSocket, &buffer, sizeof(buffer), &err)
• call ExgDisconnect(pSocket, err)
• a bit further, add that to display data: FrmCustomAlert(ReceivedDataAlert, StrIToA(str, buffer.ID), buffer.name, StrIToA(str2, buffer.quantity));
  

Your all set. Make the app, run it, populate fields with data, beam'em out, check on receiving device. If it's a Palm, data will automagically appear on screen. If it's a PC, you'll get a file called "beaming.tut" on your desktop or any folder related to IR exchanges. If it's a Pocket PC, it should be in "My Documents".

For the fun of it, try to beam data back from the target device to check the receive API!

 Solution

Here's the ZIP file.

And here's how the app should like:

Next topic