Documentation »  ACCESS Linux Platform Native Development »  Exchange Manager »  Exchange Manager Handlers

The following sections list all available exchange handlers in the platform, by action class, along with the expected parameters and a description of the provided services.

Send ^TOP^

The Send action class (ALP_EXG2_SEND_ACTIONCLASS) is used to send data to a device or application as a data object. For example, you can send data to a database for storage, send data over a Bluetooth connection, or send data as an attachment to an email or SMS message.

Send with Bluetooth ^TOP^

ALP_EXG2_SEND_USINGBLUETOOTH_VERB 
ALP_EXG2_SEND_ACTIONCLASS"/bluetooth" 

Use this verb to send data objects, such as images, sound, or video, using Bluetooth OBEX. When objects are sent, the name and mimetype are embedded within each object that is added to the request. This service is implemented by an invisible application (com.access.exchange.obexsendapp), and registers for all subjects.

By default, this service automatically displays a Bluetooth Discovery dialog to acquire the address of the destination device. However, you can add a string parameter whose value is the destination address to use, in the form xx:xx:xx:xx:xx:xx:

ALP_EXG2_SEND_USINGBLUETOOTH_SPARAM_ADDR "btobexdestaddr" 

If the address is valid, the device does not attempt to discover nearby Bluetooth devices, and connection to the specified address is immediately established.

Send with Email Application ^TOP^

#define ALP_EXG2_SEND_AS_EMAIL_ATTACHMENT_VERB 
ALP_EXG2_SEND_ACTIONCLASS"/asEmailAttach" 

Use this verb to send any type of file to another device, including images, sound, or video, as an email attachment via a pre-configured email account. When objects are sent, the name and mimetype are embedded within each object that is added to the request.

An optional string parameter representing a text/rfc2368 address can be included in the request:

#define ALP_EXG2_EMAIL_MAILTO_PARAM "mailto_url" 

If the parameter exists, the handler parses a mailto: URL from this parameter. The handler then uses the URL to populate the destination field of the email.

Send with SMS+ Application ^TOP^

#define ALP_EXG2_SEND_BY_SMS_MMS_VERB 
ALP_EXG2_SEND_ACTIONCLASS"/bySMS+" 

Use this verb to send any type of file to another device, including images, sound, or video, as SMS/MMS content, or as an SMS/MMS attachment. When objects are sent, the name and mimetype are embedded within each object that is added to the request.

The method by which objects are sent depends on the type of data, and is determined by the service:

• "text/plain" data: Sent as SMS content
• media file (image, audio, video): Sent as MMS content
• other data type: Sent as MMS attachment

Save to Storage ^TOP^

#define ALP_EXG2_SEND_TOSTORAGE_VERB 
ALP_EXG2_SEND_ACTIONCLASS"/storage" 

This service is usually invoked to store files that have been received on the device through any means (Bluetooth, SMS, as an email attachment, etc.).

Use this verb to store data objects using any application that can write the object to storage. The exact action depends on the type of data object:

• vObject: Data is inserted into the corresponding database.
• multimedia file: File is stored the media directory.
• bundle, .prc, or Java application: Application file is installed on the device.

Every application that is reponsible for storing data (of any type) should register a handler for this verb. The registered subject should be the mimetype of the data the application handles.

Get ^TOP^

The Get action class (ALP_EXG2_GET_ACTIONCLASS) is used to return data to a device or application as a data object. For example, you can get a vCard, take a picture, record a movie, or select a media file using the Get action class.

The Get action class differs from the Import action class described in "Import." When getting data, the handler determines where the data can be found (file, database, hardware acquisition). When importing data, the handler always takes data from the file system.

Capture Images or Videos ^TOP^

#define ALP_EXG2_GET_CAPTURE_VERB 
ALP_EXG2_GET_ACTIONCLASS"/capture" 

This service launches an application to capture a media file. The subject must be set to the type of media to capture (typically image/jpeg or a video type).

Optionally, you can specify where to store the captured file by providing a file name. Pass a path in ALP_EXG2_AUDIO_FILEPATH_STRING_PARAM:

#define ALP_EXG2_AUDIO_FILEPATH_STRING_PARAM "filePath" 

The value of the parameter, if it exists, is the path to store the recorded file. On output, the value is updated to be the full path to the recorded file name. This is useful when the requester just needs a reference to the file and not the actual data.

Get Contacts from Storage ^TOP^

To get Contacts data from storage, use the verb ALP_EXG2_GET_FROMSTORAGE_VERB, and invoke it with the subject, ALP_EXG2_CONTACTS_SUBJECT.

You can customize a "get Contacts data" request with several options. See the ACCESS Linux Platform doxygen-generated API reference material installed with the SDK for more information about these options.

Get Objects from Storage ^TOP^

