gw-obex.h File Reference

#include <glib.h>
#include <openobex/obex.h>

Go to the source code of this file.

Defines
#define	GW_OBEX_UNKNOWN_LENGTH   -1
#define	OBEX_FTP_UUID   "\xF9\xEC\x7B\xC4\x95\x3C\x11\xD2\x98\x4E\x52\x54\x00\xDC\x9E\x09"
#define	OBEX_FTP_UUID_LEN   16
#define	OBEX_PBAP_UUID   "\x79\x61\x35\xF0\xF0\xC5\x11\xD8\x09\x66\x08\x00\x20\x0C\x9A\x66"
#define	OBEX_PBAP_UUID_LEN   16
#define	OBEX_SYNC_UUID   "IRMC-SYNC"
#define	OBEX_SYNC_UUID_LEN   9
GW OBEX Error Codes
The error codes returned by many of the functions refer either to an OBEX Protocol error or to a GW OBEX error. If the error code is less that 256, it refers to an OBEX error, othervice it refers to a GW_OBEX_ERROR_* error.
#define	GW_OBEX_ERROR_DISCONNECT   256
#define	GW_OBEX_ERROR_ABORT   257
#define	GW_OBEX_ERROR_INTERNAL   258
#define	GW_OBEX_ERROR_NO_SERVICE   259
#define	GW_OBEX_ERROR_CONNECT_FAILED   260
#define	GW_OBEX_ERROR_TIMEOUT   261
#define	GW_OBEX_ERROR_INVALID_DATA   262
#define	GW_OBEX_ERROR_INVALID_PARAMS   263
#define	GW_OBEX_ERROR_LOCAL_ACCESS   264
#define	GW_OBEX_ERROR_BUSY   265
#define	GW_OBEX_ERROR_NO_DATA   266
Typedefs
typedef struct gw_obex	GwObex
typedef struct gw_obex_xfer	GwObexXfer
typedef void(*	gw_obex_xfer_cb_t )(GwObexXfer *xfer, gpointer data)
typedef void(*	gw_obex_disconnect_cb_t )(GwObex *ctx, gpointer data)
typedef void(*	gw_obex_progress_cb_t )(GwObex *ctx, gint obex_cmd, gint current, gint target, gpointer data)
typedef gboolean(*	gw_obex_cancel_cb_t )(gpointer data)
Functions
Functions for connecting and disconnecting
With these functions you can create and and disconnect connections. You can either connect using a filename (e.g. "/dev/rfcomm0") or using a file descriptor (e.g. a RFCOMM socket).
GwObex *	gw_obex_setup_dev (const gchar *device, const gchar *uuid, gint uuid_len, GMainContext *context, gint *error)
GwObex *	gw_obex_setup_fd (int fd, const gchar *uuid, gint uuid_len, GMainContext *context, gint *error)
void	gw_obex_close (GwObex *ctx)
Registering callback functions
With these functions you can register your own callback functions to gwobex to receive indications about special events.
void	gw_obex_set_disconnect_callback (GwObex *ctx, gw_obex_disconnect_cb_t callback, gpointer data)
void	gw_obex_set_progress_callback (GwObex *ctx, gw_obex_progress_cb_t callback, gpointer data)
void	gw_obex_set_cancel_callback (GwObex *ctx, gw_obex_cancel_cb_t callback, gpointer data)
Functions for performing synchronous remote operations
Once you have setup a connection using one of the gw_obex_setup_* functions, you can perform different remote transactions using these functions.
gboolean	gw_obex_get_capability (GwObex *ctx, gchar **cap, gint *cap_len, gint *error)
gboolean	gw_obex_get_file (GwObex *ctx, const gchar *local, const gchar *remote, const gchar *type, gint *error)
gboolean	gw_obex_put_file (GwObex *ctx, const gchar *local, const gchar *remote, const gchar *type, gint *error)
gboolean	gw_obex_get_fd (GwObex *ctx, gint fd, const gchar *remote, const gchar *type, gint *error)
gboolean	gw_obex_put_fd (GwObex *ctx, gint fd, const gchar *remote, const gchar *type, gint *error)
gboolean	gw_obex_get_buf (GwObex *ctx, const gchar *remote, const gchar *type, gchar **buf, gint *buf_size, gint *error)
gboolean	gw_obex_put_buf (GwObex *ctx, const gchar *remote, const gchar *type, const gchar *buf, gint buf_size, gint time, gint *error)
gboolean	gw_obex_get_buf_with_apparam (GwObex *ctx, const gchar *remote, const gchar *type, const guint8 *apparam, gint apparam_size, gchar **buf, gint *buf_size, gint *error)
gboolean	gw_obex_put_buf_with_apparam (GwObex *ctx, const gchar *remote, const gchar *type, const guint8 *apparam, gint apparam_size, const gchar *buf, gint buf_size, gint time, gint *error)
gboolean	gw_obex_chdir (GwObex *ctx, const gchar *dir, gint *error)
gboolean	gw_obex_mkdir (GwObex *ctx, const gchar *dir, gint *error)
gboolean	gw_obex_read_dir (GwObex *ctx, const gchar *dir, gchar **buf, gint *buf_size, gint *error)
gboolean	gw_obex_delete (GwObex *ctx, const gchar *name, gint *error)
gboolean	gw_obex_move (GwObex *ctx, const gchar *src, const gchar *dst, gint *error)
gboolean	gw_obex_copy (GwObex *ctx, const gchar *src, const gchar *dst, gint *error)
Functions for performing transfers in an asynchronous manner
With these functions you can do transfers in smaller steps. The steps are split up in a open, read/write, close manner.
GwObexXfer *	gw_obex_put_async (GwObex *ctx, const char *name, const char *type, gint size, time_t time, gint *error)
GwObexXfer *	gw_obex_get_async (GwObex *ctx, const char *name, const char *type, gint *error)
GwObexXfer *	gw_obex_get_async_with_apparam (GwObex *ctx, const char *name, const char *type, const guint8 *apparam, gint apparam_size, gint *error)
void	gw_obex_xfer_set_callback (GwObexXfer *xfer, gw_obex_xfer_cb_t cb, gpointer user_data)
time_t	gw_obex_xfer_object_time (GwObexXfer *xfer)
gint	gw_obex_xfer_object_size (GwObexXfer *xfer)
unsigned char *	gw_obex_xfer_object_apparam (GwObexXfer *xfer, size_t *apparam_size)
gboolean	gw_obex_xfer_object_done (GwObexXfer *xfer)
gboolean	gw_obex_xfer_write (GwObexXfer *xfer, const char *buf, gint buf_size, gint *bytes_written, gint *error)
gboolean	gw_obex_xfer_read (GwObexXfer *xfer, char *buf, gint buf_size, gint *bytes_read, gint *error)
gboolean	gw_obex_xfer_flush (GwObexXfer *xfer, gint *error)
gboolean	gw_obex_xfer_close (GwObexXfer *xfer, gint *error)
gboolean	gw_obex_xfer_abort (GwObexXfer *xfer, gint *error)
void	gw_obex_xfer_free (struct gw_obex_xfer *xfer)
void	gw_obex_xfer_set_blocking (GwObexXfer *xfer, gboolean block)

