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

39    Helper API

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

HelperNotifyEnumerateListType Struct ^TOP^

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

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

Action Code

data Type

Description

kHelperNotifyActionCode
Enumerate

HelperNotifyEnumerateListType

Send a list of available services.

kHelperNotifyActionCode
Validate

HelperNotifyValidateType

Validate the input data for the specified service.

kHelperNotifyActionCode
Execute

HelperNotifyExecuteType

Perform the specified service.

Compatibility

Implemented only if 4.0 New Feature Set is present.

HelperNotifyExecuteType Struct ^TOP^

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, if dataP 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 the handled field in the notification data structure should be set to true.

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

Service Class ID

dataP Value

detailsP Value

kHelper
ServiceClassID
VoiceDial

The telephone number to dial

NULL

kHelper
ServiceClassID
EMail

The email address to which the message is to be sent

HelperServiceEMailDetailsType

kHelper
ServiceClassID
SMS

The SMS mailbox number to which the message is to be sent

HelperServiceSMSDetailsType

kHelper
ServiceClassID
Fax

The fax number to which the fax is to be sent

NULL

Compatibility

Implemented only if 4.0 New Feature Set is present.

HelperNotifyValidateType Struct ^TOP^

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

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

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

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

Helper Service Class IDs ^TOP^

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

Constant

Value

Description

kHelperServiceClassIDVoiceDial

'voic'

Dial a phone number for a voice telephone call.

kHelperServiceClassIDEMail

'mail'

Send an email message.

kHelperServiceClassIDSMS

'sms_'

Send an SMS message.

kHelperServiceClassIDFax

'fax_'

Send a fax.

Compatibility

Implemented only if 4.0 New Feature Set is present.