To manage infra-red communications and add beaming features to
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
Who does what?
In a nutshell, here's how beaming works. On the sender's side:
- user initiates beaming by tapping a button, menu item, shortcut...
- sender initializes an ExgSocketType
structure with the right values (creator ID, packet size, description,
- sender calls ExgPut() passing the
socket as an argument
- sender calls ExgSend() passing
the socket and data packet as arguments
- sender checks return code and lets user know about beaming status
- sender calls ExgDisconnect() passing
the socket as an argument
On the receiver's side, things are a bit more tricky:
- Ask user
- on receiving device, Palm OS launches the application with
a sysAppLaunchCmdExgAskUser launch
- the app may prompt the receiving user whether s/he accepts
- usually, you let Palm reply "OK" for you, or you
implicitly return exgAskOk
- 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()
- Show data
- Palm OS launches the app with a sysAppLaunchCmdGoTo
- your app may display the data, do a beeeeeeeep, flash a
smiley, play your country's anthem or keep quiet
Download the ZIP file.
This app shows how to do basic beam I/O. You need another pocket
device or desktop with beaming capabilities.
- add ID MainBeamBtn with a value of your choice
- same for ID MainClearBtn
- same for ID MainStatus
- 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):
TITLE "You just received 1 record"
MESSAGE "Id: ^1\n" \
"Name: ^2\n" \
- add ICON "beam.bmp" and SMALLICON "beamsmall.bmp"
- add LAUNCHERCATEGORY with an ID of 1000 and literal that equals
- 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
socket.goToCreator = CreatorID; // use same application on target
for the GoTo launch code
socket.localMode = 0; // data will be sent to remote device, not
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,
- in MainFormHandleEvent() add call to BeamRecord()
- same in AppHandleEvent(), case MainRecordBeamCmd
- in PilotMain, add ((ExgAskParamPtr)cmdPBP)->result
- a bit further, declare this:
ExgSocketPtr pSocket = (ExgSocketPtr)cmdPBP;
- call ExgAccept(pSocket)
- call ExgReceive(pSocket, &buffer, sizeof(buffer),
- 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!
Here's the ZIP file.
And here's how the app should like: