include/hiker/exgmgr2.h File Reference

Detailed Description

Public headers for Exchange Manager.

#include <sys/types.h>
#include <hiker/types.h>
#include <hiker/sysclass.h>

Go to the source code of this file.

Data Structures

struct _AlpExgAsyncExecuteEventInfoType

event msg sent to the async execute event function. More...

Errors

#define ALP_EXG2_ACCESSFILE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00210000))

error opening/stating a file

#define ALP_EXG2_BINDSOCKET_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00080000))

Cannot bind a socket.

#define ALP_EXG2_BROKENPIPE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00250000))

Error or hangup on connection between client and handler or between daemon nad handler.

#define ALP_EXG2_BUNDLENAMETOOLONG_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00120000))

bundle name too long

#define ALP_EXG2_CANNOTRCVFD_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00330000))

A file descriptor could not be read across processes..

#define ALP_EXG2_CANNOTSENDFD_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00320000))

A file descriptor could not be sent across processes..

#define ALP_EXG2_CONNECTSOCKET_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x000A0000))

Cannot connect a socket.

#define ALP_EXG2_CREATEFILE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00200000))

error opening/creating a file

#define ALP_EXG2_CREATESOCKET_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00070000))

Cannot create a socket.

#define ALP_EXG2_DAEMONFAILURE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00030000))

General daemon internal failure.

#define ALP_EXG2_FCNTLSOCKET_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x000D0000))

Cannot set socket options.

#define ALP_EXG2_FIRST_EXT_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00800000))

Base for errors generated by a requester or a handler. These enable a handler to return a precise specific error.

#define ALP_EXG2_GSOURCE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00240000))

error while creating or attaching a gsource, or adding a timeout to a gsource

#define ALP_EXG2_HANDLERALREADYREGISTERED_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00140000))

thisverb/subject is already registered by this registrant

#define ALP_EXG2_HANDLERISLOCALONLY_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00170000))

Handler doen't accept requests from remote device.

#define ALP_EXG2_HANDLERNOTFOUND_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00160000))

There was no registered handler to handle this request.

#define ALP_EXG2_HANDLERREGISTEREDINACTIVE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00150000))

There was already an active handler for this verb/subject. This handler was registered but flagged inactive.

#define ALP_EXG2_HANDLERTIMEOUT_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00180000))

Handler did not respond to invocation in time.

#define ALP_EXG2_INVALIDAPIPARAM_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00060000))

An invalid parameter was passed to some API.

#define ALP_EXG2_LIBRARYFAILURE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00040000))

General library internal failure.

#define ALP_EXG2_LISTENSOCKET_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00090000))

Cannot listen a socket.

#define ALP_EXG2_LOCALIZEDVERBTOOLONG_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x000F0000))

Localized verb is too long.

#define ALP_EXG2_MIMETYPETOOLONG_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00110000))

mimetype is too long

#define ALP_EXG2_NOMOREOBJECTS_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00350000))

There are no more objects to receive.

#define ALP_EXG2_NOTRANSPORTS_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00020000))

No transport plug-in found.

#define ALP_EXG2_OBJECTNOTREADY_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00340000))

The object you are trying to receive is not fully defined yet. Try again later.

#define ALP_EXG2_OUTOFMEMORY_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00010000))

Out of memory.

#define ALP_EXG2_PARAMNOTFOUND_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00050000))

Request does not contain the expected parameter.

#define ALP_EXG2_PROGRAM_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00500000))

A consistency check revealed a programming error.

#define ALP_EXG2_READFILE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00230000))

error reading from a file

#define ALP_EXG2_READSOCKET_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x000C0000))

Cannot read a socket.

#define ALP_EXG2_REGCACHE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00190000))

error trying to open/create/rename the registration cache file

#define ALP_EXG2_REQUESTALREADYRECEIVED_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00310000))

The requested request is currently already handled..

#define ALP_EXG2_REQUESTNOTFOUND_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00300000))

The requested request could ne be found. It may have timedout and been removed before receive request was called..

#define ALP_EXG2_SUBJECTTOOLONG_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00100000))

subject is too long

#define ALP_EXG2_TIMEOUT_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00380000))

Timeout during data object transfer between requester and handler.

#define ALP_EXG2_UNKNOWN_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00370000))

Something failed, we don't know what exactly.

#define ALP_EXG2_USERCANCEL_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00360000))

Execution was canceled.

#define ALP_EXG2_VERBTOOLONG_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x000E0000))

Verb is too long.

