< Home < Developers < Development Support < Documentation

## 58 Exchange Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part III: Communications 58 Exchange Manager Exchange Manager Data Structures ExgAskResultType ExgGoToType ExgLocalSocketInfoType ExgPreviewInfoType ExgSocketType Exchange Manager Constants Registry ID Constants Predefined URL Schemes Predefined URL Prefixes Exchange Manager Functions ExgAccept ExgConnect ExgControl ExgDBRead ExgDBWrite ExgDisconnect ExgDoDialog ExgGet ExgGetDefaultApplication ExgGetRegisteredApplications ExgGetRegisteredTypes ExgGetTargetApplication ExgNotifyGoto ExgNotifyPreview ExgNotifyReceive ExgPut ExgReceive ExgRegisterDatatype ExgRegisterData ExgRequest ExgSend ExgSetDefaultApplication Application-Defined Functions DeleteProc ReadProc WriteProc |  |  |  | This chapter describes the Exchange Manager API declared in the header file ExgMgr.h and the Exchange Local Library API declared in the header file ExgLocalLib.h. It discusses the following topics: Exchange Manager Data Structures Exchange Manager Constants Exchange Manager Functions Application-Defined Functions For more information on the Exchange Manager, see the chapter "Object Exchange" of Palm OS Programmer's Companion, vol. II, Communications. ## 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 #####
exgAskDialog | The Exchange Manager should display a dialog that prompts the user to confirm the receipt of data. See ExgDoDialog.
exgAskOk | Accept the data.
exgAskCancel | Reject the data.
## ExgGoToType The ExgGoToType structure defines the goToParams field of the ExgSocketType structure. Applications that want to be launched after the data is received place their creator IDs in the goToCreator field and define the goToParams field. The values in this structure are copied to the sysAppLaunchCmdGoto launch code's parameter block.
    typedef struct {
      UInt16 dbCardNo;
      LocalID dbID;
      UInt16 recordNum;
      UInt32 uniqueID;
      UInt32 matchCustom;
    } ExgGoToType;
#### Field Descriptions #####
dbCardNo | The card number of the database that contains the added record.
dbID | The local ID of the database that contains the added record.
recordNum | The index of the record that was added.
uniqueID | The unique ID of the record that was added. This field is not used.
matchCustom | Application-specific information.
## New ExgLocalSocketInfoType The ExgLocalSocketInfoType structure identifies information specific to the Local Exchange Library. The socketRef field of the ExgSocketType structure is set to this structure when you send and receive data using the Local Exchange Library. The Local Exchange Library creates this structure if it does not already exist. You only need to create it if you want to supply non-default values for the noAsk or previewInfoP fields.
    typedef struct {
      Boolean freeOnDisconnect;
      Boolean noAsk;
      ExgPreviewInfoType *previewInfoP;
      FileHand tempFileH;
      Err err;
      ExgLocalOpType op;
    } ExgLocalSocketInfoType;
#### Field Descriptions #####
freeOnDisconnect | Whether the structure is freed when the ExgDisconnect call is made. The default is true. In general, code that allocates a structure should be responsible for freeing that structure. Therefore, if you have allocated ExgLocalSocketInfoType, you should set this field to false and explicitly free the structure when you are finished with it.
noAsk | Set to true to disable the display of the exchange dialog. If you want to, for example, create a vCalendar object and send it to the Datebook application in response to a user command, you probably want to set noAsk to true so that the user does not have to confirm the receipt of the data they just requested you to send.
previewInfoP | A pointer to an ExgPreviewInfoType structure, used to display a preview of the data. If you wanted to simply use another application to help display data, you would create and initialize this structure.
tempFileH | A temporary buffer that the Local Exchange Library uses. Do not set this field directly; the Local Exchange Library should set it.
err | The error code returned from the Local Exchange Library. Do not set this field directly; the Local Exchange Library should set it.
op | The operation in progress. Do not set this field directly. The Local Exchange Library sets this field to one of the following:
| #####
exgLocalOpNone | No operation in progress.
#####
exgLocalOpPut | A send is in progress.
#####
exgLocalOpAccept | A receive is in progress.
#####
exgLocalOpGet | A get is in progress.
#####
exgLocalOpGetSender | The library is receiving information from the sending application during a get operation.
## New ExgPreviewInfoType The ExgPreviewInfoType structure provides information to the ExgNotifyPreview function. The ExgNotifyPreview function uses this information to have the application display a preview of the data to be received in the exchange dialog.
    typedef struct {
      UInt16         version;
      ExgSocketType  *socketP;
      UInt16         op;
      Char           *string;
      UInt32         size;
      RectangleType  bounds;
      UInt16         types;
      Err            error;
    } ExgPreviewInfoType;
#### Field Descriptions #####
-> version | Set this field to 0 to specify version 0 of this structure.
-> socketP | A pointer to the socket structure (see ExgSocketType). The libraryRef field must identify the exchange library from which preview data should be received, and the target, type, or name field should be defined as well.
-> op | One of the following constants:
| #####
exgPreviewDialog | Display a modal dialog containing the preview. This constant is only used in situations where one application launches another to display data.
| #####
exgPreviewDraw | The preview is a graphic.
| #####
exgPreviewLongString | The preview is a long string.
| #####
exgPreviewQuery | Ask the application which preview operations it supports. The answer is returned in the types field. If the application does not support any preview modes, the error field contains exgErrNotSupported.
| #####
exgPreviewShortString | The preview is a short string.
<- string | A buffer into which the application places the string preview if exgPreviewLongString or exgPreviewShortString is specified.
-> size | The allocated size of the string field.
-> bounds | The bounds of the rectangle in which the application draws the graphic if exgPreviewDraw is specified.
<- types | Upon return from an exgPreviewQuery operation, a bit field identifying the types of previews the application supports.
<- error | The error code returned from the application. If errNone, the preview operation was successful.
Applications can define and use their own constants for the preview operation. Operations specific to an application are numbered starting at exgPreviewFirstUser and should be no greater than exgPreviewLastUser. #### Compatibility This structure is only defined if 4.0 New Feature Set is present. ## ExgSocketType The ExgSocketType structure defines an Exchange Manager socket, which is passed to most Exchange Manager functions. 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 preview:1;
      UInt16 reserved:11;
      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 have values. 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 the fields marked optional. #### Field Descriptions #####
