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

63    Exchange Library

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

The Exchange Library API described in this chapter and declared in ExgLib.h specifies a minimal set of functions that all exchange libraries must implement. This chapter is directed towards developers who use or create exchange libraries. Developers creating an exchange library should also read the Exchange Libraries chapter of the Palm OS Programmer's Companion, vol. II, Communications.

Exchange Library Functions ^TOP^

ExgLibAccept Function ^TOP^

Purpose

Accept an incoming connection.

Declared In

ExgLib.h

Prototype

Err ExgLibAccept(
   UInt16 libRefnum,
   ExgSocketType *exgSocketP
)

Parameters

libRefnum
Reference number of this exchange library.
exgSocketP
A pointer to the socket structure (see ExgSocketType).

Returns

Returns errNone if no error. exgErrNotSupported is returned if a preview is in progress and the exchange library does not support preview. Other error codes are defined by each exchange library.

Comments

The Exchange Manager's ExgAccept() function simply calls ExgLibAccept in the exchange library identified by the ExgSocketType structure passed to ExgAccept. An application calls the Exchange Manager's ExgAccept function when:

  • The application wants to initiate a connection to receive data, which it does in response to sysAppLaunchCmdExgReceiveData.
  • The application wants to initiate a connection to receive a preview of the data, which it does in response to sysAppLaunchCmdExgAskUser.

Any implementation of ExgLibAccept should update any progress dialogs to indicate that data is being accepted (or received) into an application.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

ExgLibPut()

ExgLibClose Function ^TOP^

Purpose

Library-specific. Although this function is not called by the Exchange Manager, all shared libraries normally implement it.

Declared In

ExgLib.h

Prototype

Err ExgLibClose (
   UInt16 libRefnum
)

Parameters

libRefnum
Reference number of this exchange library.

Comments

Exchange libraries are free to implement this function for internal or external use. The Exchange Manager does not call it.

ExgLibConnect Function ^TOP^

Purpose

Open a connection in preparation for sending or receiving objects.

Declared In

ExgLib.h

Prototype

Err ExgLibConnect(
   UInt16 libRefNum,
   ExgSocketType *exgSocketP
)

Parameters

libRefNum
Reference number of this exchange library.
exgSocketP
A pointer to an ExgSocketType structure identifying the socket through which objects will be sent or received.

Returns

Returns errNone if no error. If ExgLibConnect is not supported by this library, this function returns exgErrNotSupported; if its use is optional, errNone is returned. Other error codes are defined by each exchange library.

Comments

The Exchange Manager may call this function to initiate a connection for sending multiple objects or for performing two-way communications. Some exchange libraries support sending multiple objects but do not support this call. See "Sending Multiple Objects" of Palm OS Programmer's Companion, vol. II, Communications for more information.

Not all exchange libraries support this operation. In this case, the first call to ExgLibPut() must clean up after itself before returning an error. The exchange library should not expect to get an ExgLibDisconnect() call.

If ExgLibConnect is supported and an application calls ExgConnect(), the exchange library should delay any cleanup until ExgLibDisconnect, unless ExgLibConnect returns an error, in which case it should clean up after itself. The library can expect to get an ExgLibDisconnect call if it returns errNone from ExgLibConnect. If the application does not call ExgConnect, the first call to ExgLibPut must clean up after itself before returning an error and the exchange library should not expect to get an ExgLibDisconnect call.

The Exchange Manager's ExgConnect function calls ExgLibConnect in the exchange library identified by the ExgSocketType structure passed to ExgConnect. If ExgLibConnect is implemented to return exgErrNotEnoughPower, the Exchange Manager puts up an alert, so there is no need for the exchange library to do so. Other error codes are not treated specially by the Exchange Manager; the exchange library must put up its own alerts when appropriate.

The exchange library may prompt the user for addressing information.

Compatibility

Implemented only if 4.0 New Feature Set is present.

ExgLibControl Function ^TOP^

Purpose

Supply information about the exchange library.

Declared In

ExgLib.h

Prototype

Err ExgLibControl(
   UInt16 libRefNum,
   UInt16 op,
   void *valueP,
   UInt16 *valueLenP
)

Parameters

libRefNum
Reference number of this exchange library.
op
The operation to perform.
valueP
An operation specific parameter. See comments below.
valueLenP
An operation specific parameter. See comments below.

Returns

Returns errNone if no error. exgErrNotSupported is returned if the specified operation is not supported by the exchange library. exgErrBadParam is returned if the parameters (valueP and valueLenP) are not appropriate for the operation. Additional error codes are defined by each exchange library.

Comments