#define ALP_EXG2_WRITEFILE_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x00220000))

error writing to a file

#define ALP_EXG2_WRITESOCKET_ERR   ((alp_status_t) (ALP_CLASS_EXCHANGE2 | 0x000B0000))

Cannot write a socket.

Asynchronous Execution events

This event info is passed to the event callback function during execution of an asynchronous request. The only event currently defined is the completion event.

#define ALP_EXG2_ASYNC_EXECUTE_EVENT_COMPLETE   1

Execution has completed.

typedef int alp_exg_async_execute_event_t

Event Type.

typedef _AlpExgAsyncExecuteEventInfoType AlpExgAsyncExecuteEventInfoType

event msg sent to the async execute event function.

Prefixes for localized resource verbs contained in bundle catalogs.

When registering a handler, you can provide a localized verb that will be returned to applications when enumerating verbs. If the device locale changes, you must unregister and re-register your handler with the localized verb in the new locale. Another possibility is to specify the localized verb as a resource. If you do this, the exchange daemon will read the localized string from your bundle resources, and you don't need to handle the locale change yourself.

#define ALP_EXG2_BUNDLE_LOCALE_VERB_BUNDLE_PREFIX(bundle)   "RSC=" bundle "/^t/"

This prefix should be used for localized verbs which are contained in a known bundle. The bundle name must be a constant string.

#define ALP_EXG2_BUNDLE_LOCALE_VERB_PREFIX   "RSC=^t/"

This prefix should be used for localized verbs which are contained in the same bundle which the exchange handler is registered to launch.

Max size for verbs, subject and bundlename

These are the length limits for strings passed to the registration APIs.

#define ALP_EXG2_BUNDLENAME_MAXLEN   150

max len for the bundle name

#define ALP_EXG2_LOCALIZED_VERB_MAXLEN   60

max len for the localized verb

#define ALP_EXG2_SUBJECT_MAXLEN   50

max len for the request subject

#define ALP_EXG2_VERB_MAXLEN   30

max len for the verb

Predefined subjects

ALP defines some symbolic subjects such as email string or phone number. These subjects are defined here by convention.

#define ALP_EXG2_CONTACT_IDENTIFIER_STRING_SUBJECT   ALP_EXG2_NOWILDCARD_PREFIX"contactidstr_predef"

A string representing the contacts database identifier for a contact (unsigned int, must be converted back to AlpLuid).

#define ALP_EXG2_EMAILSTRING_SUBJECT   ALP_EXG2_NOWILDCARD_PREFIX"emailstr_predef"

A string representing an email.

#define ALP_EXG2_EXTENDEDPHONESTRING_SUBJECT   ALP_EXG2_NOWILDCARD_PREFIX"extphonestr_predef"

A string representing an extended phone number (for example, a USSD request).

#define ALP_EXG2_NOWILDCARD_PREFIX   "nowcp_"

exact match only : a subject starting with this prefix will not match a wildcard. Verbs registered with wildcard subject will not be returned when enumerating verbs for such a subject.

#define ALP_EXG2_PHONESTRING_SUBJECT   ALP_EXG2_NOWILDCARD_PREFIX"phonestr_predef"

A string representing a phone number.

#define ALP_EXG2_RTSPURLSTRING_SUBJECT   ALP_EXG2_NOWILDCARD_PREFIX"rtspstr_predef"

A string representing an RTSP URL.

#define ALP_EXG2_URLSTRING_SUBJECT   ALP_EXG2_NOWILDCARD_PREFIX"urlstr_predef"

A string representing an URL.

Predefined Classes of action

A class of action is basically a prefix whose purpose is to group all the verbs that perform a similar symbolic action, but using different methods. If you base your verb on a class of action, exchange mgr clients will be able to find your method dynamically as long as they know the class.
If your verb is private, don't base it on a class of action. But if you define several private methods for some symbolic action of your own, define your own private class and base all your verbs on it. This will enable to enumerate the available methods based on this action class.
Never use a predefined action class as a verb.

#define ALP_EXG2_DIAL_ACTIONCLASS   "exg_dial_predef"

Dial : methods examples: voice call, video call, send sms-mms...

#define ALP_EXG2_EDIT_ACTIONCLASS   "exg_edit_predef"

Edit (modify) data: methods examples: edit image, edit text...

#define ALP_EXG2_EXPORT_ACTIONCLASS   "exg_export_predef"

Export : methods examples: to file...

#define ALP_EXG2_GET_ACTIONCLASS   "exg_get_predef"

