Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals

exgmgrutils.h File Reference


Detailed Description

Public headers for Exchange Manager utilities.

#include <linux/types.h>
#include <hiker/types.h>
#include <hiker/exgmgr.h>

Go to the source code of this file.

Creating a 'store' request that also works through IrOBEX or BtOBEX

Requests that are just used to send data are special because they must also work when destined to a non ALP device through Irda or Bluetooth. In theses cases, the transport will automatically convert the request to OBEX objects and use an OBEX transport to deliver the data to the destination. To create this special request, you must use the set of functions below.

alp_status_t alp_exg_utils_store_request_create (AlpExgRequest *oRequest)
 Create a request to send objects using OBEX.
alp_status_t alp_exg_utils_store_request_set_data_fd (AlpExgRequest iRequest, int iFd, char *iMIMEType, char *iDescription, char *iName)
 add an object by file descriptor
alp_status_t alp_exg_utils_store_request_add_object (AlpExgRequest iRequest, char *iFilename, char *iMIMEType, char *iDescription, char *iName)
 add an object by filename

Handling 'store' requests

ALP exchange manager can receive data from both ALP and non ALP devices. In order for an application to receive such data objects, one must register a handler for the verb ALP_EXGMGR_STORE_OBJECT_VERB and the data type he is interested in. In the handler, he must then use the set of functions below to extract the data objects.

alp_status_t alp_exg_utils_is_store_request (AlpExgRequest iRequest, int *oIsStoreRequest)
 Check if a request is a 'store' request.
alp_status_t alp_exg_utils_store_request_get_object_count (AlpExgRequest iRequest, int *oObjectCount)
 Get the number of objects received.
alp_status_t alp_exg_utils_store_request_get_data_fd (AlpExgRequest iRequest, int *oFd, char *oMIMEType, size_t iMIMETypeBufLen, char *oDescription, size_t iDescriptionBufLen, char *oName, size_t iNameBufLen)
 Get the object data file descriptor <DEPRECATED, use alp_exg_utils_store_request_get_object_fd()>.
alp_status_t alp_exg_utils_store_request_get_object (AlpExgRequest iRequest, int iObjectNum, char *oFilename, size_t iFilenameBufLen, char *oMIMEType, size_t iMIMETypeBufLen, char *oDescription, size_t iDescriptionBufLen, char *oName, size_t iNameBufLen)
 Get info about one of the received objects.
alp_status_t alp_exg_utils_store_request_get_object_fd (AlpExgRequest iRequest, int iObjectNum, int *oFd, char *oMIMEType, size_t iMIMETypeBufLen, char *oDescription, size_t iDescriptionBufLen, char *oName, size_t iNameBufLen)
 Get info about one of the received objects with data from file descriptor.
alp_status_t alp_exg_utils_send_method_select (AlpExgRequest iRequest, char *iMIMEType)
 Select a send method.


Function Documentation

alp_status_t alp_exg_utils_is_store_request AlpExgRequest  iRequest,
int *  oIsStoreRequest
 

Check if a request is a 'store' request.

Use this function to determine whether the request you have received is a 'store' request. You may need to check that in case you register the same handler for multiple verbs.

Parameters:
[in] iRequest pointer to an AlpExgRequest variable that will receive the created request reference.
[in] oIsStoreRequest a pointer to an int. Upon return, the int value will be 1 if iRequest is a 'store' request.
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_send_method_select AlpExgRequest  iRequest,
char *  iMIMEType
 

Select a send method.

Sending data can be done through Bluetooth, Irda, or any other local application as an attachment. This function implements a dialog UI that merges all the possible methods for a given type and automatically sets the verb, data type and transport of the request so that it will reach the right handler.

Parameters:
[in] iRequest pointer to an AlpExgRequest that you have just created
[in] iMIMEType the mime type of the data you want to send.
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_store_request_add_object AlpExgRequest  iRequest,
char *  iFilename,
char *  iMIMEType,
char *  iDescription,
char *  iName
 

add an object by filename

Use this function when you want to send one or several objects. Each object must be stored in its own file. If you elect to use this function you cannot use alp_exg_utils_store_request_set_data_fd().

Parameters:
[in] iRequest pointer to an AlpExgRequest variable that will receive the created request reference.
[in] iFd the data file descriptor (belongs to the request when this function returns no error).
[in] iFilename the name of the file containing the object (mandatory)
[in] iMIMEType the data type (mandatory, e.g. "text/x-vcard")
[in] iDescription description that will be passed through Obex (optional, pass NULL if no description)
[in] iName an object name that will be passed through OBEX (mandatory). This name should end with an extension equivalent to the MIMEType (e.g. ".vcf").
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_store_request_create AlpExgRequest oRequest  ) 
 

Create a request to send objects using OBEX.