---

Detailed Description

OSSO GW OBEX Connectivity Library and API

Author:

Johan Hedberg <[email protected]>

Copyright (C) 2004-2005 Nokia Corporation. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License, version 2.1, as published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

---

Define Documentation

#define GW_OBEX_ERROR_ABORT   257

Operation was aborted

#define GW_OBEX_ERROR_BUSY   265

Another operation is in progress

#define GW_OBEX_ERROR_CONNECT_FAILED   260

Unable to create connection

#define GW_OBEX_ERROR_DISCONNECT   256

Transport connection was disconnected

#define GW_OBEX_ERROR_INTERNAL   258

GW OBEX internal error

#define GW_OBEX_ERROR_INVALID_DATA   262

Remote device returned invalid/corrupted data

#define GW_OBEX_ERROR_INVALID_PARAMS   263

Invalid parameters given to gwobex

#define GW_OBEX_ERROR_LOCAL_ACCESS   264

Local access error (e.g. read/write/open failed for local file)

#define GW_OBEX_ERROR_NO_DATA   266

No data currently available

#define GW_OBEX_ERROR_NO_SERVICE   259

Unable to connecto to the specified service (UUID)

#define GW_OBEX_ERROR_TIMEOUT   261

Timeout while waiting for data from the remote device

#define GW_OBEX_UNKNOWN_LENGTH   -1

