This chapter describes the Exchange Manager API declared in the header file ExgMgr.h
and the Exchange Local Library API declared in the header file ExgLocalLib.h
. It discusses the following topics:
- Exchange Manager Data Structures
- Exchange Manager Constants
- Exchange Manager Functions
- Application-Defined Functions
For more information on the Exchange Manager, see the chapter "Object Exchange" of Palm OS Programmer's Companion, vol. II, Communications.
Exchange Manager Data Structures
ExgAskResultType Enum
Purpose
The ExgAskResultType
enum defines possible values for the result
field of the sysAppLaunchCmdExgAskUser
launch code parameter block.
Prototype
typedef enum { exgAskDialog, exgAskOk, exgAskCancel } ExgAskResultType;
Constants
-
exgAskDialog
- The Exchange Manager should display a dialog that prompts the user to confirm the receipt of data. See
ExgDoDialog()
. -
exgAskOk
- Accept the data.
-
exgAskCancel
- Reject the data.
ExgGoToType Struct
Purpose
The ExgGoToType
structure defines the goToParams
field of the ExgSocketType
structure. Applications that want to be launched after the data is received place their creator IDs in the goToCreator
field and define the goToParams
field. The values in this structure are copied to the sysAppLaunchCmdGoTo
launch code's parameter block.
Prototype
typedef struct { UInt16 dbCardNo; LocalID dbID; UInt16 recordNum; UInt32 uniqueID; UInt32 matchCustom; } ExgGoToType;
Fields
-
dbCardNo
- The card number of the database that contains the added record.
-
dbID
- The local ID of the database that contains the added record.
-
recordNum
- The index of the record that was added.
-
uniqueID
- The unique ID of the record that was added. This field is not used.
-
matchCustom
- Application-specific information.
ExgLocalSocketInfoType Struct
Purpose
The ExgLocalSocketInfoType
structure identifies information specific to the Local Exchange Library. The socketRef
field of the ExgSocketType
structure is set to this structure when you send and receive data using the Local Exchange Library. The Local Exchange Library creates this structure if it does not already exist. You only need to create it if you want to supply non-default values for the noAsk
or previewInfoP
fields.
Prototype
typedef struct { Boolean freeOnDisconnect; Boolean noAsk; ExgPreviewInfoType *previewInfoP; FileHand tempFileH; Err err; ExgLocalOpType op; } ExgLocalSocketInfoType;
Fields
-
freeOnDisconnect
- Whether the structure is freed when the
ExgDisconnect()
call is made. The default 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. If you want to, for example, create a vCalendar object and send it to the Datebook application in response to a user command, you probably want to 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, used to display a preview of the data. If you wanted to simply use another application to help display data, you would create and initialize this structure. -
tempFileH
- A temporary buffer that the Local Exchange Library uses. Do not set this field directly; the Local Exchange Library should set it.
-
err
- The error code returned from the Local Exchange Library. Do not set this field directly; the Local Exchange Library should set it.
-
op
- The operation in progress. Do not set this field directly. The Local Exchange Library sets this field to one of the following:
ExgPreviewInfoType Struct
Purpose
The ExgPreviewInfoType
structure provides information to the ExgNotifyPreview()
function. The ExgNotifyPreview
function uses this information to have the application display a preview of the data to be received in the exchange dialog.
Prototype
typedef struct { UInt16 version; ExgSocketType *socketP; UInt16 op; Char *string; UInt32 size; RectangleType bounds; UInt16 types; Err error; } ExgPreviewInfoType;
Fields
-
version
- Set this field to 0 to specify version 0 of this structure.
-
socketP
- A pointer to the socket structure (see
ExgSocketType
). ThelibraryRef
field must identify the exchange library from which preview data should be received, and thetarget
,type
, orname
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.
-
string
- A buffer into which the application places the string preview if
exgPreviewLongString
orexgPreviewShortString
is specified. -
size
- The allocated size of the
string
field. -
bounds
- The bounds of the rectangle in which the application draws the graphic if
exgPreviewDraw
is specified. -
types
- Upon return from an
exgPreviewQuery
operation, a bit field identifying the types of previews the application supports. -
error
- The error code returned from the application. If
errNone
, the preview operation was successful.
Applications can define and use their own constants for the preview operation. Operations specific to an application are numbered starting at exgPreviewFirstUser
and should be no greater than exgPreviewLastUser
.
Compatibility
This structure is only defined if 4.0 New Feature Set is present.
ExgSocketType Struct
Purpose
The ExgSocketType
structure defines an Exchange Manager socket, which is passed to most Exchange Manager functions. The ExgSocketPtr
type points to a ExgSocketType
structure.
Prototype
typedef struct ExgSocketType { UInt16 libraryRef; UInt32 socketRef; UInt32 target; UInt32 count; UInt32 length; UInt32 time; UInt32 appData; UInt32 goToCreator; ExgGoToType goToParams; UInt16 localMode:1; UInt16 packetMode:1; UInt16 noGoTo:1; UInt16 noStatus:1; UInt16 preview:1; UInt16 reserved:11; Char *description; Char *type; Char *name; } ExgSocketType;
typedef ExgSocketType *ExgSocketPtr;
Note that when data is received, some of the fields in this structure may not have values. When you are sending data, it is recommended that you provide values for all of these fields, but you should not rely on receiving values for the fields marked optional.
Fields
-
libraryRef
- The exchange library in use. When an application or library receives a socket, this field is already assigned.
- When sending data, applications may identify the exchange library they want to connect with by providing a URL in the
name
field. If so, they should use 0 for thelibraryRef
field. The Exchange Manager then determines which library corresponds to the URL and assigns thelibraryRef
field. See the Comments in theExgPut()
function description for more information. -
socketRef
- The connection identifier. This value is supplied by the exchange library when a connection is established. It contains any necessary library-specific data.
-
target
- The creator ID of the application that should receive the message.
-
count
- The number of objects in this connection, usually 1 (optional).
-
length
- The total byte count for all objects being sent (optional).
-
time
- The last modified time of object (optional).
-
appData
- Application-specific information (optional).
-
goToCreator
- The creator ID of the application to launch using the
sysAppLaunchCmdGoTo
launch code after the item is received 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
- Set to 1 to exchange with local device only. A
localMode
of 1 is equivalent to specifying a URL with theexgLocalPrefix
. Set to 0 to enable an exchange with a remote machine. The default is 0. -
packetMode
- Set to 1 to use connectionless packet mode (Ultra). The default is 0. Ultra mode is not currently supported.
-
noGoTo
- Set to 1 to disable launching the application with
sysAppLaunchCmdGoTo
. The default is 0. -
noStatus
- If
true
, the exchange library should not display a progress dialog. 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. -
reserved
- Reserved system flags.
-
description
- A pointer to the text description of the object (optional).
-
type
- A pointer to the MIME type of the object (optional).
-
name
- The name of the object being sent. This can be a URL whose scheme identifies the exchange library to connect with.
- If the name has a colon, it is treated as a URL.
Compatibility
The noGoTo
and noStatus
flags are only defined if 3.5 New Feature Set is present, and the noStatus
flag has no effect unless 4.0 New Feature Set is present. The preview
flag is only defined if 4.0 New Feature Set is present.
Exchange Manager Constants
Registry ID Constants
The registry ID constants are used in the Exchange Manager registry. Exchange libraries register for the URL prefixes they handle, and applications register for the types of data they receive. The registry ID constants specify which type of data is being registered for.
Register for a creator ID. The |
||
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 |
||
Register for a filename extension. If the |
||
Register for a MIME type. If the |
Compatibility
The exgRegCreatorID
and exgRegSchemeID
constants are only defined if 4.0 New Feature Set is present.
Predefined URL Schemes
The Exchange Manager provides these predefined URL schemes, for which exchange libraries can register.
Compatibility
These constants are only defined if 4.0 New Feature Set is present.
Predefined URL Prefixes
The Exchange Manager provides the following prefixes, which can be used to construct URLs appropriate for the name
field of the ExgSocketType
structure. When sending data, applications provide a URL to identify the exchange library that should transport the data.
Compatibility
These constants are only defined if 4.0 New Feature Set is present.
Exchange Manager Functions
ExgAccept Function
Purpose
Accepts a connection from a remote device.
Declared In
ExgMgr.h
Prototype
Err ExgAccept ( ExgSocketType *socketP )
Parameters
-
→
socketP
- A pointer to the socket structure (see
ExgSocketType
).
Returns
Returns one of the following error codes:
A preview is in progress, and the exchange library identified by |
Other error codes depend on the exchange library.
Displays a fatal error message if socketP
does not have a libraryRef
specified.
Comments
Applications call this function when launched with the sysAppLaunchCmdExgReceiveData
or sysAppLaunchCmdExgPreview
launch code. The launch code contains socketP
in its parameter block. Applications should pass this socket to ExgAccept
to accept the connection, then call ExgReceive()
one or more times to receive the data, and then call ExgDisconnect()
to disconnect.
NOTE: Don't create the socket on the receiving side of an exchange. The socket is passed to you in the command parameter block of the
sysAppLaunchCmdExgReceiveData
or sysAppLaunchCmdExgPreview
launch code.
Compatibility
Implemented only if 3.0 New Feature Set is present. Preview mode is supported only if 4.0 New Feature Set is present.
See Also
ExgConnect()
, ExgPut()
, ExgGet()
ExgConnect Function
Purpose
Establishes a connection with a remote socket.
Declared In
ExgMgr.h
Prototype
Err ExgConnect ( ExgSocketType *socketP )
Parameters
-
→ socketP
- A pointer to the socket structure (see
ExgSocketType
). Specify either a value for thelibraryRef
field or a URL in thename
field.libraryRef
should be 0 if thename
field contains a URL.
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" of Palm OS Programmer's Companion, vol. II, Communications for more information.
Before calling this function, the application must initialize the socketP
parameter. The socket should identify the exchange library to connect with by providing either a library reference number in the libraryRef
field or a URL in the name
field. The default exchange library registered for that type of URL handles the connection.
To provide users with a choice of transport mechanisms, specify a URL that begins with a question mark (?). The Exchange Manager displays a dialog with a list of all exchange libraries that respond to URLs of the specified type. If only one exchange library is registered for this URL scheme, no dialog is displayed.
For example, many applications on Palm OS® 4.0 or higher support a Send command. This command generates a URL with the prefix exgSendPrefix
(see Predefined URL Prefixes). The Exchange Manager displays a dialog containing a list of libraries registered for that URL scheme. The user selects an exchange library, and that library's ExgLibConnect
function is called.
If the library is not specified by either URL or library reference number (in the libraryRef
field), the Exchange Manager by default uses the IR Library; however, if the localMode
flag is set, the Local Exchange Library is used instead.
In addition to specifying the library, you can set the count
field in socketP
before making this call to indicate the number of objects that are going to be sent. Use a count
of 0 if the number of objects isn't known in advance.
If no error is returned from ExgConnect
, applications can follow this call either by sending multiple objects or requesting data from the remote device or both. To send an object, call ExgPut()
at the beginning of each object and call ExgSend()
one or more times per object to send the data. To request data from the remote device, use ExgGet()
(and then use ExgReceive()
to receive the requested data). You can use these calls in combination with each other to support two-way communications. After all of the objects have been sent and received, call ExgDisconnect()
to disconnect.
IMPORTANT: Not all exchange libraries support the sending of multiple objects or using
ExgGet
to request data.
Compatibility
Implemented only if 3.0 New Feature Set is present. ExgConnect
was for system use only until the release of Palm OS 4.0. Multiple object sending and identifying exchange libraries by URL are supported only if 4.0 New Feature Set is present. On earlier releases, this function is an alias for the ExgPut
function.
See Also
ExgPut()
, ExgAccept()
, ExgGet()
ExgControl Function
Purpose
Requests that an exchange library perform an operation.
Declared In
ExgMgr.h
Prototype
Err ExgControl ( ExgSocketType *socketP, UInt16 op, void *valueP, UInt16 *valueLenP )
Parameters
-
→ socketP
- A pointer to the socket structure (see
ExgSocketType
). Specify either a value for thelibraryRef
field or a URL in thename
field.libraryRef
should be 0 if thename
field contains a URL. -
→
op
- A constant identifying the operation that the exchange library should perform. See the Comments section for more information.
-
↔
valueP
- Upon entry, a parameter that the exchange library requires to perform the operation, if any. Most operations do not require an input parameter. Upon return, contains the result of the operation.
-
↔
valueLenP
- The size of the
valueP
buffer. The size is updated upon return to show the actual length of the content returned.
Returns
Returns one of the following error codes:
Other error codes depend on the exchange library.
Comments
The Exchange Manager uses this function to request information from the exchange library. Applications may also call this function.
The Exchange Manager defines and uses a set of operation constants that it might send to any exchange library. These constants begin with the prefix exgLibCtlGet
. The type of the variable pointed to by valueP
depends on the type of operation to be performed. Table 62.1 lists and describes the predefined Exchange Manager operations.
Table 62.1 ExgControl operations for all exchange libraries
An exchange library may also define its own operations. For example, the IR Library supports operations to enable or disable beaming, to set the baud rates, or to use the serial port (see "IR Control Constants"). The SMS Library supports operations that allow you to set the SMS preferences for sending messages or to manipulate multipart messages (see "SMS Control Constants"). Operations specific to an exchange library are numbered starting at exgLibCtlSpecificOp
.
The socketP
passed to this function must identify an exchange library either using the libraryRef
field or using a URL in the name
field. The Comments section in ExgConnect()
describes how an application should identify the exchange library.
Compatibility
Implemented only if 4.0 New Feature Set is present.
ExgDBRead Function
Purpose
Converts a Palm OS database from its internal format and writes it to storage RAM.
Declared In
ExgMgr.h
Prototype
Err ExgDBRead ( ExgDBReadProcPtr readProcP, ExgDBDeleteProcPtr deleteProcP, void *userDataP, LocalID *dbIDP, UInt16 cardNo, Boolean *needResetP, Boolean keepDates )
Parameters
-
→
readProcP
- A pointer to a function that reads in the database and passes it to
ExgDBRead
. 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. -
→
cardNo
- The number of the card on which the database is to be stored.
-
←
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.
Compatibility
Implemented only if 3.0 New Feature Set is present.
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
Err ExgDBWrite ( ExgDBWriteProcPtr writeProcP, void *userDataP, const char *nameP, LocalID dbID, UInt16 cardNo )
Parameters
-
→
writeProcP
- A pointer to a function that writes out the database identified by
dbID
. 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. -
→
cardNo
- The number of the card on which to look for the database identified by
nameP
.
Returns
Returns errNone
if successful; otherwise, returns one of the data manager error codes (dmErr...
) or a callback-specific error code. (If the writeProcP
function returns an error, it is also returned by ExgDBWrite
.)
Comments
This function converts a Palm OS formatted database on the storage heap into a stream of bytes that can be sent over the Internet or over any other transport mechanism. It is not required that you use this function in conjunction with Exchange Manager calls.
The primary use of this function, however, is to write a database that is going to be beamed onto another device. In this case, call ExgDBWrite
after establishing the connection with ExgPut()
. Place the call to ExgSend()
in the write callback function you passed as the writeProcP
parameter. Pass the ExgSocketType
structure returned from ExgSend
in the userDataP
parameter so that you have access to it in the write callback function.
The write callback function performs the actual writing of data. ExgDBWrite
calls the write callback function multiple times. Each time, the sizeP
parameter contains the number of bytes of dataP
that are to be written. If the write callback function didn't handle it all, it's important that it set in sizeP
the number of bytes that it did handle successfully. ExgDBWrite
stops calling the write callback function after 0 is returned in sizeP
.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
ExgDisconnect Function
Purpose
Terminates an Exchange Manager transfer and disconnects.
Declared In
ExgMgr.h
Prototype
Err ExgDisconnect ( ExgSocketType *socketP, Err error )
Parameters
-
→
socketP
- A pointer to the socket structure (see
ExgSocketType
) identifying the connection to terminate. -
→
error
- Any error that occurred. This parameter tells the exchange library why the connection is being broken. Normally the error code from
ExgSend()
orExgReceive()
is passed in here.
Returns
Returns one of the following error codes:
Other error codes depend on the exchange library.
May display a fatal error message if socketP
doesn't contain a libraryRef
value.
Comments
Applications must call this function when finished sending data or receiving data. It terminates the connection made with ExgConnect()
, ExgAccept()
, ExgPut()
, or ExgGet()
.
In the error
parameter, pass any error that occurs during the application loop, including errors returned from other Exchange Manager functions. This ensures that the connection is shut down knowing that it failed rather than succeeded.
It's especially important to check the result code from this function, since this will tell you if the transfer was successful. An errNone
return value means that the item was delivered to the destination successfully. It does not mean that the user on the other end actually kept the data.
ExgDisconnect
is used after sending and receiving. When receiving, the application can insert its creator ID into the goToCreator
field in the socket structure and add other goto information in the goToParams
field. After the application returns from the sysAppLaunchCmdExgReceiveData
launch code, the exchange library may call ExgNotifyGoto()
, which launches the goToCreator
application with the standard launch code sysAppLaunchCmdGoTo
.
IMPORTANT: Placing your creator ID in the
goToCreator
field is no longer a guarantee that you receive this launch code starting in Palm OS 4.0 because Palm OS 4.0 supports the sending of multiple objects at once. Thus, another application might overwrite the goToCreator
field after your application has disconnected, making that application the recipient of the launch code.
Note that some exchange libraries wait to establish a connection until ExgDisconnect
is called. The IR Library, for example, buffers the data that it receives and then waits until ExgDisconnect
to actually send this data unless ExgConnect
is called to establish a multi-object send connection.
Compatibility
Implemented only if 3.0 New Feature Set is present.
Prior to Palm OS release 4.0, the Exchange Manager always launched the goToCreator
application, if one was provided, upon return from this function. If 4.0 New Feature Set is present, the Exchange Manager does not launch the goToCreator
application. Exchange libraries that want the previous behavior must explicitly call ExgNotifyGoto()
.
See Also
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, Err *errP )
Parameters
-
→
socketP
- A pointer to the socket structure (see
ExgSocketType
) identifying the connection. A value must be provided for thelibraryRef
field. - Applications can obtain the socket structure from the
sysAppLaunchCmdExgAskUser
launch code parameter block. -
↔
infoP
- A pointer to an
ExgDialogInfoType
structure (see the Comments section below). -
←
errP
-
errNone
if no error, or the error code if an error occurred. Currently, no errors are returned.
Returns
Returns true
if the user clicks the OK button on the dialog, or false
otherwise.
Comments
This function displays the exchange dialog, which prompts the user to accept or reject incoming data.
By default, the Exchange Manager calls this function if the receiving application doesn't handle the sysAppLaunchCmdExgAskUser
launch code or if it returns exgAskDialog
from the launch code handler. When the Exchange Manager calls ExgDoDialog
, the dialog displays a message similar to "Do you want to accept 'John Doe' into Address Book?" and allows the user to accept or reject the data. If the user clicks OK, the data should be received as an unfiled record.
The Exchange Manager attempts to display a preview of the data in the exchange dialog to provide users with enough information to determine if they want to accept or reject the data. To display the preview data, it calls ExgNotifyPreview()
. Applications wishing to support preview mode should respond to the launch code sysAppLaunchCmdExgPreview
. See the ExgNotifyPreview
function's description for more information.
Applications may also want to allow users to select a category in which to accept the incoming data. To do so, handle sysAppLaunchCmdExgAskUser
to call ExgDoDialog
directly and pass it a pointer to an ExgDialogInfoType
structure. The ExgDialogInfoType
structure is defined as follows:
Prototype
typedef struct { UInt16 version; DmOpenRef db; UInt16 categoryIndex; } ExgDialogInfoType;
Parameters
-
→
version
- Set this field to 0 to specify version 0 of this structure.
-
→
db
- A pointer to an open database that defines the categories the dialog should display.
-
←
categoryIndex
- The index of the category in which the user wants to file the incoming data.
If db
is valid, the function extracts the category information from the specified database and displays it in a pop-up list. Upon return, the categoryIndex
field contains the index of the category the user selected, or dmUnfiledCategory
if the user did not select a category.
If the call to ExgDoDialog
is successful, your application is responsible for retaining the value returned in categoryIndex
and using it to file the incoming data as a record in that category. One way to do this is to store the categoryIndex
in the socket's appData
field (see ExgSocketType
) and then extract it from the socket in your response to the launch code sysAppLaunchCmdExgReceiveData
. For example:
if (cmd == sysAppLaunchCmdExgReceiveData) {
UInt16 category =
(ExgSocketPtr)cmdPBP->appData;
/* other declarations */
/* Receive the data, and create a new record
using the received data. indexNew is the
index of this record. */
if (category !- dmUnfiledCategory
) {
UInt16 attr;
Err err;
err = DmRecordInfo(dbP, indexNew, &attr,
NULL, NULL);
// Set the category to the one the user
// specified, and mark the record dirty.
if ((attr & dmRecAttrCategoryMask) !=
category) {
attr &= ~dmRecAttrCategoryMask;
attr |= category | dmRecAttrDirty;
err = DmSetRecordInfo(dbP, indexNew,
&attr, NULL);
}
}
}
Some of the Palm OS built-in applications (Address Book, Memo, and ToDo) use this method of setting the category on data received through beaming. Refer to the example code for these applications provided in the SDK for a more complete example of how to use ExgDoDialog
.
When you explicitly call ExgDoDialog
, you must set the result
field of the sysAppLaunchCmdExgAskUser
launch code's parameter block to either exgAskOk
(upon success) or exgAskCancel
(upon failure) to prevent the system from displaying the dialog a second time.
Compatibility
Implemented only if 3.5 New Feature Set is present.
Preview mode display in the exchange dialog is implemented only if 4.0 New Feature Set is present.
ExgGet Function
Purpose
Establishes a connection and requests an object from a remote device.
Declared In
ExgMgr.h
Prototype
Err ExgGet ( ExgSocketType *socketP )
Parameters
-
→ socketP
- A pointer to the socket structure (see
ExgSocketType
). Specify either a value for thelibraryRef
field or a URL in thename
field.libraryRef
should be 0 if thename
field contains a URL. Thetarget
,type
, orname
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 device. Not all exchange libraries support this operation; for example, neither the IR Library nor Bluetooth support it.
Before calling this function, the application must initialize the socketP
parameter. The socket should identify the exchange library to connect with by providing either a library reference number in the libraryRef
field or a URL in the name
field. The default exchange library registered for the URL's scheme handles the connection. The socket should also specify what data it is requesting by providing values for at least one of the target
, name
, and type
fields. Specifying the data in the name
field is the most common method.
To provide users with a choice of transport mechanisms, the application can provide a URL that begins with a question mark (?). The Exchange Manager displays a dialog with a list of all exchange libraries that respond to URLs of the specified type. If only one exchange library is registered for this URL scheme, no dialog is displayed.
If the library is not specified by either URL or library reference number, the Exchange Manager by default uses the IR Library; however, if the localMode
flag is set, the Local Exchange Library is used instead.
Applications can use ExgGet
to initiate a send from the Local Exchange Library. For more information, see "Sending and Receiving Locally" of the Palm OS Programmer's Companion, vol. II, Communications.
If no error is returned, applications should follow this call with one or more calls to ExgReceive()
, to receive the data, or ExgDisconnect()
, to disconnect.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
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
Err ExgGetDefaultApplication ( UInt32 *creatorIDP, UInt16 id, const Char *dataTypeP )
Parameters
-
←
creatorIDP
- A pointer to the creator ID of the default application or default exchange library.
-
→
id
- The registry ID constant identifying the type of data in
dataTypeP
. See Registry ID Constants. -
→
dataTypeP
- A pointer to a string that contains the type of data for which to retrieve the default application or library. If
dataTypeP
is a file extension, do not include the period (.). If it is a URL, do not include the colon (:).
Returns
Returns errNone
if a match was found or exgErrNoKnownTarget
if there is no default application or library for this type of data.
Comments
You might use this function to see which application on this device will receive a particular type of data or to see which library on this device handles URLs of a particular scheme.
For example, to find out which application receives TXT files on this device, do the following:
UInt32 creatorID;
Err error;
error = ExgGetDefaultApplication(&creatorID,
exgRegExtensionID, "TXT");
if (!error) {
//creatorID contains default application.
To find out which exchange library handles URLs that use the beam prefix, do the following:
UInt32 creatorID;
Err error;
error = ExgGetDefaultApplication(&creatorID,
exgRegSchemeID, exgBeamScheme);
if (!error) {
//creatorID contains default library.
It's possible to have several applications registered to receive the same type of data, but none of them is the default. When the Exchange Manager receives an object of that type, it selects an application to receive the data, and it selects that same application every time. The selected application effectively becomes the default for the data type even though it is not explicitly set as the default. If this is the case, the ExgGetDefaultApplication
function returns the creator ID of this de-facto default application.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
ExgGetRegisteredApplications()
, ExgGetRegisteredTypes()
, ExgRegisterDatatype()
, ExgSetDefaultApplication()
ExgGetRegisteredApplications Function
Purpose
Retrieves a list of all applications registered to receive data of a specified type.
Declared In
ExgMgr.h
Prototype
Err ExgGetRegisteredApplications ( UInt32 **creatorIDsP, UInt32 *numAppsP, Char **namesP, Char **descriptionsP, UInt16 id, const Char *dataTypeP )
Parameters
-
← creatorIDsP
- An array of the creator IDs of the applications registered to receive objects of this type. Pass
NULL
for this parameter if you only want to know how many applications are registered for this type. -
← numAppsP
- The number of applications registered to receive objects of this type. This is the number of elements in the
creatorIDsP
array, 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. For example, iMessenger uses this function to build a list of mailto handlers so that the user can choose one of them to be the default.
The Exchange Manager itself uses ExgGetRegisteredApplications
to find exchange libraries when it is given a URL that begins with a question mark (?). It displays the returned list to the user in the Send With dialog.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
ExgGetDefaultApplication()
, ExgGetRegisteredTypes()
, ExgRegisterDatatype()
, ExgSetDefaultApplication()
ExgGetRegisteredTypes Function
Purpose
Retrieve a list of all data types for which a registration exists.
Declared In
ExgMgr.h
Prototype
Err ExgGetRegisteredTypes ( Char **dataTypesP, UInt32 *sizeP, UInt16 id )
Parameters
-
←
dataTypesP
- A packed list of strings, suitable for passing to
SysFormPointerArrayToStrings()
, containing a sorted list of data types for which a registration exists. Each string is no more 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.
Compatibility
Implemented only if 4.0 New Feature Set is present.
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
Err ExgGetTargetApplication ( ExgSocketType *socketP, Boolean unwrap, UInt32 *creatorIDP, Char *descriptionP, UInt32 descriptionSize )
Parameters
-
→ socketP
- A pointer to the socket structure (see
ExgSocketType
). The structure should contain values for 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. -
←
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 e-mail message. In this case, the Exchange Manager searches for an application that registered to receive the target, the type, or the file extension of the vStock object with the exgUnwrap
flag set. If an application is found, the vStock object is delivered, and the exchange library should discard the object that contained it (the e-mail message). If there is no application registered to receive the data with the exgUnwrap
flag set, this function returns exgErrNoKnownTarget
. In this case, the exchange library should call ExgNotifyReceive()
again passing the entire e-mail message instead of just the vStock attachment.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
ExgSetDefaultApplication()
, ExgNotifyPreview()
, ExgNotifyReceive()
, ExgRegisterDatatype()
ExgNotifyGoto Function
Purpose
Launches the target application using sysAppLaunchCmdGoTo
.
Declared In
ExgMgr.h
Prototype
Err ExgNotifyGoto ( ExgSocketType *socketP, UInt16 flags )
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
only launches an application if one is specified in the goToCreator
field and the noGoTo
parameter is false
. If a goToCreator
is not specified, it is not considered an error. This gives the application a way to override the default behavior.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
ExgNotifyReceive()
, ExgDisconnect()
ExgNotifyPreview Function
Purpose
Displays a preview in the exchange dialog of the data to be received.
Declared In
ExgMgr.h
Prototype
Err ExgNotifyPreview ( ExgPreviewInfoType *infoP )
Parameters
-
↔
infoP
- An
ExgPreviewInfoType
structure containing information about the preview operation.
Returns
Returns one of the following error codes:
Other error codes depend on the application.
Comments
This function performs the preview operation specified in the op
field of the infoP
parameter. The ExgDoDialog()
function calls this function to show a data preview in the exchange dialog. Exchange libraries might want to call this function in certain circumstances. An application rarely calls this function, but it may do so if it displays its own dialog in response to the launch code sysAppLaunchCmdExgAskUser
.
ExgNotifyPreview
uses ExgGetTargetApplication()
to determine the appropriate target application for this data and then launches that application with the launch code sysAppLaunchCmdExgPreview
, passing infoP
as the parameter block. The application responds to this launch code by accepting the connection, receiving the data from the exchange library, and depending on the operation requested, drawing the data into the infoP->bounds
rectangle or returning it in the infoP->string
field, and then disconnecting. The ExgDoDialog
function uses the returned information to draw the preview portion of the dialog.
If the preview data is a string, the ExgNotifyPreview
provides a series of fallback strings that are used if the exchange library doesn't support preview or the application doesn't respond to the launch code. If the application fails to return a string, this function provides one of the following:
- the data's description from
socketP->description
- the filename in
socketP->name
- the target application's description as stored in the exchange registry
- the MIME type in
socketP->type
- the file extension in
socketP->name
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
ExgNotifyReceive()
, ExgDisconnect()
ExgNotifyReceive Function
Purpose
Delivers an object to the appropriate application using the registry.
Declared In
ExgMgr.h
Prototype
Err ExgNotifyReceive ( ExgSocketType *socketP, UInt16 flags )
Parameters
-
↔ socketP
- A pointer to the socket structure (see
ExgSocketType
). -
→
flags
- A bit field. Pass 0 or a combination of the following constants (OR the constants together to specify more than one):
-
exgUnwrap
- The object being delivered should only be handled by an application that registered to receive it with the
exgUnwrap
flag set. -
exgNoAsk
- Do not ask the user to confirm receipt of data. If this constant is passed, the target application does not receive the
sysAppLaunchCmdExgAskUser
launch code, and the Exchange Manager does not 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 e-mail message with an attached vStock object, the exchange library may call ExgNotifyReceive
with the exgUnwrap
flag set and a socket that describes the vStock data type to see if there is an application that registered to receive it directly. If no application is registered to receive vStock objects with the exgUnwrap
flag set, ExgNotifyReceive
returns exgErrNoKnownTarget
. The exchange library should then call ExgNotifyReceive
again, but this time without the exgUnwrap
flag and with a socket that describes the e-mail message data type. This second call sends the object to the application registered to receive the e-mail message rather than its vStock attachment. That application may extract the vStock attachment from the message and use the Local Exchange Library to send it to an application registered to receive vStock objects normally (without the exgUnwrap
flag).
Compatibility
Implemented only if 3.0 New Feature Set is present. ExgNotifyReceive
was a system use only function until the release of Palm OS 4.0.
If the 4.0 New Feature Set is not present, the flags
parameter is not supported, so libraries cannot suppress the exchange dialog, send objects with attachments, or perform a get operation. These features are all added in the 4.0 New Feature Set. Also, if the 4.0 new feature set is not present, this function performs the equivalent of ExgNotifyGoto()
after the application has returned from receiving data. Exchange libraries wishing to support this functionality should call ExgNotifyGoto
immediately after calling ExgNotifyReceive
.
See Also
ExgPut Function
Purpose
Initiates the transfer of data to the destination device.
Declared In
ExgMgr.h
Prototype
Err ExgPut ( ExgSocketType *socketP )
Parameters
-
→ socketP
- Pointer to the socket structure (see
ExgSocketType
). Specify either a value for thelibraryRef
field or a URL in thename
field.libraryRef
should be 0 if thename
field contains a URL. The structure should also contain a value for thetarget
,type
, orname
field.
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 need to call ExgSend
multiple times to send all the data.
The socket's libraryRef
field or the name
field must identify the library that performs the transfer. The libraryRef
field identifies the exchange library by its library reference number. The name
field identifies the library by URL. The socket should also specify what data is being sent by providing values for at least one of the target
, name
, and type
fields. Use of the name
field is the most common method.
To provide users with a choice of transport mechanisms, the application can provide a URL that begins with a question mark (?). The Exchange Manager displays a dialog with a list of all exchange libraries that respond to URLs of the specified type. If only one exchange library is registered for this URL scheme, no dialog is displayed.
For example, many applications on Palm OS 4.0 or higher support a Send command. This command generates a URL with the prefix exgSendPrefix
(see Predefined URL Prefixes). The Exchange Manager displays a dialog containing a list of libraries registered for that URL scheme. The user selects an exchange library, and that library's ExgLibSend
function is called.
If the library is not specified by either URL or library reference number, the Exchange Manager by default uses the IR Library; however, if the localMode
flag is set, the Local Exchange Library is used instead.
Compatibility
Implemented only if 3.0 New Feature Set is present.
Support for identifying exchange libraries by URL is implemented only if 4.0 New Feature Set is present.
See Also
ExgDisconnect()
, ExgSend()
, ExgConnect()
ExgReceive Function
Purpose
Receives data from a remote device.
Declared In
ExgMgr.h
Prototype
UInt32 ExgReceive ( ExgSocketType *socketP, void *bufP, UInt32 bufLen, Err *err )
Parameters
-
→
socketP
- A pointer to the socket structure (see
ExgSocketType
). -
←
bufP
- A pointer to the buffer in which to receive the data.
-
→
bufLen
- The number of bytes to receive.
-
←
err
- A pointer to an error code result.
Returns
Returns the number of bytes actually received. A zero result indicates the end of the transmission.
An error code is returned in the address indicated by err
. The error code exgErrUserCancel
is returned if the user cancels the operation. The error code exgErrNotSupported
is returned if the application calls this function during a preview and the exchange library does not have any more data available or does not support preview.
May display a fatal error message if the library reference number is not provided in socketP
.
Comments
Applications call this function in the following circumstances:
- 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.
Compatibility
Implemented only if 3.0 New Feature Set is present. Preview mode and ExgGet()
are only supported if 4.0 New Feature Set is present.
See Also
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
Err ExgRegisterDatatype ( UInt32 creatorID, UInt16 id, const Char *dataTypesP, const Char *descriptionsP, UInt16 flags )
Parameters
-
→
creatorID
- The creator ID of the registering application or exchange library.
-
→
id
- A registry ID constant identifying the type of the items being registered. See Registry ID Constants.
-
→
dataTypesP
- Pointer to a tab-delimited, null-terminated string listing the items to register. (Use
"\t"
for the tab character.) To unregister, pass 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.
-
→
flags
- A bit field specifying registration options. Currently, only one bit is used: the unwrap bit. Pass the
exgUnwrap
constant to specify that the application is registering to receive objects of this type directly if the object is sent as part of another object. For example, if a vStock object is sent as an attachment to an email message, the Exchange Manager should send the vStock object to this application directly rather than sending the message to the email application.
Returns
Returns errNone
if successful, exgMemError
if there is not enough memory to save the registration info, or one of the data manager error codes (dmErr
...).
Comments
Both applications and exchange libraries use this function to register with the Exchange Manager to receive certain types of data.
Applications must register with the Exchange Manager to receive data objects that do not specifically target that application using the creator ID in the target
field.
Exchange libraries register to receive data with certain URL schemes. If an exchange library is not registered to receive URLs, it only handles the receipt and sending of data if its library reference number is explicitly specified in the ExgSocketType
structure. Otherwise, the IR Library handles all incoming data for which a library could not be found.
Both applications and libraries should register to receive data as soon as possible after they are installed and as soon as possible after a hard reset. For example, applications can call ExgRegisterDatatype
in response to the sysAppLaunchCmdSyncNotify
launch code, which they receive immediately after install. Exchange libraries implemented as applications can also use this strategy. Exchange libraries implemented as shared libraries should call ExgRegisterDatatype
in their startup functions.
Make only one call to ExgRegisterDatatype
per registry type. If you want to register to receive multiple items, use a tab character (\t
) to separate the items. If you were to, for example, make one call to register for the DOC file extension and one call to register for the TXT extension, the second call overwrites the first. However, if you want to register with the exgUnwrap
flag set, make one call without the exgUnwrap
flag and one call with the exgUnwrap
flag set. The application registered with the exgUnwrap
flag set is stored in a different part of the registry.
Specify exgRegExtensionID
to register to receive data that has a filename with a particular extension. For example, if your application wants to receive files with a TXT extension, it could register like this:
ExgRegisterDatatype(myCreator,
exgRegExtensionID, "TXT", NULL, 0);
If the application wants to receive files with a TXT extension or with a DOC extension, it could register like this:
ExgRegisterDatatype(myCreator,
exgRegExtensionID, "TXT\tDOC", NULL, 0);
Specify exgRegTypeID
to register to receive data with a specific MIME type. For example, if your application wants to receive "setext" text files, it could register like this:
ExgRegisterDatatype(myCreator, exgRegTypeID,
"text/x-setext", NULL, 0);
Specify exgRegCreatorID
to register to receive data targeted for a particular creator ID. For example, if your application wants to handle all data intended for the ToDo application, it could register like this:
Char toDoCreatorStr[5];
MemMove(toDoCreatorStr, sysFileCToDo, 4);
toDoCreatorStr[4] = chrNull;ExgRegisterDatatype(myCreator, exgRegCreatorID,
toDoCreatorStr, NULL, 0);
NOTE: To override one application's receipt of data, you need to also set your application as the default for this creator ID. See
ExgSetDefaultApplication()
.
Most exchange libraries will want to register for a unique URL scheme that identifies only that library, plus they should register for a more general scheme, such as the send scheme (exgSendScheme
), which causes the library to be listed in the Send With dialog when the user performs the Send command. The registry ID constant for URL prefixes is exgRegSchemeID
.
ExgRegisterDatatype(myLibCreator,
exgRegSchemeID, myScheme "\t" exgSendScheme,
NULL, 0);
Registrations are active until a hard reset or until the application or library is removed. The registration information is preserved across a soft reset. When an application is removed, its registry information is also automatically removed from the registry, so there is not normally a need to unregister. If you want to unregister, you can call ExgRegisterDatatype
with a NULL
value for the dataTypesP
parameter.
Multiple applications can be registered to receive the same type of data. If this is the case, the application that is registered as the default (using ExgSetDefaultApplication()
) is the one that receives the data unless the exchange socket explicitly specifies another application should receive it. If there is no default specified, the Exchange Manager determines a default.
Multiple libraries may also be registered to receive the same type of URL. In this case, if the URL begins with a question mark (?), the Exchange Manager displays a dialog so that the user can select which exchange library to use. If the URL does not begin with a question mark, the exchange library registered as the default is used. If there is no default specified, the Exchange Manager determines a default.
Compatibility
Implemented only if 4.0 New Feature Set is present. ExgRegisterDatatype
replaces the ExgRegisterData()
function.
See Also
ExgRegisterData()
, ExgGetTargetApplication()
, ExgPut()
, ExgGetDefaultApplication()
, ExgGetRegisteredApplications()
, ExgGetRegisteredTypes()
ExgRegisterData Function
Purpose
Registers an application to receive a specific type of data. This function is deprecated and replaced with ExgRegisterDatatype()
.
Declared In
ExgMgr.h
Prototype
Err ExgRegisterData ( UInt32 creatorID, UInt16 id, const Char *dataTypesP )
Parameters
-
→
creatorID
- Creator ID of the registering application.
-
→
id
- Registry ID identifying the type of the items being registered. Specify
exgRegExtensionID
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.
Compatibility
This function corresponds to the Palm OS 3.5 version of ExgRegisterDatatype()
. It is implemented only if 3.0 New Feature Set is present.
ExgRequest Function
Purpose
Requests some data from an exchange library or an application using a URL.
Declared In
ExgMgr.h
Prototype
Err ExgRequest ( ExgSocketType *socketP )
Parameters
-
→ socketP
- Pointer to the socket structure (see
ExgSocketType
). Specify a URL in thename
field and alibraryRef
of 0.
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.
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
ExgSend Function
Purpose
Sends data to the destination device.
Declared In
ExgMgr.h
Prototype
UInt32 ExgSend ( ExgSocketType *socketP, const void *bufP, UInt32 bufLen, Err *err )
Parameters
-
→
socketP
- A pointer to the socket structure (see
ExgSocketType
). A value must be provided for thelibraryRef
field. The structure should also contain values for thetarget
,type
, orname
fields. -
→
bufP
- A pointer to the data to send.
-
→
bufLen
- The number of bytes to send.
-
←
err
- A pointer to an error code result.
Returns
Returns the number of bytes actually sent, normally the same number as specified in bufLen
. An error code is returned in the address indicated by err
. The error code exgErrUserCancel
is returned if the user cancels the operation.
May display a fatal error message if the socketP
parameter does not contain a value for the libraryRef
field.
Comments
Call this function one or more times to send all the data, following a successful call to ExgPut()
. After sending the data, call ExgDisconnect()
to terminate the connection.
The exchange library may break large amounts of data into multiple packets or assemble small send commands together into larger packets, but the application will not be aware of these transport level details.
This function blocks the application until all the data is sent. However, the exchange library may provide its own user interface that is updated as necessary and allows the user to cancel the operation in progress.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
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
Err ExgSetDefaultApplication ( UInt32 creatorID, UInt16 id, const Char *dataTypeP )
Parameters
-
→
creatorID
- The creator ID of the application or library that should become the default for this type of data.
-
→
id
- A registry ID constant identifying the type of data in
dataTypeP
. See Registry ID Constants. -
→
dataTypesP
- A pointer to a null-terminated string containing the desired type of data.
NOTE: If specifying a file extension, do not include the period (.) that precedes the extension. If specifying a URL prefix, do not include the colon (:) at the end of the prefix.
Returns
Returns errNone
upon success or exgErrNoKnownTarget
if the specified application is not registered to receive the specified data type.
Comments
This function sets the default application that receives data of a certain type when no target is specified and the default exchange library that handles URLs with a certain prefix if no library reference number is specified.
Palm™ strongly recommends that applications allow the user to determine which application should become the default recipient for a data type. To do so, an application can use ExgGetRegisteredApplications()
to get the list of applications registered for the same type of data as it is, and then display a dialog listing those applications and allow the user to select it. Then it should call ExgSetDefaultApplication
with the user-specified default.
If you call ExgSetDefaultApplication
with an application or library that is already the default, this function has no effect.
An application can become the default for its own creator ID even if it has not specifically registered to receive its own creator ID. That is, suppose several applications are registered to receive objects targeted for the ToDo application's creator ID. The ToDo application itself is not registered for its own creator ID, as it is not necessary to do so. However, an application can use code like the following to set the ToDo application as the default for its own creator ID.
Char toDoCreatorStr[5];
MemMove(toDoCreatorStr, sysFileCToDo, 4);
toDoCreatorStr[4] = chrNull; ExgSetDefaultApplication(sysFileCToDo, exgRegCreatorID,toDoCreatorStr
);
Compatibility
Implemented only if 4.0 New Feature Set is present.
See Also
ExgGetDefaultApplication()
, ExgRegisterDatatype()
Application-Defined Functions
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 version, UInt16 cardNo, LocalID dbID, void *userDataP )
Parameters
-
→
nameP
- A pointer to the name of the identical database.
-
→
version
- The version of the identical database.
-
→
cardNo
- The card number of the identical database.
-
→
dbID
- The database ID of the identical database.
-
→
userDataP
- The
userDataP
parameter you passed 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
Err ( *ExgDBReadProcPtr ) ( void *dataP, UInt32 *sizeP, void *userDataP )
Parameters
-
←
dataP
- A pointer to a buffer where this function should place the database data. This buffer is allocated in the dynamic heap by
ExgDBRead
; you don't need to 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:
Err MyReadDBProc (void *dataP, UInt32 *sizeP, void *userDataP) { Err err = errNone; //userDataP contains ExgSocketType pointer. *sizeP = ExgReceive((ExgSocketType *)userDataP, dataP, *sizeP, &err); return err; }
ExgDBWriteProcPtr Function
Purpose
Declared In
ExgMgr.h
Prototype
Err ( *ExgDBWriteProcPtr ) ( const void *dataP, UInt32 *sizeP, void *userDataP )
Parameters
-
→
dataP
- A pointer to a buffer containing the database data, placed there by
ExgDBWrite()
. -
↔
sizeP
- The number of bytes placed in
dataP
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:
Err MyWriteDBProc (void *dataP, UInt32 *sizeP, void *userDataP) { Err err = errNone; //userDataP contains ExgSocketType pointer. *sizeP = ExgSend((ExgSocketType *)userDataP, dataP, *sizeP, &err); return err; }