This chapter describes the Helper API declared in the header files Helper.h
and HelperServiceClass.h
. The Helper API is used when an application broadcasts a sysNotifyHelperEvent
to all interested parties. The broadcaster of the notification and the notification clients (called helpers) use the Helper APIs to communicate with each other. The chapter discusses the following topics:
For more information on using the Helper API, see the section "Helper Notifications" of the Palm OS Programmer's Companion, vol. I.
Helper Data Structures
HelperNotifyEnumerateListType Struct
Purpose
The HelperNotifyEnumerateListType
provides the broadcaster of the helper notification with information about the services that the helper can provide. This structure is used as the data
field of the HelperNotifyEventType
structure when the action code is kHelperNotifyActionCodeEnumerate
.
Prototype
typedef struct HelperNotifyEnumerateListTypeTag { struct HelperNotifyEnumerateListTypeTag *nextP; Char helperAppName[kHelperAppMaxNameSize]; Char actionName[kHelperAppMaxActionNameSize]; UInt32 helperAppID; UInt32 serviceClassID; } HelperNotifyEnumerateListType;
Note that the helper allocates this structure and then adds it to the linked list of structures pointed to by notifyDetailsP->data.enumerateP
in the SysNotifyParamType
that is sent to the helper. The helper should allocate one structure per supported service.
Even though the helper allocates this structure, the helper is not responsible for freeing the structure. Instead, the application that broadcast the notification must free the structure.
Fields
-
nextP
- A pointer to the next element in the list or
NULL
to signal the end of the list. -
helperAppName
- A null-terminated string containing the name of the helper application, suitable for display in the user interface. If more than one application can perform the same service, this name is displayed as one of the choices in a pop-up list.
-
actionName
- A null-terminated string containing the name of the service that can be performed, suitable for display in the user interface. The action name should be short enough to display on a button.
-
helperAppID
- The helper's creator ID or any other ID that uniquely identifies the helper.
-
serviceClassID
- The ID of the service that the helper performs. See Helper Service Class IDs.
Compatibility
Implemented only if 4.0 New Feature Set is present.
HelperNotifyEventType Struct
Purpose
The HelperNotifyEventType
structure contains all data associated with a helper notification (sysNotifyHelperEvent
). A pointer to this structure is passed as the notifyDetailsP
field in the SysNotifyParamType
for that notification.
Prototype
typedef struct HelperNotifyEventTypeTag { UInt16 version; HelperNotifyActionCodeType actionCode; union { struct HelperNotifyEnumerateListTypeTag *enumerateP; struct HelperNotifyValidateTypeTag *validateP; struct HelperNotifyExecuteTypeTag *executeP; } data; } HelperNotifyEventType;
Fields
-
version
- The version number for this structure. The current version is 1.
-
actionCode
- The action that the helper application should perform. See Table 39.1.
-
data
- Data specific to the action code. See Table 39.1.
The HelperNotifyEventType
structure specifies which action is to be performed and contains data necessary for that action. All actions have some common data. Actions also have data specific to that action. The specific data uses a union that is part of the HelperNotifyEventType
structure.
Table 39.1 Helper action codes
Compatibility
Implemented only if 4.0 New Feature Set is present.
HelperNotifyExecuteType Struct
Purpose
The HelperNotifyExecuteType
structure identifies the service to perform and contains the data necessary to perform that service. This structure is used as the data
field of the HelperNotifyEventType
structure when the action code is kHelperNotifyActionCodeExecute
.
Prototype
typedef struct HelperNotifyExecuteTypeTag { UInt32 serviceClassID; UInt32 helperAppID; Char *dataP; Char *displayedName; void *detailsP; Err err; } HelperNotifyExecuteType;
Fields
-
serviceClassID
- The ID of the service to be performed. See Helper Service Class IDs.
-
helperAppID
- The unique ID of the helper; a value of 0 indicates that any available helper for the specified service class should perform the service.
-
dataP
- A null-terminated string specific to this service, such as a phone number for the dial service or an email address for the email service. See Table 39.2. Multiple fields must be separated by semicolons (;).
-
displayedName
- A null-terminated string containing an optional, human-readable description of the string in
dataP
. For example, ifdataP
contains a phone number, this field might contain the name of the person at that number. -
detailsP
- A pointer to a data structure containing extra information that this service requires. See Table 39.2. If the service does not require extra information, this field is
NULL
. -
err
- An error code that indicates if the service was performed successfully or not. If the service was successful, this field contains
errNone
, and thehandled
field in the notification data structure should be set totrue
.
The following table lists the Palm OS-defined values for the service class ID and for each service, shows what value dataP
contains and what type of structure detailsP
points to.
Table 39.2 HelperNotifyExecuteType values
Compatibility
Implemented only if 4.0 New Feature Set is present.
HelperNotifyValidateType Struct
Purpose
The HelperNotifyValidateType
structure identifies a service that should be validated and the helper that should validate it. This structure is used as the data
field of the HelperNotifyEventType
structure when the action code is kHelperNotifyActionCodeValidate
.
Prototype
typedef struct HelperNotifyValidateTypeTag {
UInt32 serviceClassID;
UInt32 helperAppID; } Helper
NotifyValidateType;
Fields
-
serviceClassID
- The ID of the service to be validated. See Helper Service Class IDs.
-
helperAppID
- The creator ID of the helper application. 0 indicates that any available helper for the specified service should respond. If nonzero, only the helper with the matching creator ID should respond.
The helper returns true
in the handled
field of the SysNotifyParamType
structure to indicate that the service can be performed or false
to indicate that the service cannot be performed.
Compatibility
Implemented only if 4.0 New Feature Set is present.
HelperServiceEMailDetailsType Struct
Purpose
The HelperServiceEMailDetailsType
structure provides additional data for the email service. It is used as the detailsP
field in the HelperNotifyExecuteType
when the service class ID is kHelperServiceClassIDEMail
.
Prototype
typedef struct _HelperServiceEMailDetailsType { UInt16 version; Char *cc; Char *subject; Char *message; } HelperServiceEMailDetailsType;
Fields
-
version
- The version number for this structure. The current version is 1.
-
cc
- A null-terminated string containing an email address that should be sent a carbon copy of the message. Multiple addresses are separated by a semi-colon (;). May be
NULL
if there are no email addresses to carbon copy. -
subject
- A null-terminated string containing the subject line. May be
NULL
. -
message
- Initial message body string or
NULL
.
Compatibility
Implemented only if 4.0 New Feature Set is present.
HelperServiceSMSDetailsType Struct
Purpose
The HelperServiceSMSDetailsType
structure provides the SMS message to be sent. It is used as the detailsP
field in the HelperNotifyExecuteType
when the service class ID is kHelperServiceClassIDSMS
.
Prototype
typedef struct _HelperServiceSMSDetailsType { UInt16 version; Char *message; } HelperServiceSMSDetailsType;
Fields
-
version
- The version number for this structure. The current version is 1.
-
message
- A null-terminated string containing the body of the message to be sent, or
NULL
.
Compatibility
Implemented only if 4.0 New Feature Set is present.
Helper Constants
Helper Service Class IDs
The header file HelperServiceClass.h
defines the constants listed in Table 39.3 as service class IDs. Third party developers may define their own service classes. To do so, you must register a 32-bit identifier with PalmSource, Inc. on this web site:
http://www.palmos.com/dev/creatorid/
Alternatively, you can use a creator ID that you already own.
Table 39.3 Service class ID constants
Compatibility
Implemented only if 4.0 New Feature Set is present.