Value used if target length for put or get is not known

#define OBEX_FTP_UUID   "\xF9\xEC\x7B\xC4\x95\x3C\x11\xD2\x98\x4E\x52\x54\x00\xDC\x9E\x09"

Standard folder browsing service UUID (give this as a parameter to gw_obex_setup_* to connect to folder browsing service

#define OBEX_FTP_UUID_LEN   16

Length of OBEX_FTP_UUID

#define OBEX_PBAP_UUID   "\x79\x61\x35\xF0\xF0\xC5\x11\xD8\x09\x66\x08\x00\x20\x0C\x9A\x66"

Phone Book Access Profile UUID

#define OBEX_PBAP_UUID_LEN   16

Length of OBEX_PBAP_UUID

#define OBEX_SYNC_UUID   "IRMC-SYNC"

IrMC Sync Profile UUID

#define OBEX_SYNC_UUID_LEN   9

Length of OBEX_SYNC_UUID

---

Typedef Documentation

typedef gboolean(* gw_obex_cancel_cb_t)(gpointer data)

Callback type for checking if the operation should be canceled. Only used for the synchronous functions. In the GNOME VFS case the callback function should be gnome_vfs_cancellation_check().

Parameters:

data

Optional pointer to user data

Returns:

TRUE if the operation should be canceled, FALSE othervice

typedef void(* gw_obex_disconnect_cb_t)(GwObex *ctx, gpointer data)

Callback type for transport connection loss

Parameters:

	ctx	GwObex pointer for the connection
	data	Optional pointer to user data

typedef void(* gw_obex_progress_cb_t)(GwObex *ctx, gint obex_cmd, gint current, gint target, gpointer data)

Callback type for progress information Only used for the synchronous transfer functions.

Parameters:

	ctx	GwObex pointer for the connection
	obex_cmd	eg. OBEX_CMD_PUT
	current	Bytes transfered
	target	Total length (or GW_OBEX_UNKNOWN_LENGTH)
	data	Optional pointer to user data

typedef void(* gw_obex_xfer_cb_t)(GwObexXfer *xfer, gpointer data)

Callback type for ongoing transfers

Parameters:

	ctx	GwObexXfer pointer for the transfer
	data	Optional pointer to user data

typedef struct gw_obex GwObex

Struct containing the context of a gwobex connection

typedef struct gw_obex_xfer GwObexXfer

Objecct transfer handle

---

Function Documentation

gboolean gw_obex_chdir	(	GwObex *	ctx,
		const gchar *	dir,
		gint *	error
	)

Change directory (relative to the current one).

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	dir	New directory to change to (null terminated UTF-8), ".." to go up, NULL to go to the root folder
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

void gw_obex_close

(

GwObex *

ctx

)

Close GW OBEX connection and free all memory associated with it.

Parameters:

ctx

Pointer returned by gw_obex_setup(). Cannot be used anymore after this calling this function.

gboolean gw_obex_copy	(	GwObex *	ctx,
		const gchar *	src,
		const gchar *	dst,
		gint *	error
	)

Copy a file on the remote device.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	src	Source filename (null terminated UTF-8)
	dst	Destination filename (null terminated UTF-8)
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_delete	(	GwObex *	ctx,
		const gchar *	name,
		gint *	error
	)

Remove a file from the remote device.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	name	Filename to remove (null terminated UTF-8)
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

GwObexXfer* gw_obex_get_async	(	GwObex *	ctx,
		const char *	name,
		const char *	type,
		gint *	error
	)

Start a GET operation asynchronously

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	name	Name of the object (null terminated UTF-8)
	type	Type of the object (null terminated UTF-8), or NULL
	error	Place to store error code on failure (NULL if not interested)

Returns:

a new GwObexXfer object on success, NULL on failure

GwObexXfer* gw_obex_get_async_with_apparam	(	GwObex *	ctx,
		const char *	name,
		const char *	type,
		const guint8 *	apparam,
		gint	apparam_size,
		gint *	error
	)

Start a GET operation asynchronously with application parameters

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	name	Name of the object (null terminated UTF-8)
	type	Type of the object (null terminated UTF-8), or NULL
	apparam	Application parameters of the object
	apparam_size	Application paramters' size
	error	Place to store error code on failure (NULL if not interested)

Returns:

a new GwObexXfer object on success, NULL on failure

gboolean gw_obex_get_buf	(	GwObex *	ctx,
		const gchar *	remote,
		const gchar *	type,
		gchar **	buf,
		gint *	buf_size,
		gint *	error
	)

Get an object from the remote device and store it in a memory buffer. Either remote filename or type must be supplied (or both).

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	buf	Buffer to store the object in. g_free() when not needed anymore.
	buf_size	Place to store length of fetched object
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_get_buf_with_apparam	(	GwObex *	ctx,
		const gchar *	remote,
		const gchar *	type,
		const guint8 *	apparam,
		gint	apparam_size,
		gchar **	buf,
		gint *	buf_size,
		gint *	error
	)

Get an object from the remote device and store it in a memory buffer. Either remote filename or type must be supplied (or both).

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	apparam	Application parameters of the object
	apparam_size	Application parameters size
	buf	Buffer to store the object in. g_free() when not needed anymore.
	buf_size	Place to store length of fetched object
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_get_capability	(	GwObex *	ctx,
		gchar **	cap,
		gint *	cap_len,
		gint *	error
	)

Get the capability object from the connected remote device.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	cap	Place to store the fetched object. g_free() when not needed anymore.
	cap_len	Place to store the size of the fetched object
	error	Place to store a possible error code (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_get_fd	(	GwObex *	ctx,
		gint	fd,
		const gchar *	remote,
		const gchar *	type,
		gint *	error
	)

Get a file from the remote device and write it to a file descriptor

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	fd	File descriptor to write the file into
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_get_file	(	GwObex *	ctx,
		const gchar *	local,
		const gchar *	remote,
		const gchar *	type,
		gint *	error
	)

Get a file from the remote device.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	local	Local filename (null terminated UTF-8)
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_mkdir	(	GwObex *	ctx,
		const gchar *	dir,
		gint *	error
	)

Create a new directory.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	dir	Directory to create (null terminated UTF-8)
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_move	(	GwObex *	ctx,
		const gchar *	src,
		const gchar *	dst,
		gint *	error
	)

Move/Rename a file on the remote device.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	src	Source filename (null terminated UTF-8)
	dst	Destination filename (null terminated UTF-8)
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

GwObexXfer* gw_obex_put_async	(	GwObex *	ctx,
		const char *	name,
		const char *	type,
		gint	size,
		time_t	time,
		gint *	error
	)

Start a PUT operation asynchronously

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	name	Name of the object (null terminated UTF-8)
	type	Type of the object (null terminated UTF-8), or NULL
	size	Size of the object (GW_OBEX_UNKNOWN_LENGTH if not known)
	time	Last modification time of the object (-1 if not known)
	error	Place to store error code on failure (NULL if not interested)

Returns:

a new GwObexXfer object on success, NULL on failure

gboolean gw_obex_put_buf	(	GwObex *	ctx,
		const gchar *	remote,
		const gchar *	type,
		const gchar *	buf,
		gint	buf_size,
		gint	time,
		gint *	error
	)

Send a object located in a memory buffer to the remote device. Either remote filename or type must be supplied (or both)

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	buf	Buffer containing the object
	buf_size	Buffer (object) size
	time	Last modification time of object (or -1 if not known)
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_put_buf_with_apparam	(	GwObex *	ctx,
		const gchar *	remote,
		const gchar *	type,
		const guint8 *	apparam,
		gint	apparam_size,
		const gchar *	buf,
		gint	buf_size,
		gint	time,
		gint *	error
	)

Send a object located in a memory buffer to the remote device. Either remote filename or type must be supplied (or both)

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	apparam	Application parameters of the object
	apparam_size	Application parameters size
	buf	Buffer containing the object
	buf_size	Buffer (object) size
	time	Last modification time of object (or -1 if not known)
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_put_fd	(	GwObex *	ctx,
		gint	fd,
		const gchar *	remote,
		const gchar *	type,
		gint *	error
	)

Read data from a file descriptor and send it to the remote device

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	fd	File descriptor to read the data from
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_put_file	(	GwObex *	ctx,
		const gchar *	local,
		const gchar *	remote,
		const gchar *	type,
		gint *	error
	)

Send a file to the remote device.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	local	Local filename (null terminated UTF-8)
	remote	Remote filename (null terminated UTF-8)
	type	MIME-type of the object
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_read_dir	(	GwObex *	ctx,
		const gchar *	dir,
		gchar **	buf,
		gint *	buf_size,
		gint *	error
	)

Get folder listing for the specified directory.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	dir	Directory to list (null terminated UTF-8), NULL to list current directory
	buf	Place to store the folder-listing object
	buf_size	Place to store the size for the retrieved object
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

void gw_obex_set_cancel_callback	(	GwObex *	ctx,
		gw_obex_cancel_cb_t	callback,
		gpointer	data
	)

Set function to be called to check if the current operation should be canceled. In the GNOME VFS case the callback function should be gnome_vfs_cancellation_check(). The callback function should return TRUE if the operation should be canceled and FALSE othervice.

Only used for the synchronous transfer functions.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	callback	Function to call
	data	Pointer to pass to the callback function

void gw_obex_set_disconnect_callback	(	GwObex *	ctx,
		gw_obex_disconnect_cb_t	callback,
		gpointer	data
	)

Set function to be called when a disconnection happens. You may (and probably should) call gw_obex_close() if this function is called.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	callback	Function to call
	data	Optional data to pass to the callback function

void gw_obex_set_progress_callback	(	GwObex *	ctx,
		gw_obex_progress_cb_t	callback,
		gpointer	data
	)

Set function to be called when progress for a put or get operation happens. Only used for the synchronous transfer functions.

Parameters:

	ctx	Pointer returned by gw_obex_setup()
	callback	Function to call
	data	Optional data to pass to the callback function

GwObex* gw_obex_setup_dev	(	const gchar *	device,
		const gchar *	uuid,
		gint	uuid_len,
		GMainContext *	context,
		gint *	error
	)

Open connection using a local device node and setup parameters. This function should be called before calling any other functions. The pointer returned by this function should be passed to the other functions.

Parameters:

	device	The local device which should be opened for the connection
	uuid	UUID of service to connect to. NULL for the default service (INBOX).
	uuid_len	Length (in bytes) of UUID
	context	GMainContext to attach to (or NULL for the default one)
	error	Place to store error code on failure (NULL if not interested)

Returns:

A pointer, NULL on failure This pointer should be passed to the other obex_* functions.

GwObex* gw_obex_setup_fd	(	int	fd,
		const gchar *	uuid,
		gint	uuid_len,
		GMainContext *	context,
		gint *	error
	)

Setup OBEX connection using an opened file descriptor This function should be called before calling any other functions. The pointer returned by this function should be passed to the other functions.

Parameters:

	fd	Opened file descriptor to use for the connection
	uuid	UUID of service to connect to. NULL for the default service (INBOX).
	uuid_len	Length (in bytes) of UUID
	context	GMainContext to attach to (or NULL for the default one)
	error	Place to store error code on failure (NULL if not interested)

Returns:

A pointer, NULL on failure This pointer should be passed to the other obex_* functions.

gboolean gw_obex_xfer_abort	(	GwObexXfer *	xfer,
		gint *	error
	)

Abort an ongoing transfer

You still need to call gw_obex_xfer_free after this to free the actual memory allocated for the GwObexXfer object. xfer_close and xfer_abort are mutually exclusive (only call one of them for a transfer).

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_xfer_close	(	GwObexXfer *	xfer,
		gint *	error
	)

Close an ongoing transfer

You still need to call gw_obex_xfer_free after this to free the actual memory allocated for the GwObexXfer object.

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

gboolean gw_obex_xfer_flush	(	GwObexXfer *	xfer,
		gint *	error
	)

Force all data remaining in buffers to be sent

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

void gw_obex_xfer_free

(

struct gw_obex_xfer *

xfer

)

Free the data allocated for a GwObexXfer object

Parameters:

xfer

Pointer returned by gw_obex_put_async or gw_obex_get_async

unsigned char* gw_obex_xfer_object_apparam	(	GwObexXfer *	xfer,
		size_t *	apparam_size
	)

Get the contents of the application parameters header

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	apparam_size	Return value for the size of the application parameters header.

Returns:

The pointer to the buffer that hold the contents.

gboolean gw_obex_xfer_object_done

(

GwObexXfer *

xfer

)

Returns if a transfer is already done

Parameters:

xfer

Pointer returned by gw_obex_put_async or gw_obex_get_async

Returns:

whether the current transfer is done

gint gw_obex_xfer_object_size

(

GwObexXfer *

xfer

)

Get the size of the object being transfered

Parameters:

xfer

Pointer returned by gw_obex_put_async or gw_obex_get_async

Returns:

The size or GW_OBEX_UNKNOWN_LENGTH if it is not known.

time_t gw_obex_xfer_object_time

(

GwObexXfer *

xfer

)

Get the last modification time of the object being transfered

Parameters:

xfer

Pointer returned by gw_obex_put_async or gw_obex_get_async

Returns:

The modification time or -1 if it is not known.

gboolean gw_obex_xfer_read	(	GwObexXfer *	xfer,
		char *	buf,
		gint	buf_size,
		gint *	bytes_read,
		gint *	error
	)

Read data from a transfer

The function will report EOF by returning success with zero bytes read.

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	buf	Buffer where the data should be stored
	buf_size	Size of the buffer
	bytes_read	Return value for the number of bytes that were read
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure

void gw_obex_xfer_set_blocking	(	GwObexXfer *	xfer,
		gboolean	block
	)

Set blocking behaviour for a GwObexXfer object when calling xfer_read and xfer_write

When blocking is enabled xfer_read will return only after it has been able to read some data (i.e. GW_OBEX_ERROR_NO_DATA will not be returned). For xfer_write blocking guarantees that *some* data will be written.

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	block	TRUE to enable blocking behaviour

void gw_obex_xfer_set_callback	(	GwObexXfer *	xfer,
		gw_obex_xfer_cb_t	cb,
		gpointer	user_data
	)

Set a callback function for a GwObexXfer object The callback function will be called in the following situations:

• Data can be written (i.e. xfer_write will succeed)
• Data can be read (i.e. xfer_read will succees)
• An error ocured
• The transfer is finished

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	cb	Pointer to the callback function
	user_data	Optional user data which will be passed to the callback function

Returns:

a new GwObexXfer object on success, NULL on failure

gboolean gw_obex_xfer_write	(	GwObexXfer *	xfer,
		const char *	buf,
		gint	buf_size,
		gint *	bytes_written,
		gint *	error
	)

Supply more data to a transfer

Parameters:

	xfer	Pointer returned by gw_obex_put_async or gw_obex_get_async
	buf	Buffer containing the data
	buf_size	Size of the buffer
	bytes_written	Return value for the number of bytes that were written
	error	Place to store error code on failure (NULL if not interested)

Returns:

TRUE on success, FALSE on failure