Get data: methods examples: take picture, get file, get vcard...

#define ALP_EXG2_IMPORT_ACTIONCLASS   "exg_import_predef"

Import : methods examples: from file...

#define ALP_EXG2_PRINT_ACTIONCLASS   "exg_print_predef"

Print data: methods examples: Print to network, Print to Bluetooth...

#define ALP_EXG2_SEND_ACTIONCLASS   "exg_send_predef"

Send data: methods are typically storage(local), obex bluetooth/IR, email attachments, SMS, MMS, FTP...

#define ALP_EXG2_VIEW_ACTIONCLASS   "exg_view_predef"

View data: methods examples: display image, play video, play mp3, read document...

Registering, Checking and Unregistering handlers

An application can publish a service offering by registering a handler with exchange manager. A registration is specified by a verb (the action) and a subject (upon which the verb acts).
If you want your handler to be dynamically discoverable by exchange manager clients (the apps who will invoke your service), you should define your verb as a well known class of action followed by the method you implement. For example, if your handler can store data to the device storage, you would build the verb by concatenating the predefined ALP_EXG2_SEND_ACTIONCLASS class and a string representing your method such as "storage".
You can of course define your own class of action if you need your own symbolic action. Or, if you're writing a private handler, you can just define whatever verb you like.
The subject represents what the verb will act upon.
In case there will be no data objects passed with the request, the subject is some string you define and publish in your documentation. Note there are already some of them defined for phone number, url and email strings.
In case there will be data objects passed with the request, the subject will often be the mime type of the objects. This makes it convenient for client to dynamically find your handler by querying on the type of the data they want to send you.
But it is also possible that there are different data objects with different types, all of them representing a global entity (e.g. a Palm application is composed of several prc and pdb files). In this case, the subject would probably be a string representing that global entity (e.g. "palmos_application").
Your handler may support several subjects, and it can use wildcards to specify that. There are two forms you can use: 1 - supertype + '/' + '*' (e.g. "image / *") ; you support all standard mime types that are images. 2 - '*' : your action is independant of the data (e.g. you send files as email attachments).
Note that your handler will never be invoked with a wildcard in the subject (unless the requester explicitly sets it). The wildcard is only used by exchange manager to map different subjects to your handler, but your handler is always called with the real subject that was specified by the requester.
There can be only one active handler for a given verb and subject. If there is already a handler registered for the same verb and subject than the combination you try to register, your will receive a ALP_EXG2_HANDLERREGISTEREDINACTIVE_ERR error. This means your handler was correctly registered, but it was flagged 'inactive' and it will never be called while in this state. In this case, your handler could become active in two ways: 1 - the current active handler is unregistered, and your handler is the next inactive handler in the list. You become the active handler 2 - the user uses a pref panel that list the handlers and he selects which is the active one (e.g. there are 2 email applications on the device, both register the same handlers, the user selects which is the active one.

#define ALP_EXG2_HANDLER_IS_NOT_REENTRANT   0

#define ALP_EXG2_HANDLER_IS_REENTRANT   1

#define ALP_EXG2_HANDLER_LOCAL_AND_REMOTE   0

#define ALP_EXG2_HANDLER_LOCAL_ONLY   1

typedef void(* alp_exg2_handler_callback_func )(AlpExg2RequestId iRequestId)

Handler Callback function prototype.

typedef int alp_exg_handler_localonly_t

typedef int alp_exg_handler_reentrant_t

alp_status_t alp_exg2_handler_check_registration (const char *iVerb, const char *iSubject)

Checks whether there is a handler registered for a given verb/subject.

alp_status_t alp_exg2_handler_register_callback (const char *iVerb, const char *iLocalizedVerb, const char *iSubject, alp_exg2_handler_callback_func iHandlerCallbackFunc, alp_exg_handler_localonly_t iLocalOnly, alp_exg_handler_reentrant_t iReentrant)

Register a handler implemented as a callback function in a running process.

alp_status_t alp_exg2_handler_register_launch (const char *iVerb, const char *iLocalizedVerb, const char *iSubject, const char *iBundle, alp_exg_handler_localonly_t iLocalOnly, alp_exg_handler_reentrant_t iReentrant)

Register a handler implemented in a bundle.

alp_status_t alp_exg2_handler_unregister_callback (const char *iVerb, const char *iSubject, alp_exg2_handler_callback_func iHandlerCallbackFunc)

Unregister a handler implemented as a callback.

alp_status_t alp_exg2_handler_unregister_launch (const char *iVerb, const char *iSubject, const char *iBundle)

Unregister a handler implemented in a bundle.

Media Hints

Your handler will stream data objects from different places. As a handler, this is transparent for you. In order to help you decide whether, for example, you want to display progress, the requester or the exchange transport may set some integer parameter to give you one or more hints of the media.
Use alp_exg2_request_int_parameter_get() to try to get the hints you are interested in. Note they are optional so be prepared for a default decision.

#define ALP_EXG2_HINT_MEDIA_SPEED_INT_PARAM   "exg_mediaspeed"

Media Speed hint : if this parameter exists, it gives an indication of the incoming bandwidth in kbps.

#define ALP_EXG2_HINT_MEDIA_TYPE_3G   8

#define ALP_EXG2_HINT_MEDIA_TYPE_BLUETOOTH   2

#define ALP_EXG2_HINT_MEDIA_TYPE_EDGE   7

#define ALP_EXG2_HINT_MEDIA_TYPE_ETH   4

#define ALP_EXG2_HINT_MEDIA_TYPE_GPRS   6

#define ALP_EXG2_HINT_MEDIA_TYPE_INT_PARAM   "exg_mediatype"

Media Type hint : if this parameter exists, it gives an indication of the media type.

#define ALP_EXG2_HINT_MEDIA_TYPE_IRDA   3

#define ALP_EXG2_HINT_MEDIA_TYPE_LOCAL   1

#define ALP_EXG2_HINT_MEDIA_TYPE_WIFI   5

#define ALP_EXG2_HINT_OBJECTS_TOTAL_SIZE_INT_PARAM   "exg_objtotalsize"

Total data size Hint : if this parameter exists, it gives an indication of the total size of received objects.

#define ALP_EXG2_HINT_SLOW_MEDIA_INT_PARAM   "exg_slowmedia"

Sender indicates slow media Hint : if this parameter exists and value is not zero, it indicates the sender recommends to use progress window.

Executing a request

Executing a request is the process of dispatching it to the handler which registered for the corresponding verb and subject. When the handler completes execution, you receive the execution result, and possibly parameters and/or data objects that were sent back.

typedef void(* alp_exg2_execute_event_info_func )(AlpExg2Request iRequest, void *iUserData, AlpExgAsyncExecuteEventInfoType *iExecuteEventInfo)

Event callback for request run asynchronously.

alp_status_t alp_exg2_request_execute_async (AlpExg2Request iRequest, alp_exg2_execute_event_info_func iExecuteEventInfoFunc, void *iUserData)

Execute a request asynchronously.

alp_status_t alp_exg2_request_execute_cancel (AlpExg2Request iRequest, alp_status_t iCancelErr)

Cancel a request executing asynchronously.

alp_status_t alp_exg2_request_execute_sync (AlpExg2Request iRequest)

Execute a request synchronously.

The Request data type

The exchange manager API mostly accesses a request object. This object is to be used as a handle.

typedef void * AlpExg2Request

The exchange request. A request is created and accessed using Exchange Manager API only.

typedef void * AlpExg2RequestId

Reference Id you receive in an exchange handler. Use this id to receive the corresponding exchange request.

Finding verbs dynamically

In the application UI, the user can trigger actions by tapping the data itself (tap a photo, tap a phone number or email address�). For some actions, there may be a button or menu item available. In response to this user event, an app can query the available verbs in two ways. Let's say the application has "image/jpeg" data. 1) If the user just points at the data directly on the screen, the app can ask "what can I do with image/jpeg". The app does not specify any action class, so it will get back a list of all the verbs that can handle this subject. 2) If the user taps a button or selects a menu item (typically "Send"), the app can ask "How can I 'action=Send' image/jpg". This time, the app specified a symbolic action, so it will get a similar list filtered with the 'Send' action.

alp_status_t alp_exg2_handler_query_methods (const char *iAction, const char *iSubject, const char *iExcludeInvokeName, uint32_t *oEntryCount, char **oDataP)

Dynamically find handlers based on a subject and/or a verb or class of action.

Getting parameters from a request

This section describes how you can extract parameters from a request you receive. You can also use these functions to extract parameters that were sent back as the execution result.

alp_status_t alp_exg2_request_blob_parameter_get (AlpExg2Request iRequest, const char *iParamTag, uint8_t **oBlob, size_t *oBlobSize)

Get a blob parameter from the request.

alp_status_t alp_exg2_request_int_parameter_get (AlpExg2Request iRequest, const char *iParamTag, int *oParamValue)

Get an integer parameter from the request.

alp_status_t alp_exg2_request_string_parameter_get (AlpExg2Request iRequest, const char *iParamTag, char **oParamValue)

Get a string parameter from the request.

alp_status_t alp_exg2_request_string_parameter_get_const (AlpExg2Request iRequest, const char *iParamTag, const char **oParamValue)

Get a string parameter from the request (const).

Adding parameters to a request

A request can contain integer, string, or blob (binary block) parameters. Parameters are generally optional, but you must always read the handler documentation to learn what it expects. Normally, you should not use parameters to pass data (add data objects instead), because this forces the handler to know which parameter contain the data, and which format the data is. It makes the handler non generic. So please consider using parameters to pass handler customization options, such as "showUI", "askUser", etc...
If you are working on a request you received, it is also possible to add parameters that will sent back to the requester when you complete and exit the handler.

alp_status_t alp_exg2_request_blob_parameter_set (AlpExg2Request iRequest, const char *iParamTag, const uint8_t *iBlob, size_t iBlobSize)

Add a binary parameter to the request.

alp_status_t alp_exg2_request_int_parameter_set (AlpExg2Request iRequest, const char *iParamTag, int iParamValue)

Add an integer parameter to the request.

alp_status_t alp_exg2_request_string_parameter_set (AlpExg2Request iRequest, const char *iParamTag, const char *iParamValue)

Add a string parameter to a request.

Getting data objects from a request

This section describes the functions to receive the data objects that are attached to the request. You can choose the receive method independantly of how the data objects were added.
Receiving objects is essentially a loop of alp_exg2_request_object_rcv_info() and alp_exg2_request_object_rcv_by_xxxx(). The loops ends when you are returned ALP_EXG2_NOMOREOBJECTS_ERR.
Automatic receive progress is implemented by exchange manager, but you can disable it if you prefer.

alp_status_t alp_exg2_request_check_still_active (AlpExg2Request iRequest)

Check if the requester is still active.

alp_status_t alp_exg2_request_object_rcv_by_fd (AlpExg2Request iRequest, uint32_t iObjectId, int *oFd)

Receive a file descriptor to read the data from.

alp_status_t alp_exg2_request_object_rcv_by_file (AlpExg2Request iRequest, uint32_t iObjectId, const char *iDestFile)

Receive an object into a file.

alp_status_t alp_exg2_request_object_rcv_by_ptr (AlpExg2Request iRequest, uint32_t iObjectId, uint8_t **oObjectP, size_t *oObjectSize)

Receive the data object in a memory chunk.

alp_status_t alp_exg2_request_object_rcv_count (AlpExg2Request iRequest, uint32_t *oObjectCount)

Get an indication of the number of data objects in the request.

alp_status_t alp_exg2_request_object_rcv_info (AlpExg2Request iRequest, uint32_t iObjectId, size_t *oObjectSize, const char **oObjectName, const char **oObjectType, const char **oObjectDscr)

Get Info for the next received data object.

alp_status_t alp_exg2_request_receive_progress_disable (AlpExg2Request iRequest)

Disable the automatic receive progress.

Creating and Deleting requests

In order to invoke a service in the system, you must first create a request. At least a verb and a subject must be specified before you can execute the request. Later, when you have got the execution result, you must delete the request.

alp_status_t alp_exg2_request_create (AlpExg2Request *oRequest, const char *iVerb, const char *iSubject)

Create a request.

alp_status_t alp_exg2_request_delete (AlpExg2Request iRequest)

Delete a request.

alp_status_t alp_exg2_request_set_subject (AlpExg2Request iRequest, const char *iSubject)

Set the subject.

alp_status_t alp_exg2_request_set_verb (AlpExg2Request iRequest, const char *iVerb)

Set the verb.

Manage Peer names

When displaying progress UI, it can be interesting to display the remote user name, especially when the requester acts as a proxy for the real sender (like it happens with Bluetooth receive). These functions let you set your name and get the remote name, provided it was specified by the remote of course.

alp_status_t alp_exg2_request_get_remote_peer_name (AlpExg2Request iRequest, char **oPeerName)

Get the remote name.

alp_status_t alp_exg2_request_get_remote_peer_name_const (AlpExg2Request iRequest, const char **oPeerName)

Get the remote name (const).

alp_status_t alp_exg2_request_set_local_peer_name (AlpExg2Request iRequest, const char *iPeerName)

Set the name of the requester.

Receiving a request

This section explains how a handler is invoked, receives the request that was sent, and returns a result.

alp_status_t alp_exg2_request_get_subject (AlpExg2Request iRequest, char **oSubject)

Get the subject.

alp_status_t alp_exg2_request_get_subject_const (AlpExg2Request iRequest, const char **oSubject)

Get the subject (const).

alp_status_t alp_exg2_request_get_verb (AlpExg2Request iRequest, char **oVerb)

Get the verb.

alp_status_t alp_exg2_request_get_verb_const (AlpExg2Request iRequest, const char **oVerb)

Get the verb (const).

alp_status_t alp_exg2_request_receive_complete (AlpExg2Request iRequest, alp_status_t iResult)

Complete your handler execution.

alp_status_t alp_exg2_request_receive_start (AlpExg2Request *oRequest, AlpExg2RequestId iRequestId)

Receive a request in your handler.

Adding data objects to a request

It is possible to attach as many data object as you like to a request. Each data object is fully qualified by a name, a size and a mime type. As a client, you can specify the data source by file, file descriptor or memory pointer as best suits you. As a handler, you can access the data objects by file, file descriptor or memory pointer as you like as well. You don't have to worry about access rights because exchange manager will make sure the handler can read the data. Exchange Manager will also take care to 'hide' your original data source so that the handler can only read data but has no way to know where the data comes from.
The data transfer between the requester and the handler is optimized as much as possible. Most of the time, the handler will be able to directly stream the data from the original data source, such that there is absolutely no data copy.
On rare occasion, you may need to start executing the request before you have added all the data objects (or maybe you don't know yet how many data objects you will add). In this situation, it is possible to add the objects later and the exchange manager will take care to inform the handler that it must wait for them.
If you are working on a request you received, it is also possible to add data objects that will sent back to the requester when you complete and exit the handler.

alp_status_t alp_exg2_request_object_add_by_fd (AlpExg2Request iRequest, int iFd, size_t iObjectSize, const char *iObjectName, const char *iObjectType, const char *iObjectDscr)

Add a data object by file descriptor.

alp_status_t alp_exg2_request_object_add_by_file (AlpExg2Request iRequest, const char *iObjectFile, int iDeleteWhenDone, const char *iObjectName, const char *iObjectType, const char *iObjectDscr)

Add a data object by file.

alp_status_t alp_exg2_request_object_add_by_ptr (AlpExg2Request iRequest, uint8_t *iObjectP, size_t iObjectSize, int iFreeWhenDone, const char *iObjectName, const char *iObjectType, const char *iObjectDscr)

Add a data object by memory pointer.

alp_status_t alp_exg2_request_object_add_undefined (AlpExg2Request iRequest, uint32_t *oObjectId)

Add a data object for which you don't have the data yet.

alp_status_t alp_exg2_request_object_define_by_fd (AlpExg2Request iRequest, uint32_t iObjectId, int iFd, size_t iObjectSize, const char *iObjectName, const char *iObjectType, const char *iObjectDscr)

Define an object by file descriptor.

alp_status_t alp_exg2_request_object_define_by_file (AlpExg2Request iRequest, uint32_t iObjectId, const char *iObjectFile, int iDeleteWhenDone, const char *iObjectName, const char *iObjectType, const char *iObjectDscr)

Define an object by file.

alp_status_t alp_exg2_request_object_define_by_ptr (AlpExg2Request iRequest, uint32_t iObjectId, uint8_t *iObjectP, size_t iObjectSize, int iFreeWhenDone, const char *iObjectName, const char *iObjectType, const char *iObjectDscr)

Define an object by memory pointer.

alp_status_t alp_exg2_request_object_set_count_final (AlpExg2Request iRequest)

Tell the request you have added all objects.

alp_status_t alp_exg2_request_object_set_count_undefined (AlpExg2Request iRequest)

Tell the request more objects will be added later.

Selecting a transport

There is no usage for these functions at the moment. In a future version, it may be possible to execute requests on remote devices.

alp_status_t alp_exg2_transport_get (AlpExg2Request iRequest, char **oParamsValue)

Get the transport params from the request.

alp_status_t alp_exg2_transport_get_const (AlpExg2Request iRequest, const char **oParamsValue)

Get the transport params from the request (const).

alp_status_t alp_exg2_transport_set (AlpExg2Request iRequest, const char *iParamsValue)

Setup to execute the request on a remote device.

Generated on Wed Jul 30 07:06:40 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation