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

5    Exchange Manager Reference

High-Level Communications

Exploring Palm OS®

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 Chapter 4, "Object Exchange."

Exchange Manager Data Structures ^TOP^

ExgAskParamType Struct ^TOP^

Purpose

The ExgAskParamType structure is the parameter block for the sysAppLaunchCmdExgAskUser launch code.

Declared In

ExgMgr.h

Prototype

typedef struct {
   ExgSocketPtr socketP;
   ExgAskResultType result;
   uint8_t reserved;
   uint16_t padding_1;
} ExgAskParamType;

Fields

socketP
Socket pointer (see ExgSocketType).
result
One of the ExgAskResultType enumerated values.
reserved
Reserved for future use.
padding_1
Padding; not used.

ExgCtlGetURLType Struct ^TOP^

Purpose

The ExgCtlGetURLType structure identifies the URL of a remote device as returned by the ExgControl()function with the exgLibCtlGetURL operation code.

Declared In

ExgMgr.h

Prototype

typedef struct ExgCtlGetURLType{
   ExgSocketType *socketP;
   char *URLP;
   uint16_t URLSize;
   uint16_t padding;
} ExgCtlGetURLType;

Fields

socketP
Pointer to the socket structure (see ExgSocketType).
URLP
Pointer to the URL string.
URLSize
Size of the URL string.
padding
Padding; not used.

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.

Declared In

ExgMgr.h

Prototype

typedef struct {
   LocalID dbID;
   uint32_t recordNum;
   uint32_t uniqueID;
   uint32_t matchCustom;
} ExgGoToType;

Fields

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.

Declared In

ExgLocalLib.h

Prototype

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

Fields

freeOnDisconnect
Determines 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. For example, if you want to 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. The preview feature is deprecated and is maintained only for backward compatibility.
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 constants:
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 preview feature is deprecated and is maintained only for backward compatibility. Applications should no longer implement preview via this mechanism, but should follow the data viewing guidelines described in "Put with View Mode."

Declared In

ExgMgr.h

Prototype

typedef struct {
   uint16_t version;
   uint16_t padding1;
   ExgSocketType *socketP;
   uint16_t op;
   uint16_t padding2;
   char *string;
   uint32_t size;
   RectangleType bounds;
   uint16_t types;
   uint16_t padding3;
   status_t error;
} ExgPreviewInfoType;

Fields

version
Set this field to 0 to specify version 0 of this structure.
padding1
Padding; not used.
socketP
A pointer to the socket structure (see ExgSocketType). The name field must identify the exchange library from which data should be received, and the target or type 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.
padding2
Padding; not used.
string
A buffer into which the application places the string preview if exgPreviewLongString or exgPreviewShortString is specified in op.
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 in op.
types
Upon return from an exgPreviewQuery operation, a bit field identifying the types of previews the application supports.
padding3
Padding; not used.
error
The error code returned from the application. If errNone, the preview operation was successful.

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.

Declared In

ExgMgr.h

Prototype

typedef struct ExgSocketTag {
   uint16_t libraryRef;
   uint16_t socketRefSize;
   uint32_t socketRef;
   uint32_t target;
   uint32_t count;
   uint32_t length;
   uint32_t time;
   uint32_t appData;
   uint32_t goToCreator;
   ExgGoToType goToParams;
   uint16_t localMode:1;
   uint16_t packetMode:1;
   uint16_t noGoTo:1;
   uint16_t noStatus:1;
   uint16_t preview:1;
   uint16_t cnvFrom68KApp:1;
   uint16_t acceptedSocket:1;
   uint16_t reserved:9;
   uint8_t componentIndex;
   uint8_t padding_1;
   char *description;
   char *type;
   char *name;
} ExgSocketType;
typedef ExgSocketTag *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. This is no longer used for ARM code development, but is kept for compatibility with 68K exchange libraries.
When sending data, applications may identify the exchange library they want to connect with by providing a URL in the name field, and should use 0 for the libraryRef field.
socketRefSize
Size of the data block referenced by socketRef, if socketRef is a pointer to a data block.
socketRef
The connection identifier. This value is supplied by the exchange library when a connection is established. It contains any necessary library-specific data. For an ARM exchange library, this must be a single data block without pointer references to other blocks.
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). For an ARM exchange library, do not pass pointer values here; only the 32-bit value itself is safe.
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
Deprecated; set to 0. To use local exchange, specify a URL with the exgLocalPrefix. (Note that this flag still works for backward compatibility.)
packetMode
Deprecated; set to 0.
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. The preview feature is deprecated and is maintained only for backward compatibility.
cnvFrom68KApp
If set to 1, indicates that the socket was created by a 68K application. This lets the library know that it may need to convert some data (such as the socketRef data).
acceptedSocket
If set to 1, indicates that this socket was passed into ExgAccept().
reserved
Reserved system flags.
componentIndex
The Exchange Manager C++ component holding this socket (if any). Nonzero for valid sockets.
padding_1
Padding; not used.
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.

