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
HelperNotifyActionCodeType Typedef
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
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
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
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, 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 "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 thehandled
field in the notification data structure should be set totrue
.
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
.
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
Action Codes
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'sdata
field contains aHelperNotifyEnumerateListType
structure. -
#define kHelperNotifyActionCodeExecute ((HelperNotifyActionCodeType)3)
- Perform the specified service. The
HelperNotifyEventType
structure'sdata
field contains aHelperNotifyExecuteType
structure. -
#define kHelperNotifyActionCodeValidate ((HelperNotifyActionCodeType)2)
- Perform the specified service. The
HelperNotifyEventType
structure'sdata
field contains aHelperNotifyValidateType
structure.
Miscellaneous Helper Constants
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
sysNotifyHelperEvent
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
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.