51 Exchange Manager

This chapter provides reference material for the exchange manager API:

• Exchange Manager Data Structures
  
  
• Exchange Manager Functions
  
  
• Application-Defined Functions
  

The header file ExgMgr.h declares the exchange manager API. For more information on the exchange manager, see the chapter "Beaming (Infrared Communication)" in the Palm OS Programmer's Companion.

Exchange Manager Data Structures

ExgAskResultType

The ExgAskResultType enum defines possible values for the result field of the sysAppLaunchCmdExgAskUser launch code parameter block.

typedef enum {

    exgAskDialog,
    exgAskOk,
    exgAskCancel }
ExgAskResultType;

Value Descriptions

ExgGoToType

The ExgGoToType structure defines information that is passed to the sysAppLaunchCmdGoto launch command, after an item is received. The ExgGoToPtr type points to a ExgGoToType structure.

typedef struct {

    UInt16 dbCardNo;
    LocalID dbID;
    UInt16 recordNum;
    UInt32 uniqueID;
    UInt32 matchCustom;
} ExgGoToType;

typedef ExgGoToType * ExgGoToPtr;

Field Descriptions

ExgSocketType

The ExgSocketType structure defines an exchange manager socket. The ExgSocketPtr type points to a ExgSocketType structure.

typedef struct ExgSocketType {

    UInt16 libraryRef;
    UInt32 socketRef;
    UInt32 target;
    UInt32 count;
    UInt32 length;
    UInt32 time;
    UInt32 appData;
    UInt32 goToCreator;
    ExgGoToType goToParams;
    UInt16 localMode:1;
    UInt16 packetMode:1;
    UInt16 noGoTo:1;
    UInt16 noStatus:1;
    UInt16 reserved:12;
    Char *description;
    Char *type;
    Char *name;
} ExgSocketType;

typedef ExgSocketType* ExgSocketPtr;

Note that when data is received, some of the fields in this structure may not be filled in. The existing IR library does not send values for the count, time, appData, or type fields; however, it may do so in the future. When you are sending data, it is recommended that you provide values for all of these fields, but you should not rely on receiving values for them.

Field Descriptions

Compatibility

The noGoTo and noStatus flags are only defined if 3.5 New Feature Set is present.

Exchange Manager Functions

ExgAccept

Purpose

Accepts a connection from a remote device.

Prototype

Err ExgAccept (ExgSocketPtr socketP)

Parameters

-> socketP

Pointer to the socket structure.

Result

Returns the following result codes:

errNone	No error
exgErrBadLibrary	Couldn't find default exchange library
exgErrStackInit	Couldn't initialize the IR stack (not enough battery power or unsupported hardware)

Comments

An application calls this function when it has been called with the special application launch code sysAppLaunchCmdExgReceiveData. The application is passed socketP as a parameter. It should pass this parameter to ExgAccept to accept the connection and then call ExgReceive one or more times to receive the data.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgReceive

ExgDBRead

Purpose

Reads a Palm OS^® database in its internal format and writes it to storage RAM. For example, this function might read in a database transmitted by a beaming operation using the exchange manager.

Prototype

Err ExgDBRead (ExgDBReadProcPtr readProcP, ExgDBDeleteProcPtr deleteProcP, void* userDataP, LocalID* dbIDP, UInt16 cardNo, Boolean* needResetP, Boolean keepDates)

Parameters

-> readProcP

A pointer to a function that you supply that reads in the database and passes it to ExgDBRead. See ReadProc for details.

-> deleteProcP

A pointer to a function that is called if a database with an identical name already exists on the device, so you can erase it before ExgDBRead stores the received database. See DeleteProc for details.

-> userDataP

A pointer to any data you want to pass to either the readProcP or deleteProcP functions.

<- dbIDP

The ID of the database that ExgDBRead created on the local device.

<- cardNo

The number of the card on which the database was stored by ExgDBRead.

<- needResetP

Set to true by ExgDBRead if the dmHdrAttrResetAfterInstall attribute bit is set in the received database.

-> keepDates

Specify true to retain the creation, modification, and last backup dates as set in the received database header. Specify false to reset these dates to the current date.

Result

Returns errNone if successful; otherwise, returns one of the data manager error codes (dmErr...) or a callback-specific error code (if the readProcP function returns an error, it is also returned by ExgDBRead).

Comments