ExgLibControl is a general purpose function that performs various minor operations based upon a selector. ExgMgr.h defines three selectors: exgLibCtlGetTitle, which should be supported by all exchange libraries, exgLibCtlGetVersion, and exgLibCtlGetPreview. Additional library-specific selectors should be numbered starting at exgLibCtlSpecificOp (0x8000).

Upon receiving exgLibCtlGetTitle, the exchange library must return a library title suitable for use in Exchange Manager dialogs. Exchange libraries that are built as applications should generally return their 'tAIN' resource as their title. Be sure that the title returned through valueP honors the maximum length specified in valueLenP.

An exchange library that implements the Palm OS 4.0 version of the Exchange Library API needn't do anything special upon receiving exgLibCtlGetVersion; it should simply return exgErrNotSupported. Otherwise, set valueP to a two-byte value indicating the API version number and return errNone. Note that a version number of zero corresponds to the Palm OS 4.0 version of the Exchange Library API.

The exgLibCtlGetPreview operation is used by the Exchange Manager to determine whether a given exchange library supports preview. The Exchange Manager assumes that an exchange library supports preview if the exchange library doesn't implement this operation. To indicate that a library does not support preview, set valueP to false and return errNone.

The Exchange Manager's ExgControl() function simply calls ExgLibControl in the exchange library identified by the ExgSocketType structure passed to ExgControl.

Compatibility

Implemented only if 4.0 New Feature Set is present.

ExgLibDisconnect Function ^TOP^

Purpose

Disconnect a connection made with ExgLibConnect(), ExgLibAccept(), ExgLibPut(), or ExgLibGet().

Declared In

ExgLib.h

Prototype

Err ExgLibDisconnect(
   UInt16 libRefnum,
   ExgSocketType *exgSocketP,
   Err error
)

Parameters

libRefnum
Reference number of this exchange library.
exgSocketP
A pointer to an ExgSocketType structure identifying the socket connection to be disconnected.
error
The current error state. Used to indicate why the connection is being broken, for example, user cancel or out of memory.

Returns

Typically the same error code passed in. However, this function may return an error even if errNone is passed in.

Comments

ExgLibDisconnect may be used to finish reading the data during a preview; in this case, the connection, if any, is not shut down.

Applications call ExgLibDisconnect when all data has been sent or the application wants to stop the send process. If the send data process is not completed, the caller should pass an error parameter indicating why the operation was stopped. ExgLibDisconnect is responsible for completing the operation and closing any communication ports if necessary. If data was buffered for sending in ExgLibSend, then the disconnect process may actually perform the entire transmit operation. It is important to note that the ExgLibDisconnect function can be called for an ExgLibPut, ExgLibAccept or ExgLibGet function. So it is equally important to keep track of the current operation in the ExgSocketType. If dialogs are displayed, this function must update them as appropriate. If there are errors, ExgLibDisconnect should display them (if allowed by the application).

If ExgLibConnect() is not supported, the first call to ExgLibPut() must clean up after itself before returning an error and the exchange library should not expect to get an ExgLibDisconnect call.

If ExgLibConnect is supported and an application calls ExgConnect(), the exchange library should delay any cleanup until ExgLibDisconnect, unless ExgLibConnect returns an error, in which case it should clean up after itself. The library can expect to get an ExgLibDisconnect call if it returns errNone from ExgLibConnect. If the application does not call ExgConnect, the first call to ExgLibPut must clean up after itself before returning an error and the exchange library should not expect to get an ExgLibDisconnect call.

The Exchange Manager's ExgDisconnect() function simply calls ExgLibDisconnect in the exchange library identified by the ExgSocketType structure passed to ExgDisconnect.

Compatibility

Implemented only if 4.0 New Feature Set is present.

ExgLibGet Function ^TOP^

Purpose

Establish a connection and request data from a remote device.

Declared In

ExgLib.h

Prototype

Err ExgLibGet(
   UInt16 libRefNum,
   ExgSocketType *exgSocketP
)

Parameters

libRefNum
Reference number of this exchange library.
exgSocketP
A pointer to the socket structure (see ExgSocketType).

Returns

Returns errNone if no error. exgErrNotSupported is returned if this operation is not supported by this library. Other error codes are defined by each exchange library.

Comments

ExgLibGet informs the library that it should make a connection to the remote device and request information from it. When an exchange library's ExgLibGet function is called, it should fetch the requested data and prepare to deliver it when the application calls ExgReceive(). After ExgLibReceive() is called, possibly more than once, ExgLibDisconnect() follows.

