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

9    Helper

Programming Basics

Exploring Palm OS®

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 Structures and Types
Helper Constants
Helper Notifications

The header file Helper.h declares the API that this chapter describes.

For more information on using the Helper API, see the section "Helper Notifications".

Helper Structures and Types ^TOP^

HelperNotifyActionCodeType Typedef ^TOP^

Purpose

Contains an action code that specifies what action the broadcasting application is requesting. See "Action Codes" for the set of defined action codes.

Declared In

Helper.h

Prototype

typedef uint16_t HelperNotifyActionCodeType

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.

Declared In

Helper.h

Prototype

typedef struct HelperNotifyEnumerateListTypeTag {
   struct HelperNotifyEnumerateListTypeTag *nextP;
   Char helperAppName[kHelperAppMaxNameSize];
   Char actionName[kHelperAppMaxActionNameSize];
   uint32_t helperAppID;
   uint32_t serviceClassID;
} HelperNotifyEnumerateListType

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 can be displayed as one of the choices in a pop-up list. The name should not exceed kHelperAppMaxNameSize bytes in length.
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, and should never exceed kHelperAppMaxActionNameSize bytes in length.
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."

Comments

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.

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.

Declared In

Helper.h

Prototype

typedef struct HelperNotifyEventTypeTag {
   uint16_t 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 kHelperNotifyCurrentVersion.
actionCode
The action that the helper application should perform. See "Action Codes."
data
Data specific to the action code. See "Action Codes."

Comments

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.

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.

Declared In

Helper.h

Prototype

typedef struct HelperNotifyExecuteTypeTag {
   uint32_t serviceClassID;
   uint32_t helperAppID;
   Char *dataP;
   Char *displayedName;
   void *detailsP;
   status_t 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 "Helper Service Class IDs." 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 "Helper Service Class IDs." If the service does not require extra information, this field is NULL.
err
An error code that indicates whether the service was performed successfully. If the service was successful, this field contains errNone, and the handled field in the notification data structure should be set to true.

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.

Declared In

Helper.h

Prototype

typedef struct HelperNotifyValidateTypeTag {
   uint32_t serviceClassID;
   uint32_t 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.

Comments

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.

Helper Constants ^TOP^

Action Codes ^TOP^

Purpose

Codes that specify the action that a helper application is expected to take. The code is passed to each helper application registered to receive a sysNotifyHelperEvent notification as part of the HelperNotifyEventType structure that accompanies the notification.

Declared In

Helper.h

Constants

#define kHelperNotifyActionCodeEnumerate ((HelperNotifyActionCodeType)1)
Send a list of available services. The HelperNotifyEventType structure's data field contains a HelperNotifyEnumerateListType structure.
#define kHelperNotifyActionCodeExecute ((HelperNotifyActionCodeType)3)
Perform the specified service. The HelperNotifyEventType structure's data field contains a HelperNotifyExecuteType structure.
#define kHelperNotifyActionCodeValidate ((HelperNotifyActionCodeType)2)
Perform the specified service. The HelperNotifyEventType structure's data field contains a HelperNotifyValidateType structure.

Miscellaneous Helper Constants ^TOP^

Purpose

The Helper.h file also declares these constants.

Declared In

Helper.h

Constants

#define kHelperAppMaxActionNameSize 48
The maximum length, in bytes, of a string containing the name of the service that can be performed, suitable for display in the user interface. This string is passed to broadcasting applications as part of the HelperNotifyEnumerateListType structure.
#define kHelperAppMaxNameSize 72
The maximum length, in bytes, of a string containing the name of the helper application, suitable for display in the user interface. This string is passed to broadcasting applications as part of the HelperNotifyEnumerateListType structure.
#define kHelperNotifyCurrentVersion 1
The version of the HelperNotifyEventType structure.

Helper Notifications ^TOP^

sysNotifyHelperEvent ^TOP^

Purpose

Broadcast by applications to request a service from another application. For example, the Address Book application broadcasts this notification to request that the Dial application dial a phone number.

Declared In

NotifyMgr.h

Prototype

#define sysNotifyHelperEvent 'hlpr'

Parameters

notifyDetailsP points to a HelperNotifyEventType structure.

Comments

For the sysNotifyHelperEvent, the notification client (that is, the application or shared library that registers for the notification) is called a helper. The application that broadcasts this notification specifies one of the action codes listed under "Action Codes." These action codes request all helper applications to enumerate (list the services they perform), validate (ensure that the service will succeed), and execute (perform the action). The helper responds to the notification by returning the required data in the appropriate portion of the notifyDetailsP structure and by setting the handled field to true or false to indicate the success or failure of the action.