Applications that provide a service (handlers) must register with the Exchange Manager to specify which services they can perform. Applications that require services (clients) send requests to the Exchange Manager to find a handler for that service. This chapter describes how applications register their services with the Exchange Manager, and how client applications can request those services.
Registering Application Services with the Exchange Manager
As described in Chapter 1, "Introduction," verbs take the form "action class/method", where the action class is the name of the action (e.g., "Send") and the method is how the handler will perform the action (e.g.,"using Bluetooth"). The resulting verb will look something like: "Send/UsingBluetooth".
Determining Which Verbs to Register
While the Exchange Manager defines a number of action classes, none of these classes presupposes any method. Therefore, to determine which verb your application should register with the Exchange Manager, you need only choose an action class and append the method you define.
For example, to register a camera application that can handle a photo and return its data as image/jpeg, you would choose the action class "Get" (get the photo) and append a method such as, "UsingCamera" (using the Camera application). The resulting verb is Get/UsingCamera. Whenever a client application needs to "get" a photo, the Camera application is presented as a possible method for obtaining that photo.
Note that your handler may be required to use a defined verb in some cases. For instance, if your handler is registering to send data from any source (Bluetooth, as an email attachment, etc.) to a recipient application, it must use "Send/ToStorage", your handler must actually use the defined verb.
Registering Data Types: Receiving Data
To specify what data types your application is able to receive, you can register a the full type, a super type, or a wildcard data type:
- "full type" indicates that your application can handle a specific type of data, such as
image/jpeg - "super type" indicates that your application can handle all data of a particular super type, such as
image/* - "wildcard" (*) indicates that your application can receive data of any type
For example, if the Exchange Manager receives a request to open data of type image/jpeg, it will first search for applications that have registered to handle the full type, image/jpeg. If no handlers are found, the Exchange Manager will then search for the super type, image/*. If no handlers are found, the Exchange Manager will search for the wildcard (*) type, and then dispatch the request to the appropriate handler.
NOTE: Even when you register using a wildcard, your application/handler will be invoked with the data type that was specified by the requester. Wildcard registration simply informs the Exchange Manager that your application supports all data types or subtypes.
Registering Data Types: Returning Data
If your application returns data (usually in response to a "Get" request), the data type you registered will represent the abstract object that is returned. The returned data type is found with each object.
Sending Data
You can attach data objects to a request. Each data object is fully qualified by a name, a size, and a type. As a handler, you can access the data objects by file, file descriptor, or memory pointer. The Exchange Manager takes care of any access rights by ensuring that the handler can read the data. In addition, the Exchange Manager will "hide" the original data source so that the handler can only read the data; it does not know where the data comes from.
Data transfer between the requester and the handler is optimized as much as possible. Usually, the handler streams data directly from the original data source; there is no data copy required.
Sending Requests for Service to the Exchange Manager
When a client application requires a service provided by another application (or handler), it sends a request to the Exchange Manager, which locates the appropriate application(s) to handle that request. This section describes how client applications send requests to the Exchange Manager.
Determining Which Verb to Invoke
When an application requests a service from the Exchange Manager, it can query for available verbs in two ways:
- Inform the Exchange Manager of the type of data involved in the request, such as
image/jpeg. In this case, the application does not specify an action class; it simply asks which applications can handleimage/jpegrequests. The Exchange Manager returns a list of all verbs that can handle this subject. - Inform the Exchange Manager of a specifically requested action, such as "Send," and of the type of data to be sent, such as
image/jpeg. In this case, the Exchange Manager returns a list filtered by the "Send" action class, of all verbs that can handle this subject.
Additionally, client applications can specify a bundle name whose handlers will be excluded from the returned list of available verbs. This automatically excludes verbs that are not appropriate in the current context.
For example, in the Contacts application, when a user selects the Send menu option, Contacts queries the Exchange Manager for a handler that can send Contacts data (e.g., text/x-vcard). However, one of the registered verbs is actually implemented by the Contacts application itself (e.g., "Send/SaveToContacts"). As a result, "Send/SaveToContacts" is returned as an available verb, even though that verb is not appropriate in this context. To avoid such a result, Contacts can query the Exchange Manager to exclude verbs that are registered by itself.
NOTE: This section applies to dynamically created requests. For more specific requests, if you know the desired verb, you can create the request directly as described in the doxygen-generated ACCESS Linux Platform API reference material installed with the SDK.
Creating a Request
In order to invoke a service in the system, first create a request. At least a verb and a subject must be specified before you can execute the request. Once the execution results are received, the request must be deleted.
- Create a request:
alp_exg2_request_create (
AlpExg2Request *oRequest, const char *iVerb, const char *iSubject) - Set the subject:
alp_exg2_request_set_subject (
AlpExg2Request iRequest, const char *iSubject) - Set the verb:
alp_exg2_request_set_verb (
AlpExg2Request iRequest, const char *iVerb) - Delete a request:
Receiving Data
Just as you can send data objects as described in "Sending Data," your application can receive data objects. Receiving data objects is a two-step process:
- Get the object information:
alp_exg2_request_object_rcv_info()This function returns the object name (not a file name; do not confuse an object and a container), the object size, the object data type, and an optional description. The returned information can be used to ask the user for confirmation, depending on the service the handler provides.
- Get the object data.
Note that if your application expects more than one object, you can call alp_exg2_request_object_rcv_count() to discover how many objects are contained in the request. If the final number of objects is not known, and the function returns 0xffffffff, you should call alp_exg2_request_object_rcv_info() with an incremental index until the function returns ALP_EXG2_NOMOREOBJECTS_ERR.