The Exchange Manager's ExgGet() function calls ExgLibGet in the exchange library identified in the ExgSocketType structure passed to ExgGet. If an exchange library's implementation of ExgLibGet returns exgErrNotEnoughPower, the Exchange Manager puts up an alert, so there is no need for the exchange library to do so. Other error codes are not treated specially by the Exchange Manager; an exchange library must put up its own alerts when appropriate.

Compatibility

Implemented only if 4.0 New Feature Set is present.

ExgLibHandleEvent Function ^TOP^

Purpose

Handle exchange-library-specific events.

Declared In

ExgLib.h

Prototype

Boolean ExgLibHandleEvent(
   UInt16 libRefnum,
   void *eventP
)

Parameters

libRefnum
Reference number of this exchange library.
eventP
The event to handle.

Returns

Returns true if the event was handled.

Comments

Exchange libraries are free to implement this function for internal or external use. The Exchange Manager does not call it.

ExgLibOpen Function ^TOP^

Purpose

Library-specific. Although this function is not called by the Exchange Manager, all shared libraries normally implement it.

Declared In

ExgLib.h

Prototype

Err ExgLibOpen (
   UInt16 libRefnum
)

Parameters

libRefnum
Reference number of this exchange library.

Comments

Exchange libraries are free to implement this function for internal or external use. The ExgLibDisconnect does not call it.

ExgLibPut Function ^TOP^

Purpose

Signals the start of an object to be transferred to the destination device.

Declared In

ExgLib.h

Prototype

Err ExgLibPut(
   UInt16 libRefnum,
   ExgSocketType *exgSocketP
)

Parameters

libRefnum
Reference number of this exchange library.
exgSocketP
Pointer to the socket structure (see ExgSocketType).

Returns

Returns errNone if no error. Error codes are defined by each exchange library.

Comments

Opens a connection if necessary. The actual data should be sent using ExgLibSend() after which the connection should be shut down with ExgLibDisconnect(). The exchange library may prompt the user for addressing information.

The first time this library is called, it may be necessary to allocate global variables and perform other initialization steps. It is usually a good idea to keep any state information about the open connection in the socketRef field of the exgSocketP structure. This data can then be passed to subsequent operations on that socket.

ExgLibPut should then check if the socketRef field of exgSocketP has been initialized. In some cases, an application may already have filled socketRef with addressing information. The use of socketRef is entirely up to the exchange library. If socketRef is empty, the exchange library needs to fill in any addressing information. In order to do this, the exchange library needs to open its own dialog asking the user for whatever addressing information would be appropriate.

Exchange libraries are responsible for any validation of data entered in the addressing dialog and may use Address Book lookup or other system features to improve the user experience.

Once the user has completed addressing and confirmed the dialog, the exchange library should, in general, call the Progress Manager to open a progress dialog that remains open during the entire put operation. The progress dialog should not be opened if the noStatus option was passed or if the transaction is in asynchronous mode.

If the exchange library is displaying dialogs, it must also look for events and pass them to the Progress Manager.

Other operations within ExgLibPut depend on the exchange library. The exchange library may open communications ports and establish remote links at this time. Or it may just open a stream for buffering data until a later operation. If any errors occur in this process, the exchange library is responsible for removing any progress dialogs and returning an error. If displaying progress, the exchange library may also need to display an error using the Progress Manager before returning.


NOTE: The progress dialog is converted to an error dialog and waits until the user dismisses it. This may occur in ExgLibPut or later in ExgLibDisconnect(). It depends on whether the connection was made in ExgLibPut or whether it used an existing connection made by a previous call to ExgLibConnect or ExgLibPut.

The first call to ExgLibPut() must clean up after itself before returning an error if one of the following conditions exists:

  • If ExgLibConnect() is not supported.
  • If ExgLibConnect is supported and an application does not call ExgLibConnect.

The Exchange Manager's ExgPut() function calls ExgLibPut in the exchange library identified by the ExgSocketType structure passed to ExgPut. If ExgLibPut returns exgErrNotEnoughPower, the Exchange Manager puts up an alert, so there is no need for the exchange library to do so. Other error codes are not treated specially by the Exchange Manager; an exchange library must put up its own alerts when appropriate.

Compatibility

Implemented only if 4.0 New Feature Set is present.

ExgLibReceive Function ^TOP^

Purpose

Receive data from a remote device.

Declared In

ExgLib.h

Prototype

UInt32 ExgLibReceive(
   UInt16 libRefNum,
   ExgSocketType *exgSocketP,
   void *bufP,
   UInt32 bufSize,
   Err *errP
)

Parameters

libRefNum
Reference number of this exchange library.
exgSocketP
A pointer to the socket structure (see ExgSocketType).
bufP
A pointer to a buffer into which the data is put.
bufSize
The size of the buffer in bytes.
errP
The error code result: errNone if no error. exgErrNotSupported is returned if used during a preview and the exchange library does not support preview or if there appears to be more data available but ExgLibReceive cannot obtain it.Error codes are defined by each exchange library.

