Exchange
The Exchange Manager is a central system broker in charge of the communication between different applications or servers. It facilitates data exchange between requesting services, which manipulate data, and the executing services.
Any application requiring an existing registered service must use the Exchange Manager. Doing so, it benefits automatically from any update to this service (or the application in charge of the service).
Definitions
Service
A service is described by a verb (action) and a subject (e.g. mime type). This pair verb+subject defines a specific service. Parameters can be associated with a service to customize its behavior. For instance, a service could be "store" (the verb) and "vObject" (the subject). Another service could be "display" (the verb) and "jpeg" (the subject).
Application Requesting a Service (Client Application)
An application requesting a service is, for instance,
- a PIM application such as Contacts that wants to "send contact".
- the Smart Text Engine that wants "dial a phone number" when a phone number string is identified in the text or "browse an URL" when an URL is identified in the text
- an application that wants to "take a picture" and get back the image file in JPG format
Applications of this type are referred to as "client applications."
Application Executing a Service (Handler)
An application executing a service is an application that knows how to process the verb (action) on the subject corresponding to the service. For instance:
- an image viewer knows how to display (verb) a JPG file (subject) so it could be the application that takes care of the service where verb is "display" and subject is "jpeg".
- a dialer application knows how to dial a phone number so it can execute the request or service "dial phone number"
This application will be invoked by the Exchange Manager to run the requested service handler. Such an application is referred to as a "handler application."
The Role of the Exchange Manager
The Exchange Manager provides all the mechanisms via a daemon and API to
- register services
- enable an application to ask the Exchange Manager for a given service
- dispatch the service request to the right application in charge of "executing" the request
Note that an application requests a service without knowing which application will process it. The client application only needs to know what action and what type of data and possible parameters the service expects. It is then up to the Exchange Manager to take care of the request. The application that issued the request can also get data back along with the result of its request.
Note also that the term "Exchange" is inherited from the previous OS (Garnet) and may be somewhat confusing. Indeed, in ACCESS Linux Platform this component is extensible to any kind of service (display an image, dial a phone number, etc.) and is not limited to exchanging data (for example, beam over IRDA or send over Bluetooth).
Basic Procedures
Requesting a Service
The application that wants to request a service via the Exchange Manager should do the following:
- Create an exchange request (an
AlpExg2Request) withalp_exg2_request_create(). - Set relevant parameters defining the request: verb and subject. Do this by calling
alp_exg2_request_set_verb()andalp_exg2_request_set_subject(). - Set additional parameters such as localized text that can be displayed (use
alp_exg2_request_set_human_description()), a string as parameter (callalp_exg2_request_string_parameter_set()), etc. The needed parameters and their meanings are defined by each specific service. - Once the request has been completely built with the needed parameters, call
alp_exg2_request_execute_sync()to ask for the service to be performed.
For additional details, see "Requesting a Service". For a complete list of services provided by the various applications, libraries, and other parts of ACCESS Linux Platform, along with their Exchange verb/subject combinations, see Appendix B, "Exchange Verbs."
Providing a Service
An application that provides a service for a given pair verb+subject must declare it to the Exchange Manager with alp_exg2_handler_register_launch(). Once this is done, the Exchange Manager will know that this application is in charge of handling the service defined by this pair verb+subject. The same application can register for many pairs consisting of different verbs and different subjects.
When the Exchange Manager gets a service request, it will "dispatch" it to the relevant handler (the application registered for this service).
A registered service is invoked (launched, relaunched, or called back, depending on whether the service is provided by a running application, an idle application, or a server) by the Exchange Manager when there is a pending request for a verb/subject it has registered. It must then do the following:
- Call
alp_exg2_request_receive_start()to get the request. - Extract all the data from the request via functions such as
alp_exg2_request_get_verb()andalp_exg2_request_string_parameter_get(). - Perform the requested service.
- Call
alp_exg2_request_receive_complete()to signal that processing of the request is complete. The Exchange Manager then returns the resulting request back to the requestor application.
For additional details, see "Providing a Service".
Sending an Object as an Attachment
It is possible to send objects (files) to other devices using various methods, depending on which services are available on the device. Methods can include email attachment, Bluetooth OBEX, and so forth.
The alp_exg2_handler_query_method() function helps to select the right verb in a request when you want to send an object using a specific means (such as Bluetooth OBEX or attachments using various applications as gateways). This function returns the list of all the available methods for a given action class and subject. It is then possible to either build your own menu, or to use alp_exg2_utils_actions_method_select() to display a standard dialog listing these methods.
Once the user has selected a method, you can build a standard request and add the data objects you need to send.