#define ALP_EXG2_GET_FROMSTORAGE_VERB 
ALP_EXG2_GET_ACTIONCLASS"/storage" 

When invoked, this service presents an interface that allows the user to select data. The data presented by the user interface is of the type requested by the subject, and is available from a database, file system, hardware, and so on. Data is returned as a data object.

View ^TOP^

The View action class (ALP_EXG2_VIEW_ACTIONCLASS) is used to display data on a device or in an application. For example, you can display an image, play a video or sound, or read a document.

All handlers must be able to accept one or both of the following:

• A single object to view as specified by ALP_EXG2_FILENAME_STRING_PARAM. This file must point to a world-readable file that exists for the lifetime of the request.
• Multiple objects added to the request. If the handler requires actual files, the handler may call alp_exg2_request_receive_by_file() on each object to save and view a temporary file.

Display Events ^TOP^

#define ALP_EXG2_CALENDAR_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/calendar" 

Use this verb to display events that are already in the Calendar application's database, or are in vCal file format. The default behavior is to expect vCal data in a data object.

Optionally, you can store vCal data in a file whose name is passed in a ALP_EXGMGR_FILENAME_PARAM string parameter.

In addition, the application can request that the displayed event be editable or not by setting a value in ALP_EXG2_EDITABLE_INT_PARAM. By default, the event is not editable.

Display Contacts and vCards ^TOP^

#define ALP_EXG2_CONTACTS_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/contacts" 

Use this verb to display a data object as a record in the Contacts application. The object is not editable and is not persistently stored.

To select which Contacts data object to display, you can provide the following selection parameters:

• ALP_EXG2_IDENTIFIER_STRING_PARAM: If present and non-NULL, this parameter is an unsigned string representing the local ID of the Contacts data object to display. This parameter overrides any fd_data.
• ALP_EXG2_EDITABLE_INT_PARAM: If present and non-zero, this parameter allows the user to edit the Contacts data object. This parameter defaults to 1 unless fd_data is provided.

If selection parameters are not provided, the user can choose the data object to display from a user interface.

Display Documents ^TOP^

#define ALP_EXG2_DOC_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/docviewer" 

Use this verb to display a data object, such as a PDF document, in the Documents application. The supported mimetypes are:

• application/vnd.ms-excel
• application/vnd.ms-powerpoint
• application/pdf
• text/plain

Display Memos, Notes, and Text Files ^TOP^

#define ALP_EXG2_MEMO_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/memo" 

Use this verb to display data objects as a new memo, vNote, or text file in the Memos application. The data object is not recorded.

Play Audio Files ^TOP^

#define ALP_EXG2_MUSICPLAYER_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/musicplayer" 

Use this verb to register for supported audio types to play as common audio files. Data objects will begin playing immediately.

Display Images ^TOP^

#define ALP_EXG2_PHOTOS_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/photos" 

Use this verb to register for supported image types, as well as collection types (collection/x-ply).

Display Tasks and vToDo Files ^TOP^

#define ALP_EXG2_TASKS_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/tasks" 

Use this verb to display data objects as records in the Tasks application.

Display Videos ^TOP^

#define ALP_EXG2_VIDEO_VIEW_VERB 
ALP_EXG2_VIEW_ACTIONCLASS"/videoplayer" 

Use this verb to register for supported video types. Data objects of supported types are played immediately.

Import ^TOP^

The Import action class (ALP_EXG2_IMPORT_ACTIONCLASS) is used to return data stored in the file system. Imported data is returned as a data object in the response request.

The Import action class differs from the Get action class described in "Get." When importing data, the handler always takes data from the file system. When getting data, the handler determines where the data can be found (file, database, hardware acquisition).

Import from File ^TOP^

#define ALP_EXG2_IMPORT_FROMFILE_VERB 
ALP_EXG2_IMPORT_ACTIONCLASS"/file" 

Use this verb to present a user interface that allows users to select objects from a file or external storage. Selected files are returned as data objects.

Export ^TOP^

The Export action class (ALP_EXG2_EXPORT_ACTIONCLASS) is used to save data to the file system. Exported data is passed as data objects.

The Export action class differs from the Send action class described in "Send." When exporting data, the handler always sends data to the file system. When sending data to storage, the handler determines where to save the data.

Export to File ^TOP^

#define ALP_EXG2_EXPORT_TOFILE_VERB 
ALP_EXG2_EXPORT_ACTIONCLASS"/file" 

Use this verb to save data objects to the file system.

Dial ^TOP^

The Dial action class (ALP_EXG2_DIAL_ACTIONCLASS) contains handlers that can dial a phone number for a voice call or a video call.

This action class requires all handlers to:

