Helper API
 

 < Home   < Developers   < Development Support   < Documentation

36 Helper API


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

36 Helper API

Helper Data Structures

HelperNotifyEnumerateListType

HelperNotifyEventType

HelperNotifyExecuteType

HelperNotifyValidateType

HelperServiceEMailDetailsType

HelperServiceSMSDetailsType

Helper Constants

Helper Service Class IDs

       

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:

Helper Data Structures

Helper Constants

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

New HelperNotifyEnumerateListType

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.

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.

Field Descriptions

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.

New HelperNotifyEventType

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.

typedef struct HelperNotifyEventTypeTag { 
  UInt16 version; 
  HelperNotifyActionCodeType actionCode; 
  union { 
    struct HelperNotifyEnumerateListTypeTag  
      *enumerateP; 
    struct HelperNotifyValidateTypeTag  
      *validateP; 
    struct HelperNotifyExecuteTypeTag  
      *executeP; 
  } data; 
} HelperNotifyEventType; 

Field Descriptions

version
The version number for this structure. The current version is 1.
actionCode
The action that the helper application should perform. See Table 36.1.
data
Data specific to the action code. See Table 36.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 36.1 Helper action codes 
Action Code
data Type
Description
kHelperNotifyActionCode
Enumerate
Send a list of available services.
kHelperNotifyActionCode
Validate
Validate the input data for the specified service.
kHelperNotifyActionCode
Execute
Perform the specified service.

Compatibility

Implemented only if 4.0 New Feature Set is present.

New HelperNotifyExecuteType

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.

typedef struct HelperNotifyExecuteTypeTag { 
  UInt32  serviceClassID; 
  UInt32 helperAppID; 
  Char *dataP; 
  Char *displayedName; 
  void *detailsP; 
  Err err; 
} HelperNotifyExecuteType; 

Field Descriptions

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 36.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 36.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 36.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
kHelper
ServiceClassID
SMS
The SMS mailbox number to which the message is to be sent
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.

New HelperNotifyValidateType

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.

typedef struct HelperNotifyValidateTypeTag { 
  UInt32 serviceClassID; 
  UInt32 helperAppID; 
} HelperNotifyValidateType; 

Field Descriptions

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.

New HelperServiceEMailDetailsType

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.

typedef struct _HelperServiceEMailDetailsType 
{ 
  UInt16 version; 
  Char *cc; 
  Char *subject; 
  Char *message; 
} HelperServiceEMailDetailsType; 

Field Descriptions

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.

New HelperServiceSMSDetailsType

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.

typedef struct _HelperServiceSMSDetailsType { 
  UInt16 version; 
  Char *message; 
} HelperServiceSMSDetailsType; 

Field Descriptions

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 36.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 Palm, Inc. on this web site:

http://www.palmos.com/dev/tech/palmos/creatorid/

Alternatively, you can use a creator ID that you already own.

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