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

62    Exchange Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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:

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 ^TOP^

ExgAskResultType Enum ^TOP^

Purpose

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

Prototype

typedef enum { 
exgAskDialog,
exgAskOk,
exgAskCancel
} ExgAskResultType;

Constants

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 Struct ^TOP^

Purpose

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.

Prototype

typedef struct {
UInt16dbCardNo;
LocalIDdbID;
UInt16recordNum;
UInt32uniqueID;
UInt32matchCustom;
} ExgGoToType;

Fields

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.

ExgLocalSocketInfoType Struct ^TOP^

Purpose

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.

Prototype

typedef struct {
Boolean freeOnDisconnect;
Boolean noAsk;
ExgPreviewInfoType *previewInfoP;
FileHand tempFileH;
Err err;
ExgLocalOpType op;
} ExgLocalSocketInfoType;

Fields

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.

ExgPreviewInfoType Struct ^TOP^

Purpose

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.

Prototype

typedef struct {
UInt16 version;
ExgSocketType *socketP;
UInt16 op;
Char *string;
UInt32 size;
RectangleType bounds;
UInt16 types;
Err error;
} ExgPreviewInfoType;

Fields

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 Struct ^TOP^

Purpose

The ExgSocketType structure defines an Exchange Manager socket, which is passed to most Exchange Manager functions. The ExgSocketPtr type points to a ExgSocketType structure.

Prototype

