< 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 | 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. ## 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 | 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. ## 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. |