Main Page | Directories | File List | File Members
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

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

Typedefs

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

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)
gboolean gw_obex_get_capability (GwObex *ctx, gchar **cap, gint *cap_len, gint *error)
gboolean gw_obex_get_type (GwObex *ctx, const gchar *type, gchar **buf, gint *buf_len, gint *error)
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)
gboolean gw_obex_get_file (GwObex *ctx, const gchar *local, const gchar *remote, gint *error)
gboolean gw_obex_put_file (GwObex *ctx, const gchar *local, const gchar *remote, gint *error)
gboolean gw_obex_get_fd (GwObex *ctx, gint fd, const gchar *remote, gint *error)
gboolean gw_obex_put_fd (GwObex *ctx, gint fd, const gchar *remote, 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 *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)

Detailed Description

OSSO GW OBEX Connectivity Library and API

Author:
Johan Hedberg <johan.hedberg@nokia.com>
Copyright (C) 2004-2005 Nokia Corporation

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

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

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 struct gw_obex GwObex
 

Struct containing the context of a gwobex connection

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

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,
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)
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,
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)
error Place to store error code on failure (NULL if not interested)
Returns:
TRUE on success, FALSE on failure

gboolean gw_obex_get_type (  GwObex *  ctx,
const gchar *  type,
gchar **  buf,
gint *  buf_len,
gint *  error
) 
 

Get an object identified by its type

Parameters:
ctx Pointer returned by gw_obex_setup()
type Type of the object to fetch
buf Place to store the fetched object. g_free() when not needed anymore.
buf_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_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

gboolean gw_obex_put_buf (  GwObex *  ctx,
const gchar *  remote,
const gchar *  type,
const gchar *  buf,
gint  buf_size,
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
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,
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)
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,
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)
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 filedescriptor 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 filedescriptor 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.

Generated on Wed Jan 25 10:57:08 2006 for GW OBEX Library by  doxygen 1.4.2