Exchange Manager Constants ^TOP^

ExgAskResultType Enum ^TOP^

Purpose

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

Declared In

ExgMgr.h

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.

Registry ID Constants ^TOP^

Purpose

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.

Declared In

ExgMgr.h

Constants

#define 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.
#define 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.
#define 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.
#define 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.
#define exgRegDirectCreatorID 0xffeb
Register for a creator ID for direct delivery. The target field of the ExgSocketType contains the creator ID of the application that should directly receive the data instead of an email application. (This is used instead of the exgUnwrap flag and must not be used with it.)
#define exgRegDirectExtensionID 0xffed
Register for a filename extension for direct delivery. 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, instead of an email application. (This is used instead of the exgUnwrap flag and must not be used with it.)
#define exgRegDirectTypeID 0xffee
Register for a MIME type for direct delivery. If the type field of the ExgSocketType contains a value, the application registered to receive that MIME type handles the message instead of an email application. (This is used instead of the exgUnwrap flag and must not be used with it.)
#define exgRegViewCreatorID 0xff8b
Register for a creator ID for view mode. The target field of the ExgSocketType contains the creator ID of an application that can be used to view the data.
#define exgRegViewExtensionID 0xff8d
Register for a filename extension for view mode. 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 can be used to view the data.
#define exgRegViewTypeID 0xff8e
Register for a MIME type. If the type field of the ExgSocketType contains a value, the application registered to receive that MIME type can be used to view the data.

Predefined URL Schemes ^TOP^

Purpose

The Exchange Manager provides these predefined URL schemes, for which exchange libraries can register.

Declared In

ExgMgr.h and ExgLocalLib.h

Constants

#define exgBeamScheme "_beam"
The URL scheme for Beam commands. By default, the IR Library handles this scheme.
#define 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.
#define exgGetScheme "_get"
The URL scheme for the Get mechanism.
#define exgLocalScheme "_local"
The URL scheme for the Local Exchange Library.

Predefined URL Prefixes ^TOP^

Purpose

The Exchange Manager provides these 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.

Declared In

ExgMgr.h

Constants

#define exgBeamPrefix exgBeamScheme ":"
The URL to beam data.
#define 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.
#define 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.
#define exgLocalPrefix exgLocalScheme ":"
The URL for using the Local Exchange Library.
#define exgGetPrefix exgGetScheme ":"
The URL for using the Get mechanism.

Exchange Manager Launch Codes ^TOP^

sysAppLaunchCmdExgAskUser ^TOP^

Purpose

The Exchange Manager sends this launch code to an application when data has arrived for that application. This launch code allows the application to tell the Exchange Manager not to display the exchange dialog, which it uses to have the user confirm the receipt of data. If the application does not handle this launch code, the default course of action is that the Exchange Manager displays the exchange dialog.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdExgAskUser 27


Parameters

The launch code's parameter block pointer references a ExgAskParamType structure.

Comments

Applications may want to respond to this launch code under these circumstances:

  • To reject all incoming data or to reject data under certain circumstances without first prompting the user. To reject incoming data, set the result field of the parameter block to exgAskCancel and then return.
  • To receive incoming data without confirmation. To automatically receive incoming data, set the result field to exgAskOk.
  • To provide a user confirmation dialog with extra functionality. This is described in more detail below.

The Exchange Manager allows applications to provide extra functionality in the exchange dialog. You can have the dialog include a category pop-up list from which the user chooses a category in which to file the incoming data. If you want to provide a category pop-up list, call the ExgDoDialog() function in response to this launch code and pass it a database that contains the categories to be listed. See the description of this function for more information.

Applications may also bypass the call to ExgDoDialog() altogether and provide their own dialogs.