libraryRef | The exchange library in use. When an application or library receives a socket, this field is already assigned.
| When sending data, applications may identify the exchange library they want to connect with by providing a URL in the name field. If so, they should use 0 for the libraryRef field. The Exchange Manager then determines which library corresponds to the URL and assigns the libraryRef field. See the Comments in the ExgPut function description for more information.
socketRef | The connection identifier. This value is supplied by the exchange library when a connection is established. It contains any necessary library-specific data.
target | The creator ID of the application that should receive the message.
count | The number of objects in this connection, usually 1 (optional).
length | The total byte count for all objects being sent (optional).
time | The last modified time of object (optional).
appData | Application-specific information (optional).
goToCreator | The creator ID of the application to launch using the sysAppLaunchCmdGoto launch code after the item is received if noGoTo is 0. The value is assigned by the application that receives the object. See the Comments section in ExgDisconnect for more information.
goToParams | If goToCreator is specified, then this field contains data that is copied into the launch code's parameter block. See ExgGoToType.
localMode | Set to 1 to exchange with local device only. A localMode of 1 is equivalent to specifying a URL with the exgLocalPrefix. Set to 0 to enable an exchange with a remote machine. The default is 0.
packetMode | Set to 1 to use connectionless packet mode (Ultra). The default is 0. Ultra mode is not currently supported.
noGoTo | Set to 1 to disable launching the application with sysAppLaunchCmdGoto. The default is 0.
noStatus | If true, the exchange library should not display a progress dialog. If false, the library can display a progress dialog. The default is false.
| The Exchange Manager sets and clears this bit at various times while data is received. Applications may also want to set this bit if they use the Local Exchange Library and want to prevent the progress dialog from being displayed during a send.
preview | If true, a preview is in progress. The ExgNotifyPreview function sets this bit while the preview takes place and clears it when the preview is finished. Exchange libraries should not discard any data while a preview is in progress because the full data must be sent later if the receiving user accepts it.
reserved | Reserved system flags.
description | A pointer to the text description of the object (optional).
type | A pointer to the MIME type of the object (optional).
name | The name of the object being sent. This can be a URL whose scheme identifies the exchange library to connect with.
| If the name has a colon, it is treated as a URL.
#### Compatibility The noGoTo and noStatus flags are only defined if 3.5 New Feature Set is present, and the noStatus flag has no effect unless 4.0 New Feature Set is present. The preview flag is only defined if 4.0 New Feature Set is present. ## Exchange Manager Constants ## Registry ID Constants The registry ID constants are used in the Exchange Manager registry. Exchange libraries register for the URL prefixes they handle, and applications register for the types of data they receive. The registry ID constants specify which type of data is being registered for. #####
Constant | Value | Description
--- | --- | ---
exgRegCreatorID | 0xfffb | Register for a creator ID. The target field of the ExgSocketType contains the creator ID of the application that should receive the data. Typically, the application with the matching creator ID receives the data, but it is possible for one application to register for another's creator ID and receive data in its place.
exgRegSchemeID | 0xfffc | Register for a URL scheme. Typically, only exchange libraries register for URL schemes. Applications can register for URL schemes, but they only receive the URL when ExgRequest is called. If the name field of the ExgSocketType contains a colon (:), the portion of the URL before the colon is the URL scheme. The default library registered for URLs with that scheme will handle the message.
exgRegExtensionID | 0xfffd | Register for a filename extension. If the name field of the ExgSocketType contains a period (.), the portion of the name after the last period is the filename extension. The application registered to handle files of that extension will handle the message.
exgRegTypeID | 0xfffe | Register for a MIME type. If the type field of the ExgSocketType contains a value, the application registered to receive that MIME type handles the message.
#### Compatibility The exgRegCreatorID and exgRegSchemeID constants are only defined if 4.0 New Feature Set is present. ## Predefined URL Schemes The Exchange Manager provides these predefined URL schemes, for which exchange libraries can register. #####
Constant | Value | Description
--- | --- | ---
exgBeamScheme | "_beam" | The URL scheme for Beam commands. By default, the IR Library handles this scheme.
exgSendScheme | "_send" | The URL scheme for Send commands. The purpose of the Send command is to provide a choice of transport mechanisms to the user; therefore, any exchange library that sends data should register for this scheme.
exgLocalScheme | "_local" | The URL scheme for the Local Exchange Library.
#### Compatibility These constants are only defined if 4.0 New Feature Set is present. ## Predefined URL Prefixes The Exchange Manager provides the following prefixes, which can be used to construct URLs appropriate for the name field of the ExgSocketType structure. When sending data, applications provide a URL to identify the exchange library that should transport the data. #####
Constant | Value | Description
--- | --- | ---
exgBeamPrefix | (exgBeamScheme ":") | The URL to beam data.
exgSendPrefix | ("?" exgSendScheme ":") | A URL for the general Send command. Because this URL begins with a question mark (?), the Exchange Manager displays a dialog with a list of exchange libraries registered for the exgSendScheme. The user then chooses the desired exchange library.
exgSendBeamPrefix | ("?" exgSendScheme ";" exgBeamScheme ":") | A URL for the general Send command. The Exchange Manager displays a dialog with a list of exchange libraries registered for either the exgSendScheme or the exgBeamScheme.
exgLocalPrefix | (exgLocalScheme ":") | The URL for using the Local Exchange Library.
#### Compatibility These constants are only defined if 4.0 New Feature Set is present. ## Exchange Manager Functions ## ExgAccept #### Purpose Accepts a connection from a remote device. #### Prototype Err ExgAccept (ExgSocketType *socketP) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType).
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrBadLibrary | Couldn't find default exchange library
exgErrNotSupported | A preview is in progress, and the exchange library identified by libraryRef doesn't support preview mode
Other error codes depend on the exchange library. Displays a fatal error message if socketP does not have a libraryRef specified. #### Comments Applications call this function when launched with the sysAppLaunchCmdExgReceiveData or sysAppLaunchCmdExgPreview launch code. The launch code contains socketP in its parameter block. Applications should pass this socket to ExgAccept to accept the connection, then call ExgReceive one or more times to receive the data, and then call ExgDisconnect to disconnect. NOTE: Don't create the socket on the receiving side of an exchange. The socket is passed to you in the command parameter block of the sysAppLaunchCmdExgReceiveData or sysAppLaunchCmdExgPreview launch code. #### Compatibility Implemented only if 3.0 New Feature Set is present. Preview mode is supported only if 4.0 New Feature Set is present. #### See Also ExgConnect, ExgPut, ExgGet ## ExgConnect #### Purpose Establishes a connection with a remote socket. #### Prototype Err ExgConnect (ExgSocketType *socketP) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType). Specify either a value for the libraryRef field or a URL in the name field. libraryRef should be 0 if the name field contains a URL.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrBadLibrary | Couldn't find exchange library
exgErrNotSupported | The library doesn't support the operation specified in socketP
exgErrUserCancel | The user cancelled the connection operation
exgMemError | There isn't enough free memory to respond to the request
exgErrNotEnoughPower | The battery does not have enough power to perform the operation
Other error codes depend on the exchange library. #### Comments Applications can 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. Before calling this function, the application must initialize the socketP parameter. The socket should identify the exchange library to connect with by providing either a library reference number in the libraryRef field or a URL in the name field. The default exchange library registered for that type of URL handles the connection. To provide users with a choice of transport mechanisms, specify a URL that begins with a question mark (?). The Exchange Manager displays a dialog with a list of all exchange libraries that respond to URLs of the specified type. If only one exchange library is registered for this URL scheme, no dialog is displayed. For example, many applications on Palm OS® 4.0 or higher support a Send command. This command generates a URL with the prefix exgSendPrefix (see Predefined URL Prefixes). The Exchange Manager displays a dialog containing a list of libraries registered for that URL scheme. The user selects an exchange library, and that library's ExgLibConnect function is called. If the library is not specified by either URL or library reference number (in the libraryRef field), the Exchange Manager by default uses the IR Library; however, if the localMode flag is set, the Local Exchange Library is used instead. In addition to specifying the library, you can set the count field in socketP before making this call to indicate the number of objects that are going to be sent. Use a count of 0 if the number of objects isn't known in advance. If no error is returned from ExgConnect, applications can follow this call either by sending multiple objects or requesting data from the remote device or both. To send an object, call ExgPut at the beginning of each object and call ExgSend one or more times per object to send the data. To request data from the remote device, use ExgGet (and then use ExgReceive to receive the requested data). You can use these calls in combination with each other to support two-way communications. After all of the objects have been sent and received, call ExgDisconnect to disconnect. IMPORTANT: Not all exchange libraries support the sending of multiple objects or using ExgGet to request data. #### Compatibility Implemented only if 3.0 New Feature Set is present. ExgConnect was for system use only until the release of Palm OS 4.0. Multiple object sending and identifying exchange libraries by URL are supported only if 4.0 New Feature Set is present. On earlier releases, this function is an alias for the ExgPut function. #### See Also ExgPut, ExgAccept, ExgGet ## New ExgControl #### Purpose Requests that an exchange library perform an operation. #### Prototype Err ExgControl (ExgSocketType *socketP, UInt16 op, void *valueP, UInt16 *valueLenP) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType). Specify either a value for the libraryRef field or a URL in the name field. libraryRef should be 0 if the name field contains a URL.
#####
-> op | A constant identifying the operation that the exchange library should perform. See the Comments section for more information.
#####
<-> valueP | Upon entry, a parameter that the exchange library requires to perform the operation, if any. Most operations do not require an input parameter. Upon return, contains the result of the operation.
#####
<-> valueLenP | The size of the valueP buffer. The size is updated upon return to show the actual length of the content returned.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrBadLibrary | Couldn't find the requested exchange library
exgErrNotSupported | The exchange library does not support the requested operation
Other error codes depend on the exchange library. #### Comments The Exchange Manager uses this function to request information from the exchange library. Applications may also call this function. The Exchange Manager defines and uses a set of operation constants that it might send to any exchange library. These constants begin with the prefix exgLibCtlGet. The type of the variable pointed to by valueP depends on the type of operation to be performed. Table 58.1 lists and describes the predefined Exchange Manager operations. #####
Table 58.1 ExgControl operations for all exchange libraries
Operation exgLibCtlGet... | value Data Type | Description
--- | --- | ---
Preview | Boolean. Output only. | Returns true if the exchange library supports preview mode or false if not. If the exchange library does not respond to this operation, it is assumed to support preview mode.
Title | String buffer of size exgTitleBufferSize bytes. Output only. | Returns the name of the exchange library as it should appear in the Send dialog. All exchange libraries must respond to this operation.
Version | UInt16. Output only. | Returns the version of the exchange library API that this library implements. The constant exgLibAPIVersion defines the current version number. If the exchange library does not respond to this operation, the library supports the version of the Exchange Library API defined in Palm OS 4.0.
An exchange library may also define its own operations. For example, the IR Library supports operations to enable or disable beaming, to set the baud rates, or to use the serial port (see "IR Control Constants"). The SMS Library supports operations that allow you to set the SMS preferences for sending messages or to manipulate multipart messages (see "SMS Control Constants"). Operations specific to an exchange library are numbered starting at exgLibCtlSpecificOp. The socketP passed to this function must identify an exchange library either using the libraryRef field or using a URL in the name field. The Comments section in ExgConnect describes how an application should identify the exchange library. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## ExgDBRead #### Purpose Converts a Palm OS database from its internal format and writes it to storage RAM. #### 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 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. See DeleteProc for details.
#####
-> userDataP | A pointer to any data you want to pass to either the readProcP or deleteProcP functions. Often, this parameter is used to pass the ExgSocketType that is required by many Exchange Manager 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 This function converts data received from an exchange library or from any other transport mechanism into a Palm OS database and stores that database in the storage heap. It is not required that you use this function in conjunction with Exchange Manager calls. That is, it's possible to use this function to perform other operations, such as converting a database created on the desktop computer to a Palm OS formatted database in the storage heap. The primary use of this function, however, is to receive a database that has been beamed onto the device. In this case, call ExgDBRead in response to the launch code sysAppLaunchCmdExgReceiveData after calling ExgAccept to accept the connection. Place the call to ExgReceive in the read callback function you passed as the readProcP parameter. Pass the ExgSocketType structure returned from ExgAccept in the userDataP parameter so that you have access to it in the read callback function. The read callback function performs the actual reading of data. ExgDBRead calls the read callback function multiple times. Each time, the sizeP parameter contains the number of bytes ExgDBRead expects the data returned in dataP to contain. 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 0 is returned in sizeP. The callback function you pass in deleteProcP handles the case where the database being read already exists on the device. It is called only in that circumstance. The callback function may want to close the database if it is open, change the existing database's name, or delete the existing database to allow an overwrite. See DeleteProc for more information. #### Compatibility Implemented only if 3.0 New Feature Set is present. #### See Also ExgDBWrite ## ExgDBWrite #### Purpose Converts a given Palm OS database from its internal format on the local device and writes it using a function you supply. #### Prototype Err ExgDBWrite (ExgDBWriteProcPtr writeProcP, void* userDataP, const char* nameP, LocalID dbID, UInt16 cardNo) #### Parameters #####
-> writeProcP | A pointer to a function 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. Often, this parameter is used to pass the ExgSocketType that is required by many Exchange Manager functions.
#####
-> nameP | A pointer to the name of the database that you want ExgDBWrite to write. This database is passed to writeProcP.
#####
-> dbID | The ID of the database that you want ExgDBWrite to 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 This function converts a Palm OS formatted database on the storage heap into a stream of bytes that can be sent over the Internet or over any other transport mechanism. It is not required that you use this function in conjunction with Exchange Manager calls. The primary use of this function, however, is to write a database that is going to be beamed onto another device. In this case, call ExgDBWrite after establishing the connection with ExgPut. Place the call to ExgSend in the write callback function you passed as the writeProcP parameter. Pass the ExgSocketType structure returned from ExgSend in the userDataP parameter so that you have access to it in the write callback function. The write callback function performs the actual writing of data. ExgDBWrite calls the write callback function multiple times. Each time, the sizeP parameter contains the number of bytes of dataP that are to be written. 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 0 is returned in sizeP. #### 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 (ExgSocketType *socketP, Err error) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType) identifying the connection to terminate.
#####
-> error | Any error that occurred. This parameter tells the exchange library why the connection is being broken. Normally the error code from ExgSend or ExgReceive is passed in here.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrBadLibrary | Couldn't find default exchange library
exgMemError | Couldn't read data to send
exgErrUserCancel | User cancelled transfer
Other error codes depend on the exchange library. May display a fatal error message if socketP doesn't contain a libraryRef value. #### Comments Applications must call this function when finished sending data or receiving data. It terminates the connection made with ExgConnect, ExgAccept, ExgPut, or ExgGet. 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 after 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 in the goToParams field. After the application returns from the sysAppLaunchCmdExgReceiveData launch code, the exchange library may call ExgNotifyGoto, which launches the goToCreator application with the standard launch code sysAppLaunchCmdGoto. IMPORTANT: Placing your creator ID in the goToCreator field is no longer a guarantee that you receive this launch code starting in Palm OS 4.0 because Palm OS 4.0 supports the sending of multiple objects at once. Thus, another application might overwrite the goToCreator field after your application has disconnected, making that application the recipient of the launch code. Note that some exchange libraries wait to establish a connection until ExgDisconnect is called. The IR Library, for example, buffers the data that it receives and then waits until ExgDisconnect to actually send this data unless ExgConnect is called to establish a multi-object send connection. #### Compatibility Implemented only if 3.0 New Feature Set is present. Prior to Palm OS release 4.0, the Exchange Manager always launched the goToCreator application, if one was provided, upon return from this function. If 4.0 New Feature Set is present, the Exchange Manager does not launch the goToCreator application. Exchange libraries that want the previous behavior must explicitly call ExgNotifyGoto. #### See Also ExgReceive, ExgSend ## ExgDoDialog #### Purpose Displays a dialog that allows users to accept or reject the receipt of data. #### Prototype Boolean ExgDoDialog (ExgSocketType *socketP, ExgDialogInfoType *infoP, Err *errP) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType) identifying the connection. A value must be provided for the libraryRef field.
#####
| Applications can obtain the socket structure from the sysAppLaunchCmdExgAskUser launch code parameter block.
#####
<-> infoP | A pointer to an ExgDialogInfoType structure (see the Comments 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 if the receiving application doesn't handle the sysAppLaunchCmdExgAskUser launch code or if it returns exgAskDialog from the launch code handler. When the Exchange Manager calls ExgDoDialog, the dialog displays a message similar to "Do you want to accept 'John Doe' into Address Book?" and allows the user to accept or reject the data. If the user clicks OK, the data should be received as an unfiled record. The Exchange Manager attempts to display a preview of the data in the exchange dialog to provide users with enough information to determine if they want to accept or reject the data. To display the preview data, it calls ExgNotifyPreview. Applications wishing to support preview mode should respond to the launch code sysAppLaunchCmdExgPreview. See the ExgNotifyPreview function's description for more information. Applications may also want to allow users to select a category in which to accept the incoming data. To do so, handle sysAppLaunchCmdExgAskUser to call ExgDoDialog directly 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 | A pointer to an open database that defines the categories the dialog should display.
#####
<- categoryIndex | The 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 category =
        (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 (category !- dmUnfiledCategory) {
        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) !=
          category) {
          attr &= ~dmRecAttrCategoryMask;
          attr |= category | dmRecAttrDirty;
          err = DmSetRecordInfo(dbP, indexNew,
            &attr, NULL);
        }
      }
    }