• Register the subject ALP_EXG2_PHONESTRING_SUBJECT or ALP_EXG2_CONTACT_IDENTIFIER_STRING_SUBJECT.
• Expect to receive phone numbers in a string parameter (ALP_EXG2_GENERIC_STRING_PARAM) if the subject is ALP_EXG2_PHONESTRING_SUBJECT
• Expect to receive the contact ID in a string parameter (ALP_EXG2_GENERIC_STRING_PARAM) if the subject is ALP_EXG2_CONTACT_IDENTIFIER_STRING_SUBJECT

Dial Video Call with Phone Application ^TOP^

#define ALP_EXG2_DIAL_VIDEOCALL_VERB 
ALP_EXG2_DIAL_ACTIONCLASS"/videoCall" 

Use this verb to dial a phone number to establish a video call.

Dial Voice Call with Phone Application ^TOP^

#define ALP_EXG2_DIAL_VOICECALL_VERB 
ALP_EXG2_DIAL_ACTIONCLASS"/voiceCall" 

Use this verb to dial a phone number to establish a voice call.

Custom ^TOP^

The Custom category contains all customized handlers. These verbs are not based on an action class, and they do not follow particular conventions for passing data and parameters. Each customized handler must define its own parameters and behavior.

Handlers in the custom group cannot be dynamically discovered. A requester that wants to use a custom service must explicitly invoke the required verb, subject, and add all request parameters as required by the definition.

Open URL in Browser Application ^TOP^

#define ALP_EXG2_BROWSER_OPEN_URL_VERB "Open" 

Use this verb to start the Browser application and open a URL.

Set the subject to ALP_EXG2_URLSTRING_SUBJECT.

Pass the URL as a string in ALP_EXG2_GENERIC_STRING_PARAM.

Make Emergency Call with Phone Application ^TOP^

#define ALP_EXG2_DIAL_EMERGENCY_SUBJECT "dial_emergency" 
#define ALP_EXG2_DIAL_EMERGENCY_VERB "dialEmergency" 

Use this verb to make an emergency call with the Phone application.

Dial Voicemail Service with Phone Application ^TOP^

#define ALP_EXG2_DIAL_VOICEMAIL_SUBJECT "dial_voicemail" 
#define ALP_EXG2_DIAL_VOICEMAIL_VERB "dialVoicemail" 

Use this verb to dial voicemail services using the Phone application.

Get Web Content in Downloads Application ^TOP^

#define ALP_EXG2_DOWNLOAD_URL_VERB "alp_download" 

Use this verb to start the Downloads application and begin downloading the content of a URL.

• Set the subject to ALP_EXG2_URLSTRING_SUBJECT
• Pass the URL as a string in ALP_EXG2_GENERIC_STRING_PARAM

View Attention Items in Email Application ^TOP^

#define ALP_EXG2_EMAIL_ATTENTION_SUBJECT 
"email_attention_subject" 
#define ALP_EXG2_EMAIL_VIEW_ATTENTION_VERB 
"email_attention_verb" 

Use this verb to the email application and jump to the Inbox where the attention item was generated.

Set the subject to ALP_EXG2_EMAIL_ATTENTION_SUBJECT.

Pass the account ID of the email attention item in ALP_EXG2_EMAIL_ATTENTION_ACCOUNT_ID_INT_PARAM.

Pass the service ID of the email attention item in ALP_EXG2_EMAIL_ATTENTION_SERVICE_ID_INT_PARAM.

Start Chat with iMessenger Application ^TOP^

#define ALP_EXG2_IM_START_CHAT_VERB "Chat" 

Use this verb to start the iMessenger application.

Set the subject to ALP_EXG2_EMAILSTRING_SUBJECT.

Pass the email address of the chat buddy as a string in ALP_EXG2_GENERIC_STRING_PARAM.

Launch Photos Application in Grid-view Mode ^TOP^

#define ALP_EXG2_PHOTOS_LIST_VIEW_SUBJECT "application/img" 
#define ALP_EXG2_PHOTOS_LIST_VIEW_VERB "photos_view_list" 

Use this verb to open the Photos application Picture Viewer in grid-view mode. No input parameters are required, and no values are returned.

Play Stream Content from a URL ^TOP^

#define ALP_EXG2_PLAY_STREAM_FROM_URL_VERB 
"play_stream_from_url" 

Use this verb to start the PVPlayer application and play content from a URL.

Set the subject to ALP_EXG2_RTSPURLSTRING_SUBJECT.

Pass the URL string in ALP_EXG2_GENERIC_STRING_PARAM.

Install Certificates in Security Settings ^TOP^

#define ALP_EXG2_SECU_CERT_STORE_VERB "store" 

Use this verb to start the Settings application Security panel and display the install/accept certificate dialog.

The application to launch the verb is specified in a string parameter:

#define ALP_EXG2_SECU_CERT_APPNAME_STR_PARAM "appname" 

Supported subjects are:

• application/x-x509-ca-cert
• application/x-x509-user-cert
• application/pkcs12
• application/x-pkcs12
• application/x-x509-email-cert
• .p12
• .pfx
• .cer
• .pem
• .crt