This function creates a new request and sets the right verb to let the exchange transport know you want to send objects using OBEX. This lets you send one or more objects to any device which understands OBEX. Note that upon return, the request verb will have been set (don't set it yourself).

Parameters:
[out] oRequest pointer to an AlpExgRequest variable that will receive the created request reference.
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_store_request_get_data_fd AlpExgRequest  iRequest,
int *  oFd,
char *  oMIMEType,
size_t  iMIMETypeBufLen,
char *  oDescription,
size_t  iDescriptionBufLen,
char *  oName,
size_t  iNameBufLen
 

Get the object data file descriptor <DEPRECATED, use alp_exg_utils_store_request_get_object_fd()>.

If there is only a single object in the request, it may have been passed by file descriptor. Call this function to check and possibly retrieve the fd. Once you have got the fd, it belongs to you and you are responsible to close it when you are finished with it. If the fd returned is -1, then use alp_exg_utils_store_request_get_object() to retrieve the object filename.

Parameters:
[in] iRequest pointer to an AlpExgRequest variable that will receive the created request reference.
[in] oFd a pointer to an int. Upon return, it will contain the fd or -1 if there is no fd available.
[in] oMIMEType a pointer to a buffer where to store the data type (can be NULL if you don't want this info)
[in] iMIMETypeBufLen the size of the buffer
[in] oDescription a pointer to a buffer where to store the description (can be NULL if you don't want this info)
[in] iDescriptionBufLen the size of the buffer
[in] oName a pointer to a buffer where to store the name (can be NULL if you don't want this info)
[in] iNameBufLen the size of the buffer
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_store_request_get_object AlpExgRequest  iRequest,
int  iObjectNum,
char *  oFilename,
size_t  iFilenameBufLen,
char *  oMIMEType,
size_t  iMIMETypeBufLen,
char *  oDescription,
size_t  iDescriptionBufLen,
char *  oName,
size_t  iNameBufLen
 

Get info about one of the received objects.

The file you get is yours. You are responsible to either move it to your private storage, or delete it when done.

Parameters:
[in] iRequest pointer to an AlpExgRequest variable that will receive the created request reference.
[in] oFilename a pointer to a buffer where to store the filename (can be NULL if you don't want this info)
[in] iFilenameBufLen the size of the buffer
[in] oMIMEType a pointer to a buffer where to store the data type (can be NULL if you don't want this info)
[in] iMIMETypeBufLen the size of the buffer
[in] oDescription a pointer to a buffer where to store the description (can be NULL if you don't want this info)
[in] iDescriptionBufLen the size of the buffer
[in] oName a pointer to a buffer where to store the name (can be NULL if you don't want this info)
[in] iNameBufLen the size of the buffer
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_store_request_get_object_count AlpExgRequest  iRequest,
int *  oObjectCount
 

Get the number of objects received.

Use this function to determine how many objects you have received.

Parameters:
[in] iRequest pointer to an AlpExgRequest variable that will receive the created request reference.
[in] oObjectCount a pointer to an int. Upon return, the int value will be the number of objects received.
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_store_request_get_object_fd AlpExgRequest  iRequest,
int  iObjectNum,
int *  oFd,
char *  oMIMEType,
size_t  iMIMETypeBufLen,
char *  oDescription,
size_t  iDescriptionBufLen,
char *  oName,
size_t  iNameBufLen
 

Get info about one of the received objects with data from file descriptor.

The fd you get is yours. You are responsible to close it when done.

Parameters:
[in] iRequest pointer to an AlpExgRequest variable that will receive the created request reference.
[in] oFd a pointer to an int. Upon return, it will contain an fd to the data. Close it when you have read the data.
[in] oMIMEType a pointer to a buffer where to store the data type (can be NULL if you don't want this info)
[in] iMIMETypeBufLen the size of the buffer
[in] oDescription a pointer to a buffer where to store the description (can be NULL if you don't want this info)
[in] iDescriptionBufLen the size of the buffer
[in] oName a pointer to a buffer where to store the name (can be NULL if you don't want this info)
[in] iNameBufLen the size of the buffer
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success

alp_status_t alp_exg_utils_store_request_set_data_fd AlpExgRequest  iRequest,
int  iFd,
char *  iMIMEType,
char *  iDescription,
char *  iName
 

add an object by file descriptor

Use this function when you want to send only a single object and specify a file descriptor. If you elect to use this function you cannot use alp_exg_utils_store_request_add_object(). Note that the fd belongs to the request if the function returns no error. It will be closed when the request is destroyed.

Parameters:
[in] iRequest pointer to an AlpExgRequest variable that will receive the created request reference.
[in] iFd the data file descriptor (belongs to the request when this function returns no error).
[in] iMIMEType the data type (mandatory, e.g. "text/x-vcard")
[in] iDescription description that will be passed through Obex (optional, pass NULL if no description)
[in] iName an object name that will be passed through OBEX (mandatory). This name should end with an extension equivalent to the MIMEType (e.g. ".vcf").
Returns:
ALP_EXGMGR_ERR_NO_ERROR - success


Generated on Sat Dec 16 20:29:48 2006 for hiker-0.9 by  doxygen 1.4.4