If an application responds to this launch code, it must set the result field in the parameter block to the appropriate value. Possible values are defined by the ExgAskResultType enum.

If you don't use the default version of the dialog, return exgAskOk if the user confirmed or exgAskCancel if the user canceled. If you don't set the result field properly, two dialogs are displayed.

See Also

sysAppLaunchCmdExgPreview, and Chapter 6, "Common Launch Codes," in Exploring Palm OS: Programming Basics

sysAppLaunchCmdExgGetData ^TOP^

Purpose

The Exchange Manager sends this launch code when the exchange library requests data to be sent to a remote device. That is, an application on a remote device has called the ExgGet() function to request data, and the Exchange Manager has determined that the launched application should handle the request.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdExgGetData 59


Parameters

The parameter block sent with this launch code is a pointer to the ExgSocketType structure corresponding to the Exchange Manager connection on which the data is to be sent. You pass this socket pointer to ExgAccept(). For more details, see "Responding to a Get Request."

Comments

To respond to this launch code, applications should accept a connection with ExgAccept(), use ExgSend() to send the data, and call ExgDisconnect() when finished.

See Also

Chapter 6, "Common Launch Codes," in Exploring Palm OS: Programming Basics

sysAppLaunchCmdExgPreview ^TOP^

Purpose

Sent after sysAppLaunchCmdExgAskUser to have the application display the preview in the exchange dialog.

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdExgPreview 57


Parameters

The launch code's parameter block pointer references a ExgPreviewInfoType structure.

Comments

This launch command is deprecated and is maintained only for backward compatibility. Applications should no longer implement preview via this mechanism, but should follow the data viewing guidelines described in "Put with View Mode."

See Also

Chapter 6, "Common Launch Codes," in Exploring Palm OS: Programming Basics

sysAppLaunchCmdExgReceiveData ^TOP^

Purpose

The Exchange Manager sends this launch code following the sysAppLaunchCmdExgAskUser and sysAppLaunchCmdExgPreview launch codes to notify the application that it should receive the data (assuming that the application or the user has indicated the data should be received).

Declared In

CmnLaunchCodes.h

Prototype

#define sysAppLaunchCmdExgReceiveData 26


Parameters

The parameter block sent with this launch code is a pointer to the ExgSocketType structure corresponding to the Exchange Manager connection on which the data is arriving. Pass this pointer to the ExgAccept() function to begin receiving the data. For more details, see "Receiving the Data."

Comments

The application should use Exchange Manager functions to receive the data and store it or do whatever it needs to with the data. Specifically, most applications should respond to this launch code by calling ExgAccept() to accept the connection and then ExgReceive() to receive the data.

Note that the application may not be the active application, and thus may not have globals available when it is launched with this launch code. You can check if you have globals by using this code in the PilotMain() function:


Boolean appIsActive = launchFlags & sysAppLaunchFlagSubCall; 

The appIsActive value is true if your application is active and globals are available; otherwise, you won't be able to access any of your global variables during the receive operation.

See Also

Chapter 6, "Common Launch Codes," in Exploring Palm OS: Programming Basics

Exchange Manager Functions ^TOP^

ExgAccept Function ^TOP^

Purpose

Accepts a connection from a remote device.

Declared In

ExgMgr.h

Prototype