typedef struct ExgSocketType {
UInt16libraryRef;
UInt32socketRef;
UInt32target;
UInt32count;
UInt32length;
UInt32time;
UInt32appData;
UInt32goToCreator;
ExgGoToTypegoToParams;
UInt16localMode:1;
UInt16packetMode:1;
UInt16noGoTo:1;
UInt16noStatus:1;
UInt16preview:1;
UInt16reserved: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.

Fields

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 ^TOP^

Registry ID Constants ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

ExgAccept Function ^TOP^

Purpose

Accepts a connection from a remote device.

Declared In

ExgMgr.h

Prototype

Err ExgAccept (
   ExgSocketType*socketP
)

Parameters

socketP
A pointer to the socket structure (see ExgSocketType).

Returns

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 Function ^TOP^

Purpose

Establishes a connection with a remote socket.

Declared In

ExgMgr.h

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.

Returns

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()

ExgControl Function ^TOP^

Purpose

Requests that an exchange library perform an operation.

Declared In

ExgMgr.h

Prototype

Err ExgControl (
   ExgSocketType*socketP,
   UInt16op,
   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.

Returns

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 62.1 lists and describes the predefined Exchange Manager operations.

Table 62.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 Function ^TOP^

Purpose

Converts a Palm OS database from its internal format and writes it to storage RAM.

Declared In

ExgMgr.h

Prototype

Err ExgDBRead (
   ExgDBReadProcPtrreadProcP,
   ExgDBDeleteProcPtrdeleteProcP,
   void*userDataP,
   LocalID*dbIDP,
   UInt16cardNo,
   Boolean*needResetP,
   BooleankeepDates
)

Parameters

readProcP
A pointer to a function that reads in the database and passes it to ExgDBRead. See ExgDBReadProcPtr() for details.
deleteProcP
A pointer to a function that is called if a database with an identical name already exists on the device. See ExgDBDeleteProcPtr() 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 is to be stored.
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.

Returns

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 ExgDBDeleteProcPtr() for more information.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

ExgDBWrite()

ExgDBWrite Function ^TOP^

Purpose

Converts a given Palm OS database from its internal format on the local device and writes it using a function you supply.

Declared In

ExgMgr.h

Prototype

Err ExgDBWrite (
   ExgDBWriteProcPtrwriteProcP,
   void*userDataP,
   constchar*nameP,
   LocalIDdbID,
   UInt16cardNo
)

Parameters

writeProcP
A pointer to a function that writes out the database identified by dbID. See ExgDBWriteProcPtr() 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.

Returns

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 Function ^TOP^

Purpose

Terminates an Exchange Manager transfer and disconnects.

Declared In

ExgMgr.h

Prototype

Err ExgDisconnect (
   ExgSocketType*socketP,
   Errerror
)

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.

Returns

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 Function ^TOP^

Purpose

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

Declared In

ExgMgr.h

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.

Returns

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:

Prototype

typedef struct {
UInt16 version;
DmOpenRef db;
UInt16 categoryIndex;
} ExgDialogInfoType;

Parameters

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 Function ^TOP^

Purpose

Establishes a connection and requests an object from a remote device.

Declared In

ExgMgr.h

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.

Returns

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; for example, neither the IR Library nor Bluetooth support it.

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()

ExgGetDefaultApplication Function ^TOP^

Purpose

Retrieves the default application for the specified type of data or the default exchange library for URLs with the specified scheme.

Declared In

ExgMgr.h

Prototype

Err ExgGetDefaultApplication (
   UInt32*creatorIDP,
   UInt16id,
   constChar*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 (:).

Returns

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()

ExgGetRegisteredApplications Function ^TOP^

Purpose

Retrieves a list of all applications registered to receive data of a specified type.

Declared In

ExgMgr.h

Prototype

Err ExgGetRegisteredApplications (
   UInt32**creatorIDsP,
   UInt32*numAppsP,
   Char**namesP,
   Char**descriptionsP,
   UInt16id,
   constChar*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.

Returns

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()

ExgGetRegisteredTypes Function ^TOP^

Purpose

Retrieve a list of all data types for which a registration exists.

Declared In

ExgMgr.h

Prototype

Err ExgGetRegisteredTypes (
   Char**dataTypesP,
   UInt32*sizeP,
   UInt16id
)

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.

Returns

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()

ExgGetTargetApplication Function ^TOP^

Purpose

Retrieves the application that should receive a specific message. This function does not search for libraries.

Declared In

ExgMgr.h

Prototype

Err ExgGetTargetApplication (
   ExgSocketType*socketP,
   Booleanunwrap,
   UInt32*creatorIDP,
   Char*descriptionP,
   UInt32descriptionSize
)

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.

Returns

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()

ExgNotifyGoto Function ^TOP^

Purpose

Launches the target application using sysAppLaunchCmdGoTo.

Declared In

ExgMgr.h

Prototype

Err ExgNotifyGoto (
   ExgSocketType*socketP,
   UInt16flags
)

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.

Returns

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()

ExgNotifyPreview Function ^TOP^

Purpose

Displays a preview in the exchange dialog of the data to be received.

Declared In

ExgMgr.h

Prototype

Err ExgNotifyPreview (
   ExgPreviewInfoType*infoP
)

Parameters

infoP
An ExgPreviewInfoType structure containing information about the preview operation.

Returns

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 Function ^TOP^

Purpose

Delivers an object to the appropriate application using the registry.

Declared In

ExgMgr.h

Prototype

Err ExgNotifyReceive (
   ExgSocketType*socketP,
   UInt16flags
)

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.

Returns

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 Function ^TOP^

Purpose

Initiates the transfer of data to the destination device.

Declared In

ExgMgr.h

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.

Returns

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 Function ^TOP^

Purpose

Receives data from a remote device.

Declared In

ExgMgr.h

Prototype

UInt32 ExgReceive (
   ExgSocketType*socketP,
   void*bufP,
   UInt32bufLen,
   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.

Returns

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:

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()

ExgRegisterDatatype Function ^TOP^

Purpose

Registers an application to receive a specific type of data, or registers an exchange library to handle specific URL schemes.

Declared In

ExgMgr.h

Prototype

Err ExgRegisterDatatype (
   UInt32creatorID,
   UInt16id,
   constChar*dataTypesP,
   constChar*descriptionsP,
   UInt16flags
)

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.

Returns

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 Function ^TOP^

Purpose

Registers an application to receive a specific type of data. This function is deprecated and replaced with ExgRegisterDatatype().

Declared In

ExgMgr.h

Prototype

Err ExgRegisterData (
   UInt32creatorID,
   UInt16id,
   constChar*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.

Returns

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 Powered 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.

ExgRequest Function ^TOP^

Purpose

Requests some data from an exchange library or an application using a URL.

Declared In

ExgMgr.h

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.

Returns

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 Function ^TOP^

Purpose

Sends data to the destination device.

Declared In

ExgMgr.h

Prototype

UInt32 ExgSend (
   ExgSocketType*socketP,
   constvoid*bufP,
   UInt32bufLen,
   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.

Returns

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()

ExgSetDefaultApplication Function ^TOP^

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.

Declared In

ExgMgr.h

Prototype

Err ExgSetDefaultApplication (
   UInt32creatorID,
   UInt16id,
   constChar*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.

Returns

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.

Palm 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 ^TOP^

ExgDBDeleteProcPtr Function ^TOP^

Purpose

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

Declared In

ExgMgr.h

Prototype

Boolean (
   *ExgDBDeleteProcPtr
) (
   constchar*nameP,
   UInt16version,
   UInt16cardNo,
   LocalIDdbID,
   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 ExgDBReadProcPtr() function is implemented using Exchange Manager calls, this often contains the ExgSocketType structure.

Returns

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.

ExgDBReadProcPtr Function ^TOP^

Purpose

Reads in the database and pass it to ExgDBRead().

Declared In

ExgMgr.h

Prototype

Err (
   *ExgDBReadProcPtr
) (
   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.

Returns

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; 
} 

ExgDBWriteProcPtr Function ^TOP^

Purpose

Writes out the database.

Declared In

ExgMgr.h

Prototype

Err (
   *ExgDBWriteProcPtr
) (
   constvoid*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.

Returns

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; 
}