The read callback function passed in readProcP is called multiple times by ExgDBRead. Each time, ExgDBRead passes in sizeP the number of bytes it expects to receive in the next chunk that the read callback function is to return in dataP. It's important for the read callback function to set the number of bytes (in sizeP) that it actually placed in dataP, if it's not the same as what ExgDBRead expected. ExgDBRead stops calling the read callback function after it receives the entire database (it knows when it's got it all based on the header information).

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgDBWrite

ExgDBWrite

Purpose

Reads a given Palm OS database in its internal format from the local device and writes it out using a function you supply. For example, this function might read a local database and transmit it by a beaming operation using the exchange manager.

Prototype

Err ExgDBWrite (ExgDBWriteProcPtr writeProcP, void* userDataP, const char* nameP, LocalID dbID, UInt16 cardNo)

Parameters

-> writeProcP

A pointer to a function that you supply that writes out the database identified by dbID. See WriteProc for details.

-> userDataP

A pointer to any data you want to pass to the writeProcP function.

-> nameP

A pointer to the name of the database that you want ExgDBWrite to read and pass to writeProcP.

-> dbID

The id of the database that you want ExgDBWrite to read and pass to writeProcP. If you don't supply an ID, then nameP is used to search for the database by name.

-> cardNo

The number of the card on which to look for the database identified by nameP.

Result

Returns errNone if successful; otherwise, returns one of the data manager error codes (dmErr...) or a callback-specific error code (if the writeProcP function returns an error, it is also returned by ExgDBWrite).

Comments

The writeProcP parameter points to a function that you supply and that is called by ExgDBWrite to write out a database. For example, you might use this function to call exchange manager functions to beam the database to another unit.

The write callback function is called multiple times by ExgDBWrite. In the sizeP parameter, ExgDBWrite passes the number of bytes in dataP. Due to transport errors, timeouts, or other problems, you may not be able to successfully send all this data. If the write callback function didn't handle it all, it's important that it set in sizeP the number of bytes that it did handle successfully. ExgDBWrite stops calling the write callback function after you write out the entire database (it knows when you've done it all based on the header information and number of bytes you return in sizeP each time).

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgDBRead

ExgDisconnect

Purpose

Terminates an exchange manager transfer and disconnects.

Prototype

Err ExgDisconnect(ExgSocketPtr socketP, Err error)

Parameters

-> socketP

Pointer to the socket structure identifying the connection to terminate.

-> error

Any application error that occurred.

Result

Returns the following result codes:

errNone	No error
exgErrBadLibrary	Couldn't find default exchange library
exgMemError	Couldn't read data to send
exgErrUserCancel	User cancelled transfer

Comments

In the error parameter, pass any error that occurs during the application loop, including errors returned from other exchange manager functions. This ensures that the connection is shut down knowing that it failed rather than succeeded.

It's especially important to check the result code from this function, since this will tell you if the transfer was successful. An errNone return value means that the item was delivered to the destination successfully. It does not mean that the user on the other end actually kept the data.

ExgDisconnect is used for sending and receiving. When receiving, the application can insert its creator ID into the goToCreator field in the socket structure and add other goto information. After the application returns from the sysAppLaunchCmdExgReceiveData call, the system will launch the application with a standard sysAppLaunchCmdGoto launch code built from the information in the socket header gotoParams field.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgPut, ExgReceive, ExgSend

ExgDoDialog

Purpose

Display a dialog that allows users to accept or reject the receipt of data.

Prototype

Boolean ExgDoDialog (ExgSocketPtr socketP, ExgDialogInfoType *infoP, Err *errP)

Parameters

-> socketP

Pointer to the socket structure identifying the connection. You can obtain this pointer from the sysAppLaunchCmdExgAskUser launch code parameter block.

<-> infoP

A pointer to an ExgDialogInfoType structure (see the "Comment" section below).

<- errP

errNone if no error, or the error code if an error occurred. Currently, no errors are returned.

Result

Returns true if the user clicks the OK button on the dialog, or false otherwise.

Comments

This function displays the exchange dialog, which prompts the user to accept or reject incoming data.

By default, the exchange manager calls this function for you if you don't handle the sysAppLaunchCmdExgAskUser launch code or if you return exgAskDialog from the launch code handler. When the exchange manager calls ExgDoDialog, the dialog only displays a message similar to "Do you want to accept `John Doe' into AddressBook?" and allows the user to accept or reject the data. If the user clicks OK, the data should be received as an unfiled record.

To allow users to select a category when accepting incoming data, handle sysAppLaunchCmdExgAskUser to call ExgDoDialog explicitly, and pass it a pointer to an ExgDialogInfoType structure. The ExgDialogInfoType structure is defined as follows:

typedef struct {

    UInt16 version;
    DmOpenRef db;
    UInt16 categoryIndex;
} ExgDialogInfoType;

-> version

Set this field to 0 to specify version 0 of this structure.

-> db

Pointer to an open database that defines the categories the dialog should display.

<- categoryIndex

Index of the category in which the user wants to file the incoming data.

If db is valid, the function extracts the category information from the specified database and displays it in a pop-up list. Upon return, the categoryIndex field contains the index of the category the user selected, or dmUnfiledCategory if the user did not select a category.

If the call to ExgDoDialog is successful, your application is responsible for retaining the value returned in categoryIndex and using it to file the incoming data as a record in that category. One way to do this is to store the categoryIndex in the socket's appData field (see ExgSocketType) and then extract it from the socket in your response to the launch code sysAppLaunchCmdExgReceiveData. For example:

if (cmd == sysAppLaunchCmdExgReceiveData) {

    UInt16 categoryID =
    (ExgSocketPtr)cmdPBP->appData;
    /* other declarations */

/* Receive the data, and create a new record
    using the received data. indexNew is the
    index of this record. */

    if (categoryID){

    UInt16 attr;
    Err err;
    err = DmRecordInfo(dbP, indexNew, &attr,
    NULL, NULL);

    // Set the category to the one the user
    // specified, and mark the record dirty.
    if ((attr & dmRecAttrCategoryMask) !=
    categoryID) {
    attr &= ~dmRecAttrCategoryMask;
    attr |= categoryID | dmRecAttrDirty;
    err = DmSetRecordInfo(dbP, indexNew,
    &attr, NULL);
    }
    }
}

Some of the Palm OS built-in applications (AddressBook, Memo, and ToDo) use this method of setting the category on data received through beaming. Refer to the example code for these applications provided in the SDK for a more complete example of how to use ExgDoDialog.

When you explicitly call ExgDoDialog, you must set the result field of the sysAppLaunchCmdExgAskUser launch code's parameter block to either exgAskOk (upon success) or exgAskCancel (upon failure) to prevent the system from displaying the dialog a second time.

Compatibility

Implemented only if 3.5 New Feature Set is present.

ExgPut

Purpose

Initiates the transfer of data to the destination device.

Prototype

Err ExgPut (ExgSocketPtr socketP)

Parameters

-> socketP

Pointer to the socket structure containing connection information and information identifying the object to send.

Result

Returns the following result codes:

errNone	No error
exgErrBadLibrary	Couldn't find default exchange library
exgErrStackInit	Couldn't initialize the IR stack (not enough battery power or unsupported hardware)
exgMemError	Not enough memory to initialize transfer

Comments

If the connection does not already exist, this function establishes one. You must create and pass a pointer to an ExgSocketType structure containing information about the data to send and the destination application. All unused fields in the structure must be zeroed.

If no error is returned, this call must be followed by ExgSend, to begin sending data, or ExgDisconnect, to disconnect. You may need to call ExgSend multiple times to send all the data.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgDisconnect, ExgSend

ExgReceive

Purpose

Receives data from a remote device.

Prototype

UInt32 ExgReceive (ExgSocketPtr socketP, void *bufP, const UInt32 bufLen, Err * err)

Parameters

-> socketP

Pointer to the socket structure.

-> bufP

Pointer to the buffer to receive the data.

-> bufLen

Number of bytes to receive.

<- err

Pointer to an error code result.

Result

Returns the number of bytes actually received. A zero result indicates the end of the transmission. An error code is returned in the address indicated by err. The error code exgErrUserCancel is returned if the user cancels the operation.

Comments

Call this function one or more times to receive all the data, following a successful call to ExgAccept. After receiving the data, call ExgDisconnect to terminate the connection.

This function blocks the application until the end of the transmission or until the requested number of bytes has been received. However, it does provide its own user interface that will be updated as necessary and will allow the user to cancel the operation in progress.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgAccept, ExgDisconnect

ExgRegisterData

Purpose

Registers an application to receive a specific type of data.

Prototype

Err ExgRegisterData (const UInt32 creatorID, const UInt16 id, const Char * const dataTypesP)

Parameters

-> creatorID

Creator ID of the registering application.

-> id

Registry ID identifying the type of the items being registered. Specify exgRegExtensionID or exgRegTypeID.

-> dataTypesP

Pointer to a tab-delimited, null-terminated string listing the items to register. (Use /t for the tab character.) These include file extensions or MIME types. To unregister, pass a NULL value.

Result

Returns errNone if successful, otherwise, one of the data manager error codes (dmErr...).

Comments

Applications that wish to receive data from anything other than another Palm OS device running the same application must use this function to register for the kinds of data they can receive. Call this function when your application is loaded on the device.

Specify exgRegExtensionID to register to receive data that has a filename with a particular extension. For example, if your application wants to receive files with a .TXT extension, it could register like this:

ExgRegisterData(myCreator, exgRegExtensionID, "TXT");

If the application wants to receive files with a .TXT extension or with a .DOC extension, it could register like this:

ExgRegisterData(myCreator, exgRegExtensionID, "TXT/tDOC");

Specify exgRegTypeID to register to receive data with a specific MIME type. For example, if your application wants to receive "setext" text files, it could register like this:

ExgRegisterData(myCreator, exgRegTypeID,
"text/x-setext");

Note that in the current implementation of the IR library, registering for a MIME type has no effect because the IR library does not send data type information. Therefore, the type is always received as NULL and will not match "setext." However, applications may choose to register for a type anyway because this limitation may be removed in the future.

Registrations are active until a hard reset or until the application is removed. The registration information is backed up and restored across a soft reset. When an application is removed, its registry information is also automatically removed from the registry, so there is not normally a need to unregister. If you want to unregister, you can register with a NULL value.

Compatibility

Implemented only if 3.0 New Feature Set is present.

ExgSend

Purpose

Sends data to the destination device.

Prototype

UInt32 ExgSend (ExgSocketPtr socketP, const void * const bufP, const UInt32 bufLen, Err * err)

Parameters

-> socketP

Pointer to the socket structure.

-> bufP

Pointer to the data to send.

-> bufLen

Number of bytes to send.

<- err

Pointer to an error code result.

Result

Returns the number of bytes sent, normally the same number as specified in bufLen. An error code is returned in the address indicated by err. The error code exgErrUserCancel is returned if the user cancels the operation.

Comments

Call this function one or more times to send all the data, following a successful call to ExgPut. After sending the data, call ExgDisconnect to terminate the connection.

The lower level protocol may break large amounts of data into multiple packets or assemble small send commands together into larger packets, but the application will not be aware of these transport level details.

This function blocks the application until all the data is sent. However, it does provide its own user interface that will be updated as necessary and will allow the user to cancel the operation in progress.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgDisconnect, ExgPut

Application-Defined Functions

The functions in this section are supplied by you and can be named anything. You supply pointers to the functions in exchange manager functions that you call (ExgDBRead and ExgDBWrite).

DeleteProc

Purpose

Handle the case where a database with an identical name already exists on the device.

Prototype

Boolean DeleteProc (const char* nameP, UInt16 version, UInt16 cardNo, LocalID dbID, void* userDataP)

Parameters

-> nameP

A pointer to the name of the identical database that already exists.

-> version

The version of the identical database that already exists.

-> cardNo

The card number of the identical database that already exists.

-> dbID

The database ID of the identical database that already exists.

-> userDataP

The userDataP parameter passed to ExgDBRead is simply passed on to the delete function. You can use it for application-specific data.

Result

Returns a Boolean value. true means that this function handled the situation successfully; that is, it deleted, renamed, or moved the database so there would no longer be a conflict with the one that ExgDBRead is writing. false means that this function did not handle the situation successfully; in this case, ExgDBRead exits with no error (same as if the user cancelled the operation).

Comments

This delete callback function gives you a chance to delete the existing database, or take some other action (such as changing the database name, if appropriate).

ReadProc

Purpose

Read in the database and pass it to ExgDBRead.

Prototype

Err ReadProc (void* dataP, UInt32* sizeP, void* userDataP)

Parameters

-> dataP

A pointer to a buffer where this function should place the database data.

<-> sizeP

The size of dataP. This value is set by ExgDBRead to the number of bytes it expects to receive in dataP. You must set this value to the number of bytes you return in dataP (if it's not the same).

-> userDataP

The userDataP parameter passed to ExgDBRead is simply passed on to the read function. You can use it for application-specific data.

Result

Returns an error number, or errNone if there is no error. If this function returns an error, ExgDBRead deletes the database it was creating, cleans up any memory it allocated, then exits, returning the error passed back from this function.

WriteProc

Purpose

Writes out the database.

Prototype

Err WriteProc (const void* dataP, UInt32* sizeP, void* userDataP)

Parameters

-> dataP

A pointer to a buffer containing the database data, placed there by ExgDBWrite.

<-> sizeP

The number of bytes placed in dataP by ExgDBWrite. If you were unable to write out or send all of the data in this chunk, on exit, you should set sizeP to the number of bytes you did write.

-> userDataP

The userDataP parameter passed to ExgDBWrite is simply passed on to the write function. You can use it for application-specific data.

Result

Returns an error number, or errNone if there is no error. If this function returns an error, ExgDBWrite closes the database it was reading, cleans up any memory it allocated, then exits, returning the error passed back from this function.