status_t ExgAccept (
   ExgSocketPtr 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 doesn't support preview mode

Other error codes depend on the exchange library.

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.

See Also

ExgConnect(), ExgPut(), ExgGet()

ExgConnect Function ^TOP^

Purpose

Establishes a connection with a remote socket.

Declared In

ExgMgr.h

Prototype

status_t ExgConnect (
   ExgSocketPtr socketP
)

Parameters

socketP
A pointer to the socket structure (see ExgSocketType). Specify a URL in the name field and 0 for the libraryRef field.

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" 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 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 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 URL, 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.

See Also

ExgPut(), ExgAccept(), ExgGet()

ExgControl Function ^TOP^

Purpose

Requests that an exchange library perform an operation.

Declared In

ExgMgr.h

Prototype

status_t ExgControl (
   ExgSocketType *socketP,
   uint16_t op,
   void *valueP,
   uint16_t *valueLenP
)

Parameters

socketP
A pointer to the socket structure (see ExgSocketType). Specify a URL in the name field and 0 for the libraryRef field.
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 5.1 lists and describes the predefined Exchange Manager operations.

Table 5.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. The preview feature is deprecated and is maintained only for backward compatibility.

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.

URL

ExgCtlGetURLType structure.

Returns the URL that addresses the remote device from which you receive data. You can get the URL after calling ExgAccept().

Version

uint16_t. 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. Operations specific to an exchange library are numbered starting at exgLibCtlSpecificOp.

The socketP passed to this function must identify an exchange library with a URL in the name field. The Comments section in ExgConnect() describes how an application should identify the exchange library.

ExgDBRead Function ^TOP^

Purpose

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

Declared In

ExgMgr.h

Prototype

status_t ExgDBRead (
   ExgDBReadProcPtr readProcP,
   ExgDBDeleteProcPtr deleteProcP,
   void *userDataP,
   DatabaseID *dbIDP,
   Boolean *needResetP,
   Boolean keepDates
)

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

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

status_t ExgDBWrite (
   ExgDBWriteProcPtr writeProcP,
   void *userDataP,
   const char *nameP,
   DatabaseID dbID
)

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.

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.

See Also

ExgDBRead()

ExgDisconnect Function ^TOP^

Purpose

Terminates an Exchange Manager transfer and disconnects.

Declared In

ExgMgr.h

Prototype

status_t ExgDisconnect (
   ExgSocketPtr socketP,
   status_t 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.

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.

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 not a guarantee that you receive this launch code, because Palm OS 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.

The Exchange Manager does not automatically launch the goToCreator application, if one was provided, upon return from this function. Exchange libraries that want this 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,
   status_t *errP
)

Parameters

socketP
A pointer to the socket structure (see ExgSocketType) identifying the connection.
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(). 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_t version;
  DmOpenRef db;
  uint16_t 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_t 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_t attr; 
    status_t 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.

ExgGet Function ^TOP^

Purpose

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

Declared In

ExgMgr.h

Prototype

status_t ExgGet (
   ExgSocketPtr socketP
)

Parameters

socketP
A pointer to the socket structure (see ExgSocketType). Specify a URL in the name field and 0 for the libraryRef field. The target or type 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

exgErrNotSupported

The exchange library doesn't support this function

Other error codes depend on the exchange library.

Comments

Applications use this function to request data (initiate a send) from a remote or local device. Not all exchange libraries support this operation; among the exchange libraries built into the Palm OS only the Local Exchange library supports it.

Before calling this function, the application must initialize the socketP parameter. The socket should identify the exchange library to connect with by providing 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 URL, 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".

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.

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

status_t ExgGetDefaultApplication (
   uint32_t *creatorIDP,
   uint16_t 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 (:).

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_t creatorID; 
status_t 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_t creatorID; 
status_t 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.

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

status_t ExgGetRegisteredApplications (
   uint32_t **creatorIDsP,
   uint32_t *numAppsP,
   char **namesP,
   char **descriptionsP,
   uint16_t 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.

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.

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.

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

status_t ExgGetRegisteredTypes (
   char **dataTypesP,
   uint32_t *sizeP,
   uint16_t 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.

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.

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

status_t ExgGetTargetApplication (
   ExgSocketType *socketP,
   Boolean unwrap,
   uint32_t *creatorIDP,
   char *descriptionP,
   uint32_t 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. Note that usage of the exgUnwrap flag is deprecated.
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 email 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 email 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 email message instead of just the vStock attachment.

See Also

ExgSetDefaultApplication(), ExgNotifyPreview(), ExgNotifyReceive(), ExgRegisterDatatype()

ExgNotifyGoto Function ^TOP^

Purpose

Launches the target application using sysAppLaunchCmdGoTo.

Declared In

ExgMgr.h

Prototype

status_t ExgNotifyGoto (
   ExgSocketType *socketP,
   uint16_t 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.

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() launches an application only 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.

See Also

ExgNotifyReceive(), ExgDisconnect()

ExgNotifyPreview Function ^TOP^

Purpose

Gets a description of the data to be received for the exchange dialog.

Declared In

ExgMgr.h

Prototype

status_t ExgNotifyPreview (
   ExgPreviewInfoType *infoP
)

Parameters

infoP
An ExgPreviewInfoType structure containing information about the 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

The ExgDoDialog() function calls this function to get a description of the data to show 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.

The preview feature is deprecated and is maintained only for backward compatibility. Applications should no longer implement preview via this mechanism, but should follow the data viewing guidelines described in "Put with View Mode."

This function provides to the exchange dialog the first of the following object descriptions that it finds:

  • 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

See Also

ExgNotifyReceive(), ExgDisconnect()

ExgNotifyReceive Function ^TOP^

Purpose

Delivers an object to the appropriate application using the registry.

Declared In

ExgMgr.h

Prototype

status_t ExgNotifyReceive (
   ExgSocketType *socketP,
   uint16_t 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.

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 email 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 email message data type. This second call sends the object to the application registered to receive the email 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).

See Also

ExgNotifyPreview()

ExgPut Function ^TOP^

Purpose

Initiates the transfer of data to the destination device.

Declared In

ExgMgr.h

Prototype

status_t ExgPut (
   ExgSocketPtr socketP
)

Parameters

socketP
Pointer to the socket structure (see ExgSocketType). Specify a URL in the name field. The structure should also contain a value for the target or type fields.

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 want to call ExgSend() multiple times to send the data in chunks.

The socket's name field must identify by URL the library that performs the transfer. The socket should also specify what data is being sent by providing values for at least one of the target and type fields.

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 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 URL, the Exchange Manager by default uses the IR Library; however, if the localMode flag is set, the Local Exchange Library is used instead.

See Also

ExgDisconnect(), ExgSend(), ExgConnect()

ExgReceive Function ^TOP^

Purpose

Receives data from a remote device.

Declared In

ExgMgr.h

Prototype

uint32_t ExgReceive (
   ExgSocketPtr socketP,
   void *bufP,
   uint32_t bufLen,
   status_t *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.

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.

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

status_t ExgRegisterDatatype (
   uint32_t creatorID,
   uint16_t id,
   const char *dataTypesP,
   const char *descriptionsP,
   uint16_t 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, so they should be user-friendly. Use information that describes the type of information handled, such as pictures, sounds, contact information, etc. Don't use MIME types or file extensions because they are not meaningful to the average user.
flags
Always pass zero for this parameter. (This was formerly used for the exgUnwrap flag, but that is now deprecated.)

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

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.

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

status_t ExgRegisterData (
   uint32_t creatorID,
   uint16_t 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.

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.

ExgRequest Function ^TOP^

Purpose

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

Declared In

ExgMgr.h

Prototype

status_t ExgRequest (
   ExgSocketType *socketP
)

Parameters

socketP
Pointer to the socket structure (see ExgSocketType). Specify a URL in the name field.

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.

See Also

ExgGet(), ExgNotifyReceive()

ExgSend Function ^TOP^

Purpose

Sends data to the destination device.

Declared In

ExgMgr.h

Prototype

uint32_t ExgSend (
   ExgSocketPtr socketP,
   const void *bufP,
   uint32_t bufLen,
   status_t  *err
)

Parameters

socketP
A pointer to the socket structure (see ExgSocketType). A value must be provided for the name field. The structure should also contain values for the target or type 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 either the same number of bytes as specified in bufLen, or 0 if nothing was sent. An error code is returned in the address indicated by err. The error code exgErrUserCancel is returned if the user cancels the operation.

Comments

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

The 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 requested 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.

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

status_t ExgSetDefaultApplication (
   uint32_t creatorID,
   uint16_t 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.

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 it sets the default exchange library that handles URLs with a certain prefix.

We strongly recommend 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);  

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
) (
   const char *nameP,
   uint16_t version,
   DatabaseID dbID,
   void *userDataP
)

Parameters

nameP
A pointer to the name of the identical database.
version
The version 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

status_t (
   *ExgDBReadProcPtr
) (
   void *dataP,
   uint32_t *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:


status_t MyReadDBProc (void *dataP, uint32_t *sizeP,  
  void *userDataP)  
{ 
  status_t 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

status_t (
   *ExgDBWriteProcPtr
) (
   const void *dataP,
   uint32_t *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:


status_t MyWriteDBProc (void *dataP, uint32_t *sizeP,  
  void *userDataP)  
{ 
  status_t err = errNone; 
  //userDataP contains ExgSocketType pointer.  
  *sizeP =  
    ExgSend((ExgSocketType *)userDataP,  
      dataP, *sizeP, &err); 
  return err; 
}