This chapter describes the Exchange Manager API declared in the header file ExgMgr.h
and the Exchange Local Library API declared in the header file ExgLocalLib.h
. It discusses the following topics:
- Exchange Manager Data Structures
- Exchange Manager Constants
- Exchange Manager Launch Codes
- Exchange Manager Functions
- Application-Defined Functions
For more information on the Exchange Manager, see Chapter 4, "Object Exchange."
Exchange Manager Data Structures
ExgAskParamType Struct
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
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
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
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 istrue
. In general, code that allocates a structure should be responsible for freeing that structure. Therefore, if you have allocatedExgLocalSocketInfoType
, you should set this field tofalse
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 setnoAsk
totrue
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:
ExgPreviewInfoType Struct
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
). Thename
field must identify the exchange library from which data should be received, and thetarget
ortype
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, theerror
field containsexgErrNotSupported
. -
exgPreviewShortString
- The preview is a short string.
-
padding2
- Padding; not used.
-
string
- A buffer into which the application places the string preview if
exgPreviewLongString
orexgPreviewShortString
is specified inop
. -
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 inop
. -
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
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 thelibraryRef
field. -
socketRefSize
- Size of the data block referenced by
socketRef
, ifsocketRef
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 ifnoGoTo
is 0. The value is assigned by the application that receives the object. See the Comments section inExgDisconnect()
for more information. -
goToParams
- If
goToCreator
is specified, then this field contains data that is copied into the launch code's parameter block. SeeExgGoToType
. -
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. Iffalse
, the library can display a progress dialog. The default isfalse
. - 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. TheExgNotifyPreview()
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
ExgAskResultType Enum
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
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 theExgSocketType
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 thename
field of theExgSocketType
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 theExgSocketType
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 theExgSocketType
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 theExgSocketType
contains the creator ID of the application that should directly receive the data instead of an email application. (This is used instead of theexgUnwrap
flag and must not be used with it.) -
#define exgRegDirectExtensionID 0xffed
- Register for a filename extension for direct delivery. If the
name
field of theExgSocketType
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 theexgUnwrap
flag and must not be used with it.) -
#define exgRegDirectTypeID 0xffee
- Register for a MIME type for direct delivery. If the
type
field of theExgSocketType
contains a value, the application registered to receive that MIME type handles the message instead of an email application. (This is used instead of theexgUnwrap
flag and must not be used with it.) -
#define exgRegViewCreatorID 0xff8b
- Register for a creator ID for view mode. The
target
field of theExgSocketType
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 theExgSocketType
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 theExgSocketType
contains a value, the application registered to receive that MIME type can be used to view the data.
Predefined URL Schemes
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
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 theexgBeamScheme
. -
#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
sysAppLaunchCmdExgAskUser
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 toexgAskCancel
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
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
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
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
ExgAccept Function
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:
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
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 thename
field and 0 for thelibraryRef
field.
Returns
Returns one of the following error codes:
The library doesn't support the operation specified in |
|
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
Purpose
Requests that an exchange library perform an operation.
Declared In
ExgMgr.h
Prototype
status_t ExgControl ( ExgSocketType *socketP
, uint16_top
, void *valueP
, uint16_t *valueLenP
)
Parameters
-
→ socketP
- A pointer to the socket structure (see
ExgSocketType
). Specify a URL in thename
field and 0 for thelibraryRef
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:
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
Returns |
||
String buffer of size |
Returns the name of the exchange library as it should appear in the Send dialog. All exchange libraries must respond to this operation. |
|
|
Returns the URL that addresses the remote device from which you receive data. You can get the URL after calling |
|
Returns the version of the exchange library API that this library implements. The constant |
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
Purpose
Converts a Palm OS database from its internal format and writes it to storage RAM.
Declared In
ExgMgr.h
Prototype
status_t ExgDBRead ( ExgDBReadProcPtrreadProcP
, ExgDBDeleteProcPtrdeleteProcP
, void *userDataP
, DatabaseID *dbIDP
, Boolean *needResetP
, BooleankeepDates
)
Parameters
-
→
readProcP
- A pointer to a function that reads in the database and passes it to
ExgDBRead()
. SeeExgDBReadProcPtr()
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
ordeleteProcP
functions. Often, this parameter is used to pass theExgSocketType
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
byExgDBRead()
if thedmHdrAttrResetAfterInstall
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. Specifyfalse
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 Function
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 ( ExgDBWriteProcPtrwriteProcP
, void *userDataP
, const char *nameP
, DatabaseIDdbID
)
Parameters
-
→
writeProcP
- A pointer to a function that writes out the database identified by
dbID
. SeeExgDBWriteProcPtr()
for details. -
→
userDataP
- A pointer to any data you want to pass to the
writeProcP
function. Often, this parameter is used to pass theExgSocketType
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 towriteProcP
. -
→
dbID
- The ID of the database that you want
ExgDBWrite()
to pass towriteProcP
. If you don't supply an ID, thennameP
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
ExgDisconnect Function
Purpose
Terminates an Exchange Manager transfer and disconnects.
Declared In
ExgMgr.h
Prototype
status_t ExgDisconnect ( ExgSocketPtrsocketP
, status_terror
)
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()
orExgReceive()
is passed in here.
Returns
Returns one of the following error codes:
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
ExgDoDialog Function
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
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 thename
field and 0 for thelibraryRef
field. Thetarget
ortype
fields should identify the data being requested.
Returns
Returns one of the following error codes:
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
ExgGetDefaultApplication Function
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_tid
, 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
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_tid
, 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, thenamesP
array, and thedescriptionsP
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 thanexgMaxTitleLen
characters. PassNULL
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 thanexgMaxDescriptionLength
characters. PassNULL
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 thanexgMaxTypeLength
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
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_tid
)
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 thanexgMaxTypeLength
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
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
, Booleanunwrap
, uint32_t *creatorIDP
, char *descriptionP
, uint32_tdescriptionSize
)
Parameters
-
→ socketP
- A pointer to the socket structure (see
ExgSocketType
). The structure should contain values for thetarget
,type
, orname
fields. -
→
unwrap
- If
true
, only an application that registered to receive the data type with theexgUnwrap
flag set should be the target application. Iffalse
, the target application should be an application that registered with theexgUnwrap
flag clear. Note that usage of theexgUnwrap
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:
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 thetarget
, 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
Purpose
Launches the target application using sysAppLaunchCmdGoTo
.
Declared In
ExgMgr.h
Prototype
status_t ExgNotifyGoto ( ExgSocketType *socketP
, uint16_tflags
)
Parameters
-
→
socketP
- A socket identifying the object to deliver (see
ExgSocketType
). ThegoToCreator
field contains the application to be launched, and thegoToParams
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:
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
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:
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
Purpose
Delivers an object to the appropriate application using the registry.
Declared In
ExgMgr.h
Prototype
status_t ExgNotifyReceive ( ExgSocketType *socketP
, uint16_tflags
)
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 callExgDoDialog()
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:
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:
- It sends the application the
sysAppLaunchCmdExgAskUser
launch code. - If the application returns
exgAskDialog
or does not respond to the launch code, it callsExgDoDialog()
, which sends the application thesysAppLaunchCmdExgPreview
launch code to have the application receive preview data for the dialog. - 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
ExgPut Function
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 thename
field. The structure should also contain a value for thetarget
ortype
fields.
Returns
Returns one of the following error codes:
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
Purpose
Receives data from a remote device.
Declared In
ExgMgr.h
Prototype
uint32_t ExgReceive ( ExgSocketPtrsocketP
, void *bufP
, uint32_tbufLen
, 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:
- In response to the
sysAppLaunchCmdExgReceiveData
launch code, following a successful call toExgAccept()
. - In response to the
sysAppLaunchCmdExgPreview
launch code, following a successful call toExgAccept()
. - To receive requested data following a successful call to
ExgGet()
.
After receiving the data, applications call ExgDisconnect()
to terminate the connection.
This function blocks the application until the end of the transmission or until the requested number of bytes has been received. However, exchange libraries can provide their own user interface that is shown during this call, is updated as necessary, and allows the user to cancel the operation in progress.
See Also
ExgRegisterDatatype Function
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_tcreatorID
, uint16_tid
, const char *dataTypesP
, const char *descriptionsP
, uint16_tflags
)
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 aNULL
value. Each item in the string must be no more thanexgMaxTypeLength
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 thanexgMaxDescriptionLength
. PassNULL
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
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_tcreatorID
, uint16_tid
, const char *dataTypesP
)
Parameters
-
→
creatorID
- Creator ID of the registering application.
-
→
id
- Registry ID identifying the type of the items being registered. Specify
exgRegExtensionID
orexgRegTypeID
. -
→
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
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 thename
field.
Returns
Returns one of the following error codes:
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
ExgSend Function
Purpose
Sends data to the destination device.
Declared In
ExgMgr.h
Prototype
uint32_t ExgSend ( ExgSocketPtrsocketP
, const void *bufP
, uint32_tbufLen
, status_t *err
)
Parameters
-
→
socketP
- A pointer to the socket structure (see
ExgSocketType
). A value must be provided for thename
field. The structure should also contain values for thetarget
ortype
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
ExgSetDefaultApplication Function
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_tcreatorID
, uint16_tid
, 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
ExgDBDeleteProcPtr Function
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_tversion
, DatabaseIDdbID
, 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 toExgDBRead()
. If used, this parameter contains any application-specific data you find necessary. If theExgDBReadProcPtr()
function is implemented using Exchange Manager calls, this often contains theExgSocketType
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
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 useDmWrite()
when filling it. -
↔
sizeP
- The size of
dataP
. This value is set byExgDBRead()
to the number of bytes it expects to receive indataP
. You must set this value to the number of bytes you return indataP
(if it's not the same). -
→
userDataP
- The
userDataP
parameter you passed toExgDBRead()
. Pass theExgSocketType
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
Purpose
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
byExgDBWrite()
. If you were unable to write out or send all of the data in this chunk, on exit, setsizeP
to the number of bytes you did write. -
→
userDataP
- The
userDataP
parameter you passed toExgDBWrite()
. You can use it for application-specific data. Pass theExgSocketType
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; }