< Home < Developers < Development Support < Documentation

## 59 Exchange Library

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part III: Communications 59 Exchange Library Exchange Library Functions ExgLibAccept ExgLibClose ExgLibConnect ExgLibControl ExgLibDisconnect ExgLibGet ExgLibHandleEvent ExgLibOpen ExgLibPut ExgLibReceive ExgLibRequest ExgLibSend ExgLibSleep ExgLibWake |  |  |  | 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 ## New ExgLibAccept #### Purpose Accept an incoming connection. #### Prototype Err ExgLibAccept(UInt16 libRefnum, ExgSocketType *exgSocketP) #### Parameters #####
-> libRefnum | Reference number of this exchange library.
#####
-> exgSocketP | A pointer to the socket structure (see ExgSocketType).
#### Result 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 ## New ExgLibClose #### Purpose Library-specific. Although this function is not called by the Exchange Manager, all shared libraries normally implement it. #### 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. ## New ExgLibConnect #### Purpose Open a connection in preparation for sending or receiving objects. #### 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.
#### Result 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. ## New ExgLibControl #### Purpose Supply information about the exchange library. #### 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.
#### Result 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. ## New ExgLibDisconnect #### Purpose Disconnect a connection made with ExgLibConnect, ExgLibAccept, ExgLibPut, or ExgLibGet. #### 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.
#### Result 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. ## New ExgLibGet #### Purpose Establish a connection and request data from a remote device. #### Prototype Err ExgLibGet(UInt16 libRefNum, ExgSocketType *exgSocketP) #### Parameters #####
-> libRefNum | Reference number of this exchange library.
#####
<-> exgSocketP | A pointer to the socket structure (see ExgSocketType).
#### Result 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. ## New ExgLibHandleEvent #### Purpose Handle exchange-library-specific events. #### Prototype Boolean ExgLibHandleEvent(UInt16 libRefnum, void *eventP) #### Parameters #####
-> libRefnum | Reference number of this exchange library.
#####
-> eventP | The event to handle.
#### Result 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. ## New ExgLibOpen #### Purpose Library-specific. Although this function is not called by the Exchange Manager, all shared libraries normally implement it. #### 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. ## New ExgLibPut #### Purpose Signals the start of an object to be transferred to the destination device. #### Prototype Err ExgLibPut(UInt16 libRefnum, ExgSocketType *exgSocketP) #### Parameters #####
-> libRefnum | Reference number of this exchange library.
#####
<- exgSocketP | Pointer to the socket structure (see ExgSocketType).
#### Result 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. ## New ExgLibReceive #### Purpose Receive data from a remote device. #### 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.
#### Result 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. ## New ExgLibRequest #### Purpose Requests an object using a URL, then has the Exchange Manager send it to the default application registered for the object's type. #### 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.
#### Result 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 ## New ExgLibSend #### Purpose Send data for an object to a destination device. #### 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
#### Result 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. ## New ExgLibSleep #### Purpose The device is going to sleep. #### Prototype Err ExgLibSleep(UInt16 libRefnum) #### Parameters #####
-> libRefnum | Reference number of this exchange library.
#### Result 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). ## New ExgLibWake #### Purpose The device is waking up. #### Prototype Err ExgLibWake(UInt16 libRefnum) #### Parameters #####
-> libRefnum | Reference number of this exchange library.
#### Result 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. |