Returns

The number of bytes received. Returns 0 if the object is complete. ExgLibReceive blocks until at least one byte is available or the object is complete.

Comments

Use after ExgLibGet() or ExgLibAccept() to receive the contents of the object. May be used after ExgLibAccept to examine the contents during a preview.

ExgLibReceive must update any progress dialogs to indicate that data is being received. The ExgLibReceive should fill the buffer passed as much as possible and return the actual number of bytes that were stored in the buffer. ExgLibReceive must block for at least one byte if the stream is not complete. Returning zero bytes indicates the end of the data.

The Exchange Manager's ExgReceive() function simply calls ExgLibReceive in the exchange library identified by the ExgSocketType structure passed to ExgReceive.

Compatibility

Implemented only if 4.0 New Feature Set is present.

ExgLibRequest Function ^TOP^

Purpose

Requests an object using a URL, then has the Exchange Manager send it to the default application registered for the object's type.

Declared In

ExgLib.h

Prototype

Err ExgLibRequest(
   UInt16 libRefNum,
   ExgSocketType *socketP
)

Parameters

libRefNum
Reference number of this exchange library.
socketP
Pointer to the socket structure (see ExgSocketType). The name field contains the URL of the object being requested.

Returns

Returns errNone if no error. exgErrNotSupported is returned if the exchange library does not support this operation. Other error codes are defined by each exchange library.

Comments

The exchange library may prompt the user for addressing information. The socket's name field may contain a URL with any of the schemes for which the exchange library registered. Not all exchange libraries support this operation.


NOTE: This function is often used to tickle an exchange library to make it check to see if there are new messages. These messages are then delivered as usual. So there may or may not be a specific object being requested.

The Exchange Manager's ExgRequest() function calls ExgLibRequest in the exchange library identified by the ExgSocketType structure passed to ExgRequest. If ExgLibRequest returns exgErrNotEnoughPower, the Exchange Manager puts up an alert, so there is no need for the exchange library to do so. Other error codes are not treated specially by the Exchange Manager; an exchange library must put up its own alerts when appropriate.

See Also

ExgRegisterDatatype()

ExgLibSend Function ^TOP^

Purpose

Send data for an object to a destination device.

Declared In

ExgLib.h

Prototype

UInt32 ExgLibSend(
   UInt16 libRefNum,
   ExgSocketType *exgSocketP,
   const void *bufP,
   UInt32 bufLen,
   Err *errP
)

Parameters

libRefNum
Reference number of this exchange library.
exgSocketP
A pointer to the socket structure (see ExgSocketType).
bufP
A pointer to a buffer containing the data to send.
bufLen
The number of bytes to send.
errP
The error code result. Error codes are defined by each exchange library

Returns

Returns the number of bytes sent.

Comments

Applications call ExgSend() after ExgPut() and in response to sysAppLaunchCmdExgGetData.

This function blocks until all bytes to be sent are actually sent, or until an error occurs (such as device full).

ExgLibSend may be called any number of times with varying size buffers to transmit information. If dialogs are being displayed, ExgLibSend must keep them updated (perhaps with animation or progress information). ExgLibSend must also check for events and let the Progress Manager handle them.

The Exchange Manager's ExgSend function simply calls ExgLibSend in the exchange library identified by the ExgSocketType structure passed to ExgSend.

Compatibility

Implemented only if 4.0 New Feature Set is present.

ExgLibSleep Function ^TOP^

Purpose

The device is going to sleep.

Declared In

ExgLib.h

Prototype

Err ExgLibSleep(
   UInt16 libRefnum
)

Parameters

libRefnum
Reference number of this exchange library.

Returns

Returns errNone if no error. Error codes are defined by each exchange library.

Comments

The device goes into sleep mode when the user turns the device off, the auto-off timer expires, or power is low. All shared libraries must implement ExgLibSleep; however, no processing is required and simply returning errNone is enough.


IMPORTANT: Libraries must return from this function quickly to allow sufficient time for emergency shutdown situations (removal of batteries, for example).

ExgLibWake Function ^TOP^

Purpose

The device is waking up.

Declared In

ExgLib.h

Prototype

Err ExgLibWake(
   UInt16 libRefnum
)

Parameters

libRefnum
Reference number of this exchange library.

Returns

Returns errNone if no error. Error codes are defined by each exchange library.

Comments

The device wakes up when the user turns the device on. All shared libraries must implement ExgLibWake, although no processing is required; it is enough to simply return errNone.