The certificate must be contained in a file whose file name is passed as a string parameter:

#define ALP_EXG2_SECU_CERT_FILENAME_STR_PARAM "filename" 

Alternatively, the certificate must be contained as binary data which is passed in a blob parameter:

#define ALP_EXG2_SECU_CERT_DATA_BLOB_PARAM "data" 

Use an int parameter to specify mode (this parameter is mandatory):

#define ALP_EXG2_SECU_CERT_RESULT_INT_PARAM "mode" 

• 0 - Blocking: receive data and show the install/accept dialog
• 1 - Unblocking: Only receive data, then return

The handler returns the result state in an int parameter:

#define ALP_EXG2_SECU_RESULT_INT_PARAM Ā "result" 

• 0 - Cancel or failed to install
• 1 - Installed successfully

Accept Certificates in Security Settings ^TOP^

#define ALP_EXG2_SECU_CERT_ACCEPT_VERB "accept" 

Use this verb to start the Settings application Security panel and display the install/accept certificate dialog when the Browser or Email applications encounter a server with an expired or self-signed certificate.

Supported subjects are:

• "application/x-x509-ca-cert"
• "application/x-x509-user-cert"
• "application/pkcs12"
• "application/x-pkcs12"
• application/x-x509-email-cert
• .p12
• .pfx
• .cer
• .pem
• .crt

This handler has the same paramaters as the verb ALP_EXG2_SECU_CERT_STORE_VERB described in "Install Certificates in Security Settings."

The certificate must be contained in a file whose file name is passed as a string in ALP_EXG2_SECU_CERT_FILENAME_STR_PARAM. Alternatively, the certificate must be contained as binary data which is passed in a blob parameter, ALP_EXG2_SECU_CERT_DATA_BLOB_PARAM.

The handler returns the result state in the ALP_EXG2_SECU_RESULT_INT_PARAM int parameter:

• 0 - Reject or fail to accept/save
• 1 - Accept once successfully
• 2 - Accept and save successfully
• 4 - Exists: The cerificate already exists

Verify Device Lock in Security Settings ^TOP^

#define ALP_EXG2_SECU_VERIFY_VERB "verify" 

Use this verb to verify if the device is locked. If so, the user must supply the required password or enter Emergency Call mode.

Set the subject to ALP_EXG2_SECU_VERIFY_SUBJECT:

#define ALP_EXG2_SECU_VERIFY_SUBJECT "application/x-text" 

The handler returns the result state in the ALP_EXG2_SECU_RESULT_INT_PARAM int parameter:

#define ALP_EXG2_SECU_RESULT_INT_PARAM "result" 

• 0 - Password verified successfully
• 1 - Entered Emergency Call mode
• 2 - Cancel the verify dialog

View Certificates in Security Settings ^TOP^

#define ALP_EXG2_SECU_VIEW_VERB "view" 

Use this verb to display the Settings application Security panel Certificates dialog when the Browser application encounter a server requiring a certificate.

Set the subject to ALP_EXG2_SECU_VERIFY_SUBJECT.

Compose Message in SMS/MMS Application ^TOP^

#define ALP_EXG2_SMS_MMS_COMPOSE_VERB "compose_sms+" 

Use this verb to start the SMS+ application to compose an MMS or SMS message.

Set the subject to ALP_EXG2_PHONESTRING_SUBJECT.

The destination, content, and type of message can be specified by the following parameters:

• If the string parameter ALP_EXG2_GENERIC_STRING_PARAM exists and is not empty, the destination number of the SMS or MMS message is pre-filled with the value of this parameter. The parameter should be a phone number.
• If the string parameter ALP_EXG2_SMS_MMS_BODYTEXT_STRING_PARAM exists and is not empty, the body of the SMS or MMS message pre-filled with this string.
• If the int parameter ALP_EXG2_SMS_MMS_SERVICEID_INT_PARAM exists, the value of that parameter indicates the type of message to compose:
  • The value ALP_POSTAL_SERVICE_ID_MMS indicates an MMS message.
  • The value ALP_POSTAL_SERVICE_ID_SMS indicates an SMS message. This is the default if a parameter is not supplied.

Use Record ID to Display SMS/MMS Message ^TOP^

#define ALP_EXG2_SMS_MMS_VIEWBYLUID_SUBJECT 
"ps_reference_sms" 
#define ALP_EXG2_SMS_MMS_VIEWBYLUID_VERB "view_by_luid_SMS+" 

Use this handler to start the SMS+ application and display an SMS or MMS message from the database.

Set the subject set to ALP_EXG2_SMS_MMS_VIEWBYLUID_SUBJECT.

Pass the mandatory record ID in the ALP_EXG2_SMS_MMS_LUID_INT_PARAM int parameter.