Some of the Palm OS built-in applications (Address Book, 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. Preview mode display in the exchange dialog is implemented only if 4.0 New Feature Set is present. ## ExgGet #### Purpose Establishes a connection and requests an object from a remote device. #### Prototype Err ExgGet (ExgSocketType *socketP) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType). Specify either a value for the libraryRef field or a URL in the name field. libraryRef should be 0 if the name field contains a URL. The target, type, or name fields should identify the data being requested.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrBadLibrary | Couldn't find default exchange library
exgErrUserCancel | The user cancelled the operation
exgMemError | There is not enough free memory to perform the operation
Other error codes depend on the exchange library. #### Comments Applications use this function to request data (initiate a send) from a remote device. Not all exchange libraries support this operation. Before calling this function, the application must initialize the socketP parameter. The socket should identify the exchange library to connect with by providing either a library reference number in the libraryRef field or a URL in the name field. The default exchange library registered for the URL's scheme handles the connection. The socket should also specify what data it is requesting by providing values for at least one of the target, name, and type fields. Specifying the data in the name field is the most common method. To provide users with a choice of transport mechanisms, the application can provide a URL that begins with a question mark (?). The Exchange Manager displays a dialog with a list of all exchange libraries that respond to URLs of the specified type. If only one exchange library is registered for this URL scheme, no dialog is displayed. If the library is not specified by either URL or library reference number, the Exchange Manager by default uses the IR Library; however, if the localMode flag is set, the Local Exchange Library is used instead. Applications can use ExgGet to initiate a send from the Local Exchange Library. For more information, see "Sending and Receiving Locally" of the Palm OS Programmer's Companion, vol. II, Communications. If no error is returned, applications should follow this call with one or more calls to ExgReceive, to receive the data, or ExgDisconnect, to disconnect. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgPut, ExgConnect ## New ExgGetDefaultApplication #### Purpose Retrieves the default application for the specified type of data or the default exchange library for URLs with the specified scheme. #### Prototype Err ExgGetDefaultApplication (UInt32 *creatorIDP, UInt16 id, const Char *dataTypeP) #### Parameters #####
<- creatorIDP | A pointer to the creator ID of the default application or default exchange library.
#####
-> id | The registry ID constant identifying the type of data in dataTypeP. See Registry ID Constants.
#####
-> dataTypeP | A pointer to a string that contains the type of data for which to retrieve the default application or library. If dataTypeP is a file extension, do not include the period (.). If it is a URL, do not include the colon (:).
#### Result Returns errNone if a match was found or exgErrNoKnownTarget if there is no default application or library for this type of data. #### Comments You might use this function to see which application on this device will receive a particular type of data or to see which library on this device handles URLs of a particular scheme. For example, to find out which application receives TXT files on this device, do the following:
    UInt32 creatorID;
    Err error;
    error = ExgGetDefaultApplication(&creatorID,
      exgRegExtensionID, "TXT");
    if (!error) {
        //creatorID contains default application.
To find out which exchange library handles URLs that use the beam prefix, do the following:
    UInt32 creatorID;
    Err error;
    error = ExgGetDefaultApplication(&creatorID,
      exgRegSchemeID, exgBeamScheme);
    if (!error) {
        //creatorID contains default library.
It's possible to have several applications registered to receive the same type of data, but none of them is the default. When the Exchange Manager receives an object of that type, it selects an application to receive the data, and it selects that same application every time. The selected application effectively becomes the default for the data type even though it is not explicitly set as the default. If this is the case, the ExgGetDefaultApplication function returns the creator ID of this de-facto default application. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgGetRegisteredApplications, ExgGetRegisteredTypes, ExgRegisterDatatype, ExgSetDefaultApplication ## New ExgGetRegisteredApplications #### Purpose Retrieves a list of all applications registered to receive data of a specified type. #### Prototype Err ExgGetRegisteredApplications (UInt32 **creatorIDsP, UInt32 *numAppsP, Char **namesP, Char **descriptionsP, UInt16 id, const Char *dataTypeP) #### Parameters #####
<- creatorIDsP | An array of the creator IDs of the applications registered to receive objects of this type. Pass NULL for this parameter if you only want to know how many applications are registered for this type.
#####
<- numAppsP | The number of applications registered to receive objects of this type. This is the number of elements in the creatorIDsP array, the namesP array, and the descriptionsP array.
#####
<- namesP | A packed list of strings, suitable for passing to SysFormPointerArrayToStrings, containing the names of the applications or libraries. Each string is no more than exgMaxTitleLen characters. Pass NULL for this parameter if you don't want to retrieve it.
#####
<- descriptionsP | A packed list of strings, suitable for passing to SysFormPointerArrayToStrings, containing the descriptions of the applications or libraries. Descriptions are specified when the applications or libraries register for data. Each string is no more than exgMaxDescriptionLength characters. Pass NULL for this parameter if you don't want to retrieve it.
#####
-> id | The registry ID constant identifying the type of data in dataTypeP. See Registry ID Constants.
#####
-> dataTypesP | A pointer to a tab-delimited, null-terminated string listing the items to register. (Use \t for the tab character.) Each item in the string must be no more than exgMaxTypeLength characters. There can be no more than 16 types total.
#### Result Returns errNone upon success or exgMemError if the function cannot allocate space for the creator IDs, names, or descriptions. IMPORTANT: This function allocates enough space for the creatorIDsP, namesP, and descriptionsP arrays as long as you do not pass NULL for the parameters. You are still responsible for freeing these arrays. #### Comments You might use this function to see which applications on this device can receive a particular type of data or to see which libraries on this device handle URLs of a particular scheme. You can also use it to built a list of choices from which the user can select a default application or default exchange library for a particular data type or URL scheme. For example, iMessenger uses this function to build a list of mailto handlers so that the user can choose one of them to be the default. The Exchange Manager itself uses ExgGetRegisteredApplications to find exchange libraries when it is given a URL that begins with a question mark (?). It displays the returned list to the user in the Send With dialog. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgGetDefaultApplication, ExgGetRegisteredTypes, ExgRegisterDatatype, ExgSetDefaultApplication ## New ExgGetRegisteredTypes #### Purpose Retrieve a list of all data types for which a registration exists. #### Prototype Err ExgGetRegisteredTypes (Char **dataTypesP, UInt32 *sizeP, UInt16 id) #### Parameters #####
<- dataTypesP | A packed list of strings, suitable for passing to SysFormPointerArrayToStrings, containing a sorted list of data types for which a registration exists. Each string is no more than exgMaxTypeLength characters.
#####
<- sizeP | The number of elements in the dataTypesP array.
#####
-> id | The type of data to search for. For example, you can search for all registered creator IDs, all registered MIME types, and so on.
#### Result Returns errNone upon success or exgMemError if the function cannot allocate space for the data types array. IMPORTANT: This function allocates enough space for the dataTypesP array as long as you do not pass NULL for the parameter. You are still responsible for freeing this array. #### Comments This function could be used to create an application that allows users to choose the default application for each data type. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgGetDefaultApplication, ExgGetRegisteredApplications, ExgRegisterDatatype, ExgSetDefaultApplication ## New ExgGetTargetApplication #### Purpose Retrieves the application that should receive a specific message. This function does not search for libraries. #### Prototype Err ExgGetTargetApplication (ExgSocketType *socketP, Boolean unwrap, UInt32 *creatorIDP, Char *descriptionP, UInt32 descriptionSize) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType). The structure should contain values for the target, type, or name fields.
#####
-> unwrap | If true, only an application that registered to receive the data type with the exgUnwrap flag set should be the target application. If false, the target application should be an application that registered with the exgUnwrap flag clear.
#####
<- creatorIDP | The creator ID of the application that should receive this object.
#####
<-> descriptionP | The application's description from the registry, if any.
#####
-> descriptionSize | The size of the descriptionP buffer.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrTargetMissing | The target field contains a creator ID, but the application with that creator ID does not exist
exgErrNoKnownTarget | No application is registered to receive the data type
#### Comments The Exchange Manager uses this function to determine which application should be launched to receive incoming data. Applications and libraries may call this function as well. ExgGetTargetApplication determines the target application by doing the following: If the socketP->target field contains a creator ID, the Exchange Manager searches the registry to see if an application is registered for that creator ID as the default application. If the registry does not contain an entry for the creator ID, it checks to see if the application identified by the creator ID is installed on this device. If an application is found for the target, that is the application returned. If the socketP->type field contains a MIME type, the Exchange Manager searches the registry for an application registered to receive objects of that type. If one is found, that is the application returned. If the socketP->name field contains a period (.), the portion after the last period is taken to be the file extension. The Exchange Manager searches the registry for an application registered to receive a file with the specified extension. If one is found, that is the application returned. If not, exgErrNoKnownTarget is returned. If more than one application is registered for the target, type, or file extension, this function returns the one that is registered as the default. If no application is registered as the default, then a specific application is chosen. The Exchange Manager chooses this same application each time. That is, each time a file with a TXT extension is sent with no target or MIME type specified, the ExgGetTargetApplication returns the same application to handle the receipt. Set the unwrap parameter to true if the object was sent as part of another object, such as a vStock object that was sent as an attachment to an e-mail message. In this case, the Exchange Manager searches for an application that registered to receive the target, the type, or the file extension of the vStock object with the exgUnwrap flag set. If an application is found, the vStock object is delivered, and the exchange library should discard the object that contained it (the e-mail message). If there is no application registered to receive the data with the exgUnwrap flag set, this function returns exgErrNoKnownTarget. In this case, the exchange library should call ExgNotifyReceive again passing the entire e-mail message instead of just the vStock attachment. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgSetDefaultApplication, ExgNotifyPreview, ExgNotifyReceive, ExgRegisterDatatype ## New ExgNotifyGoto #### Purpose Launches the target application using sysAppLaunchCmdGoto. #### Prototype Err ExgNotifyGoto (ExgSocketType *socketP, UInt16 flags) #### Parameters #####
-> socketP | A socket identifying the object to deliver (see ExgSocketType). The goToCreator field contains the application to be launched, and the goToParams field contains data for the launch code's parameter block.
#####
-> flags | Not currently used. Pass 0 for this parameter.
#### Result Returns one of the following error codes: #####
errNone | Success or the goToCreator field is empty
dmErr... (one of the data manager error codes) | The specified application could not be found
memErrNotEnoughSpace | Not enough memory available to create the launch code's parameter block
#### Comments Exchange libraries call this function if they want to support immediate display of the received object. Applications do not call this function. Most exchange libraries should call ExgNotifyGoto after the return from ExgNotifyReceive so that the user can inspect the newly received data. If the exchange library is most often used by a single application that does not require the launch code, this call to ExgNotifyGoto can be skipped. For example, the SMS Library does not call ExgNotifyGoto. SMS messages are received by the SMS Messenger application, which does not launch upon receiving data. ExgNotifyGoto only launches an application if one is specified in the goToCreator field and the noGoTo parameter is false. If a goToCreator is not specified, it is not considered an error. This gives the application a way to override the default behavior. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgNotifyReceive, ExgDisconnect ## New ExgNotifyPreview #### Purpose Displays a preview in the exchange dialog of the data to be received. #### Prototype Err ExgNotifyPreview (ExgPreviewInfoType *infoP) #### Parameters #####
<-> infoP | An ExgPreviewInfoType structure containing information about the preview operation.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrNotSupported | The exchange library doesn't support preview mode
exgErrNoKnownTarget | There is no application registered to receive the type of object
Other error codes depend on the application. #### Comments This function performs the preview operation specified in the op field of the infoP parameter. The ExgDoDialog function calls this function to show a data preview in the exchange dialog. Exchange libraries might want to call this function in certain circumstances. An application rarely calls this function, but it may do so if it displays its own dialog in response to the launch code sysAppLaunchCmdExgAskUser. ExgNotifyPreview uses ExgGetTargetApplication to determine the appropriate target application for this data and then launches that application with the launch code sysAppLaunchCmdExgPreview, passing infoP as the parameter block. The application responds to this launch code by accepting the connection, receiving the data from the exchange library, and depending on the operation requested, drawing the data into the infoP->bounds rectangle or returning it in the infoP->string field, and then disconnecting. The ExgDoDialog function uses the returned information to draw the preview portion of the dialog. If the preview data is a string, the ExgNotifyPreview provides a series of fallback strings that are used if the exchange library doesn't support preview or the application doesn't respond to the launch code. If the application fails to return a string, this function provides one of the following: the data's description from socketP->description the filename in socketP->name the target application's description as stored in the exchange registry the MIME type in socketP->type the file extension in socketP->name #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgNotifyReceive, ExgDisconnect ## ExgNotifyReceive #### Purpose Delivers an object to the appropriate application using the registry. #### Prototype Err ExgNotifyReceive (ExgSocketType *socketP, UInt16 flags) #### Parameters #####
<-> socketP | A pointer to the socket structure (see ExgSocketType).
#####
-> flags | A bit field. Pass 0 or a combination of the following constants (OR the constants together to specify more than one):
#####
exgUnwrap | The object being delivered should only be handled by an application that registered to receive it with the exgUnwrap flag set.
#####
exgNoAsk | Do not ask the user to confirm receipt of data. If this constant is passed, the target application does not receive the sysAppLaunchCmdExgAskUser launch code, and the Exchange Manager does not call ExgDoDialog to display the user confirmation dialog.
#####
exgGet | Specifies that this is a request for the application to send data rather than to receive data.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrTargetMissing | The target field contains a creator ID, but the application with that creator ID does not exist
exgErrNoKnownTarget | No application is registered to receive the data type
exgErrUserCancel | The user cancelled the operation
Other error codes depend on the application that is launched. #### Comments Exchange libraries call this function to initiate a receive operation on the receiving device. Applications do not call this function. The ExgNotifyReceive function uses ExgGetTargetApplication to determine which application should receive the data, then sends that application the appropriate launch codes. If the flags parameter is 0, a receive operation is assumed. The ExgNotifyReceive function does the following: 1. It sends the application the sysAppLaunchCmdExgAskUser launch code. 2. If the application returns exgAskDialog or does not respond to the launch code, it calls ExgDoDialog, which sends the application the sysAppLaunchCmdExgPreview launch code to have the application receive preview data for the dialog. 3. It sends the application the sysAppLaunchCmdExgReceiveData launch code to tell the application to receive the data. If the flags field contains the exgNoAsk flag, the first and second steps are skipped. If the flags field contains exgGet, this function is a request for data to send to the remote device, not a request to receive data from the remote device. In this case, ExgNotifyReceive launches the target application with the sysAppLaunchCmdExgGetData launch code. If the flags field has the exgUnwrap bit set, it means that the object to be received was sent as part of another object, and it should only be sent to an application that registered to receive it with the exgUnwrap flag set. For example, if the exchange library receives an e-mail message with an attached vStock object, the exchange library may call ExgNotifyReceive with the exgUnwrap flag set and a socket that describes the vStock data type to see if there is an application that registered to receive it directly. If no application is registered to receive vStock objects with the exgUnwrap flag set, ExgNotifyReceive returns exgErrNoKnownTarget. The exchange library should then call ExgNotifyReceive again, but this time without the exgUnwrap flag and with a socket that describes the e-mail message data type. This second call sends the object to the application registered to receive the e-mail message rather than its vStock attachment. That application may extract the vStock attachment from the message and use the Local Exchange Library to send it to an application registered to receive vStock objects normally (without the exgUnwrap flag). #### Compatibility Implemented only if 3.0 New Feature Set is present. ExgNotifyReceive was a system use only function until the release of Palm OS 4.0. If the 4.0 New Feature Set is not present, the flags parameter is not supported, so libraries cannot suppress the exchange dialog, send objects with attachments, or perform a get operation. These features are all added in the 4.0 New Feature Set. Also, if the 4.0 new feature set is not present, this function performs the equivalent of ExgNotifyGoto after the application has returned from receiving data. Exchange libraries wishing to support this functionality should call ExgNotifyGoto immediately after calling ExgNotifyReceive. #### See Also ExgNotifyPreview ## ExgPut #### Purpose Initiates the transfer of data to the destination device. #### Prototype Err ExgPut (ExgSocketType *socketP) #### Parameters #####
-> socketP | Pointer to the socket structure (see ExgSocketType). Specify either a value for the libraryRef field or a URL in the name field. libraryRef should be 0 if the name field contains a URL. The structure should also contain a value for the target, type, or name field.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrBadLibrary | Couldn't find default exchange library
exgMemError | Not enough memory to initialize transfer
exgErrNotEnoughPower | The battery does not have enough power to perform the operation
Other error codes depend on the exchange library. #### Comments Applications call this function to start a send operation. If the connection does not already exist, this function establishes one. You must create and initialize an ExgSocketType structure containing information about the data to send and the destination application. All unused fields in the structure must be set to 0. 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. The socket's libraryRef field or the name field must identify the library that performs the transfer. The libraryRef field identifies the exchange library by its library reference number. The name field identifies the library by URL. The socket should also specify what data is being sent by providing values for at least one of the target, name, and type fields. Use of the name field is the most common method. To provide users with a choice of transport mechanisms, the application can provide a URL that begins with a question mark (?). The Exchange Manager displays a dialog with a list of all exchange libraries that respond to URLs of the specified type. If only one exchange library is registered for this URL scheme, no dialog is displayed. For example, many applications on Palm OS 4.0 or higher support a Send command. This command generates a URL with the prefix exgSendPrefix (see Predefined URL Prefixes). The Exchange Manager displays a dialog containing a list of libraries registered for that URL scheme. The user selects an exchange library, and that library's ExgLibSend function is called. If the library is not specified by either URL or library reference number, the Exchange Manager by default uses the IR Library; however, if the localMode flag is set, the Local Exchange Library is used instead. #### Compatibility Implemented only if 3.0 New Feature Set is present. Support for identifying exchange libraries by URL is implemented only if 4.0 New Feature Set is present. #### See Also ExgDisconnect, ExgSend, ExgConnect ## ExgReceive #### Purpose Receives data from a remote device. #### Prototype UInt32 ExgReceive (ExgSocketType *socketP, void *bufP, UInt32 bufLen, Err *err) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType).
#####
<- bufP | A pointer to the buffer in which to receive the data.
#####
-> bufLen | The number of bytes to receive.
#####
<- err | A 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. The error code exgErrNotSupported is returned if the application calls this function during a preview and the exchange library does not have any more data available or does not support preview. May display a fatal error message if the library reference number is not provided in socketP. #### Comments Applications call this function in the following circumstances: In response to the sysAppLaunchCmdExgReceiveData launch code, following a successful call to ExgAccept. In response to the sysAppLaunchCmdExgPreview launch code, following a successful call to ExgAccept. To receive requested data following a successful call to ExgGet. After receiving the data, applications 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, exchange libraries can provide their own user interface that is shown during this call, is updated as necessary, and allows the user to cancel the operation in progress. #### Compatibility Implemented only if 3.0 New Feature Set is present. Preview mode and ExgGet are only supported if 4.0 New Feature Set is present. #### See Also ExgNotifyReceive ## New ExgRegisterDatatype #### Purpose Registers an application to receive a specific type of data, or registers an exchange library to handle specific URL schemes. #### Prototype Err ExgRegisterDatatype (UInt32 creatorID, UInt16 id, const Char *dataTypesP, const Char *descriptionsP, UInt16 flags) #### Parameters #####
-> creatorID | The creator ID of the registering application or exchange library.
#####
-> id | A registry ID constant identifying the type of the items being registered. See Registry ID Constants.
#####
-> dataTypesP | Pointer to a tab-delimited, null-terminated string listing the items to register. (Use "\t" for the tab character.) To unregister, pass a NULL value. Each item in the string must be no more than exgMaxTypeLength characters. There can be no more than 16 types total.
NOTE: If specifying file extensions, do not include the period (.) that precedes the extension. If specifying URL prefixes, do not include the colon (:) at the end of the prefix. #####
-> descriptionsP | Pointer to a tab-delimited, null-terminated string that lists descriptions for the items in the dataTypesP parameter. (Use "\t" for the tab character.) Each description must be no longer than exgMaxDescriptionLength. Pass NULL to leave out the descriptions.
#####
| There must either be one description for all types or the number of descriptions must match the number of types.
#####
| The descriptions are used in dialogs displayed by Exchange Manager to identify applications or libraries.
#####
-> flags | A bit field specifying registration options. Currently, only one bit is used: the unwrap bit. Pass the exgUnwrap constant to specify that the application is registering to receive objects of this type directly if the object is sent as part of another object. For example, if a vStock object is sent as an attachment to an email message, the Exchange Manager should send the vStock object to this application directly rather than sending the message to the email application.
#### Result Returns errNone if successful, exgMemError if there is not enough memory to save the registration info, or one of the data manager error codes (dmErr...). #### Comments Both applications and exchange libraries use this function to register with the Exchange Manager to receive certain types of data. Applications must register with the Exchange Manager to receive data objects that do not specifically target that application using the creator ID in the target field. Exchange libraries register to receive data with certain URL schemes. If an exchange library is not registered to receive URLs, it only handles the receipt and sending of data if its library reference number is explicitly specified in the ExgSocketType structure. Otherwise, the IR Library handles all incoming data for which a library could not be found. Both applications and libraries should register to receive data as soon as possible after they are installed and as soon as possible after a hard reset. For example, applications can call ExgRegisterDatatype in response to the sysAppLaunchCmdSyncNotify launch code, which they receive immediately after install. Exchange libraries implemented as applications can also use this strategy. Exchange libraries implemented as shared libraries should call ExgRegisterDatatype in their startup functions. Make only one call to ExgRegisterDatatype per registry type. If you want to register to receive multiple items, use a tab character (\t) to separate the items. If you were to, for example, make one call to register for the DOC file extension and one call to register for the TXT extension, the second call overwrites the first. However, if you want to register with the exgUnwrap flag set, make one call without the exgUnwrap flag and one call with the exgUnwrap flag set. The application registered with the exgUnwrap flag set is stored in a different part of the registry. 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:
    ExgRegisterDatatype(myCreator,
      exgRegExtensionID, "TXT", NULL, 0);
If the application wants to receive files with a TXT extension or with a DOC extension, it could register like this:
    ExgRegisterDatatype(myCreator,
      exgRegExtensionID, "TXT\tDOC", NULL, 0);
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:
    ExgRegisterDatatype(myCreator, exgRegTypeID,
    "text/x-setext", NULL, 0);
Specify exgRegCreatorID to register to receive data targeted for a particular creator ID. For example, if your application wants to handle all data intended for the ToDo application, it could register like this:
    Char toDoCreatorStr[5];
    MemMove(toDoCreatorStr, sysFileCToDo, 4);
    toDoCreatorStr[4] = chrNull;
    ExgRegisterDatatype(myCreator, exgRegCreatorID,
      toDoCreatorStr, NULL, 0);
NOTE: To override one application's receipt of data, you need to also set your application as the default for this creator ID. See ExgSetDefaultApplication. Most exchange libraries will want to register for a unique URL scheme that identifies only that library, plus they should register for a more general scheme, such as the send scheme (exgSendScheme), which causes the library to be listed in the Send With dialog when the user performs the Send command. The registry ID constant for URL prefixes is exgRegSchemeID.
    ExgRegisterDatatype(myLibCreator,
      exgRegSchemeID, myScheme "\t" exgSendScheme,
      NULL, 0);
Registrations are active until a hard reset or until the application or library is removed. The registration information is preserved 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 call ExgRegisterDatatype with a NULL value for the dataTypesP parameter. Multiple applications can be registered to receive the same type of data. If this is the case, the application that is registered as the default (using ExgSetDefaultApplication) is the one that receives the data unless the exchange socket explicitly specifies another application should receive it. If there is no default specified, the Exchange Manager determines a default. Multiple libraries may also be registered to receive the same type of URL. In this case, if the URL begins with a question mark (?), the Exchange Manager displays a dialog so that the user can select which exchange library to use. If the URL does not begin with a question mark, the exchange library registered as the default is used. If there is no default specified, the Exchange Manager determines a default. #### Compatibility Implemented only if 4.0 New Feature Set is present. ExgRegisterDatatype replaces the ExgRegisterData function. #### See Also ExgRegisterData, ExgGetTargetApplication, ExgPut, ExgGetDefaultApplication, ExgGetRegisteredApplications, ExgGetRegisteredTypes ## ExgRegisterData #### Purpose Registers an application to receive a specific type of data. This function is deprecated and replaced with ExgRegisterDatatype. #### Prototype Err ExgRegisterData (UInt32 creatorID, UInt16 id, const Char *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 PoweredTM handheld 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. #### Compatibility This function corresponds to the Palm OS 3.5 version of ExgRegisterDatatype. It is implemented only if 3.0 New Feature Set is present. ## New ExgRequest #### Purpose Requests some data from an exchange library or an application using a URL. #### Prototype Err ExgRequest (ExgSocketType *socketP) #### Parameters #####
-> socketP | Pointer to the socket structure (see ExgSocketType). Specify a URL in the name field and a libraryRef of 0.
#### Result Returns one of the following error codes: #####
errNone | Success
exgErrBadLibrary | Couldn't find default exchange library
exgErrNotEnoughPower | The device does not have enough power to perform the operation
sysErrLibNotFound | Couldn't find library or application to respond to URL
Other error codes depend on the exchange library or application. #### Comments The ExgRequest function is similar to ExgGet in that both are used to request data. The difference is that the application that calls ExgGet is always the application that receives the data. When you call ExgRequest, the application that receives the data is the application that is registered to receive it. For example, using ExgRequest, it is possible for one application to use the Exchange Manager to retrieve a vCard using any supported transport mechanism and have that data sent directly to the Address Book application instead of to the calling application. The socketP passed to this function identifies the exchange library using a URL in the name field. The application must know before-hand the proper URL prefix for the exchange library with which it wants to connect. See Predefined URL Prefixes for a list of URL prefixes that the Exchange Manager provides. If the provided URL begins with a question mark (?) and there are several exchange libraries registered for the specified URL scheme, the Exchange Manager displays a dialog from which the user selects the appropriate transport mechanism. If the Exchange Manager cannot find a library that is registered for the specified URL, it assumes that an application is registered to receive the URL, and it launches that application with the sysAppLaunchCmdGoToURL launch code. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgGet, ExgNotifyReceive ## ExgSend #### Purpose Sends data to the destination device. #### Prototype UInt32 ExgSend (ExgSocketType *socketP, const void *bufP, UInt32 bufLen, Err * err) #### Parameters #####
-> socketP | A pointer to the socket structure (see ExgSocketType). A value must be provided for the libraryRef field. The structure should also contain values for the target, type, or name fields.
#####
-> bufP | A pointer to the data to send.
#####
-> bufLen | The number of bytes to send.
#####
<- err | A pointer to an error code result.
#### Result Returns the number of bytes actually 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. May display a fatal error message if the socketP parameter does not contain a value for the libraryRef field. #### 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 exchange library 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, the exchange library may provide its own user interface that is updated as necessary and allows the user to cancel the operation in progress. #### Compatibility Implemented only if 3.0 New Feature Set is present. #### See Also ExgReceive, ExgGet ## New ExgSetDefaultApplication #### Purpose Sets the application that receives a specified type of data by default. This function also sets the default exchange library that handles particular URL schemes. #### Prototype Err ExgSetDefaultApplication (UInt32 creatorID, UInt16 id, const Char *dataTypeP) #### Parameters #####
-> creatorID | The creator ID of the application or library that should become the default for this type of data.
#####
-> id | A registry ID constant identifying the type of data in dataTypeP. See Registry ID Constants.
#####
-> dataTypesP | A pointer to a null-terminated string containing the desired type of data.
NOTE: If specifying a file extension, do not include the period (.) that precedes the extension. If specifying a URL prefix, do not include the colon (:) at the end of the prefix. #### Result Returns errNone upon success or exgErrNoKnownTarget if the specified application is not registered to receive the specified data type. #### Comments This function sets the default application that receives data of a certain type when no target is specified and the default exchange library that handles URLs with a certain prefix if no library reference number is specified. PalmTM strongly recommends that applications allow the user to determine which application should become the default recipient for a data type. To do so, an application can use ExgGetRegisteredApplications to get the list of applications registered for the same type of data as it is, and then display a dialog listing those applications and allow the user to select it. Then it should call ExgSetDefaultApplication with the user-specified default. If you call ExgSetDefaultApplication with an application or library that is already the default, this function has no effect. An application can become the default for its own creator ID even if it has not specifically registered to receive its own creator ID. That is, suppose several applications are registered to receive objects targeted for the ToDo application's creator ID. The ToDo application itself is not registered for its own creator ID, as it is not necessary to do so. However, an application can use code like the following to set the ToDo application as the default for its own creator ID.
    Char toDoCreatorStr[5];
    MemMove(toDoCreatorStr, sysFileCToDo, 4);
    toDoCreatorStr[4] = chrNull;
    ExgSetDefaultApplication(sysFileCToDo,
      exgRegCreatorID, toDoCreatorStr);
#### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also ExgGetDefaultApplication, ExgRegisterDatatype ## Application-Defined Functions ## DeleteProc #### Purpose Handles 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.
#####
-> version | The version of the identical database.
#####
-> cardNo | The card number of the identical database.
#####
-> dbID | The database ID of the identical database.
#####
-> userDataP | The userDataP parameter you passed to ExgDBRead. If used, this parameter contains any application-specific data you find necessary. If the ReadProc function is implemented using Exchange Manager calls, this often contains the ExgSocketType structure.
#### Result Return true to have the ExgDBRead function continue to read the database. Use this return value if you have deleted or moved the existing database or if you want the database to be overwritten. Return false to have ExgDBRead exit without reading the database. #### Comments This function is called if the Data Manager can't create the incoming database because a database with the same name already exists. You should delete the existing database or take some other action, such as changing the database name. It is appropriate to prompt the user before choosing to delete or move the database. ## ReadProc #### Purpose Reads 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. This buffer is allocated in the dynamic heap by ExgDBRead; you don't need to use DmWrite when filling it.
#####
<-> 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 you passed to ExgDBRead. Pass the ExgSocketType structure if you implement this function using Exchange Manager calls.
#### Result Return 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. #### Comments ExgDBRead is commonly used to receive a database from a beam or from some other transport mechanism. In this case, an appropriate implementation of this callback function is to call ExgReceive as shown here:
    Err MyReadDBProc (void *dataP, UInt32 *sizeP,
      void *userDataP)
    {
      Err err = errNone;
      //userDataP contains ExgSocketType pointer.
      *sizeP =
        ExgReceive((ExgSocketType *)userDataP,
          dataP, *sizeP, &err);
      return err;
    }
## 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, set sizeP to the number of bytes you did write.
#####
-> userDataP | The userDataP parameter you passed to ExgDBWrite. You can use it for application-specific data. Pass the ExgSocketType structure if you implement this function using Exchange Manager calls.
#### Result Return 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. #### Comments ExgDBWrite is commonly used to write a database that is going to be beamed to another device (or sent through some other transport mechanism). In this case, an appropriate implementation of this callback function is to call ExgSend as shown here:
    Err MyWriteDBProc (void *dataP, UInt32 *sizeP,
      void *userDataP)
    {
      Err err = errNone;
      //userDataP contains ExgSocketType pointer.
      *sizeP =
        ExgSend((ExgSocketType *)userDataP,
          dataP, *sizeP, &err);
      return err;
    }