Main Page | Directories | File List | Globals
src

gw-obex.h File Reference

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

Go to the source code of this file.

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

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_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)
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)
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)

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

Typedefs

typedef gw_obex GwObex
typedef 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)

Detailed Description

OSSO GW OBEX Connectivity Library and API

Author:
Johan Hedberg <johan.hedberg@nokia.com>
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

Typedef Documentation

typedef gboolean(* gw_obex_cancel_cb_t)(gpointer data)
 

Callback type for checking if the operation should be canceled. 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

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

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_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_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.

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.

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

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

Generated on Thu Dec 21 16:46:11 2006 for GW OBEX Library by  doxygen 1.4.2