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
ExgLibAccept Function
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
ExgLibClose Function
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
Comments
Exchange libraries are free to implement this function for internal or external use. The Exchange Manager does not call it.
ExgLibConnect Function
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
ExgSocketTypestructure 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
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
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
ExgSocketTypestructure 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
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
Purpose
Handle exchange-library-specific events.
Declared In
ExgLib.h Prototype
Boolean ExgLibHandleEvent( UInt16 libRefnum, void *eventP )
Parameters
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
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
Comments
Exchange libraries are free to implement this function for internal or external use. The ExgLibDisconnect does not call it.
ExgLibPut Function
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
ExgLibConnectis supported and an application does not callExgLibConnect.
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
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:
errNoneif no error.exgErrNotSupportedis returned if used during a preview and the exchange library does not support preview or if there appears to be more data available butExgLibReceivecannot 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
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). Thenamefield 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
ExgLibSend Function
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
Purpose
Declared In
ExgLib.h Prototype
Err ExgLibSleep( UInt16 libRefnum )
Parameters
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
Purpose
Declared In
ExgLib.h Prototype
Err ExgLibWake( UInt16 libRefnum )
Parameters
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.