client.h File Reference

ObexFTP client API. More...

`#include <inttypes.h>`
`#include <sys/stat.h>`
`#include <time.h>`
`#include <openobex/obex.h>`
`#include "obexftp.h"`
`#include "object.h"`
`#include "uuid.h"`

## Data Structures

struct | stat_entry_t
struct | cache_object
struct | obexftp_client_t

## Macros

#define | OBEX_TRANS_USB 6
#define | OBEXFTP_LEADING_SLASH 0x01 /* used in get (and alike) */
#define | OBEXFTP_TRAILING_SLASH 0x02 /* used in list */
#define | OBEXFTP_SPLIT_SETPATH 0x04 /* some phones dont have a cwd */
#define | OBEXFTP_CONN_HEADER 0x08 /* do we even need this? */
#define | OBEXFTP_USE_LEADING_SLASH(x)
#define | OBEXFTP_USE_TRAILING_SLASH(x)
#define | OBEXFTP_USE_SPLIT_SETPATH(x)
#define | OBEXFTP_USE_CONN_HEADER(x)
#define | DEFAULT_OBEXFTP_QUIRKS (OBEXFTP_LEADING_SLASH | OBEXFTP_TRAILING_SLASH | OBEXFTP_SPLIT_SETPATH | OBEXFTP_CONN_HEADER)
#define | DEFAULT_CACHE_TIMEOUT 180 /* 3 minutes */
#define | DEFAULT_CACHE_MAXSIZE 10240 /* 10k */
#define | obexftp_connect(cli, device, port)
#define | obexftp_connect_ftp(cli, device, port)
#define | obexftp_connect_push(cli, device, port)
#define | obexftp_connect_sync(cli, device, port)
#define | obexftp_chpath(cli, name)
#define | obexftp_mkpath(cli, name)
#define | obexftp_cdup(cli)
#define | obexftp_cdtop(cli)
#define | obexftp_get(cli, localname, remotename)
#define | obexftp_list(cli, localname, remotename)
#define | obexftp_get_capability(cli, localname, remotename)

## Typedefs

typedef struct cache_object | cache_object_t

## Functions

obexftp_client_t * | obexftp_open (int transport, obex_ctrans_t *ctrans, obexftp_info_cb_t infocb, void *infocb_data)
| Create an obexftp client.
void | obexftp_close (obexftp_client_t *cli)
| Close an obexftp client and free the resources.
int | obexftp_connect_uuid (obexftp_client_t *cli, const char *device, int port, const uint8_t uuid[], uint32_t uuid_len)
| Do simple connect as client.
int | obexftp_connect_src (obexftp_client_t *cli, const char *src, const char *device, int port, const uint8_t uuid[], uint32_t uuid_len)
| Connect this ObexFTP client using a given source address by sending an OBEX CONNECT request.
int | obexftp_connect_service (obexftp_client_t *cli, const char *src, const char *device, int port, int service)
int | obexftp_disconnect (obexftp_client_t *cli)
| Disconnect this ObexFTP client by sending an OBEX DISCONNECT request.
int | obexftp_setpath (obexftp_client_t *cli, const char *name, int create)
| Send OBEX SETPATH request (multiple requests if split path flag is set).
int | obexftp_get_type (obexftp_client_t *cli, const char *type, const char *localname, const char *remotename)
| Send an OBEX GET with optional TYPE.
int | obexftp_put_file (obexftp_client_t *cli, const char *filename, const char *remotename)
| Send an OBEX PUT, optionally with (some) SETPATHs for a local file.
int | obexftp_put_data (obexftp_client_t *cli, const uint8_t *data, int size, const char *remotename)
| Send memory data by OBEX PUT, optionally with (some) SETPATHs.
int | obexftp_del (obexftp_client_t *cli, const char *name)
| Send an OBEX PUT with empty file name (delete).
int | obexftp_info (obexftp_client_t *cli, uint8_t opcode)
| Send a custom Siemens OBEX app info opcode.
int | obexftp_rename (obexftp_client_t *cli, const char *sourcename, const char *targetname)
| Send an custom Siemens OBEX rename request.
void * | obexftp_opendir (obexftp_client_t *cli, const char *name)
| Prepare a directory for reading.
int | obexftp_closedir (void *dir)
| Close a directory after reading.
stat_entry_t * | obexftp_readdir (void *dir)
| Read the next entry from an open directory.
stat_entry_t * | obexftp_stat (obexftp_client_t *cli, const char *name)
| Stat a directory entry.

## Detailed Description

ObexFTP client API.

ObexFTP library - language bindings for OBEX file transfer.

Copyright (c) 2002-2007 Christian W. Zuckschwerdt zany@.nosp@m.triq.nosp@m..net

ObexFTP 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 program 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 ObexFTP. If not, see http://www.gnu.org/.

## Macro Definition Documentation

## DEFAULT_CACHE_MAXSIZE

#define DEFAULT_CACHE_MAXSIZE 10240 /* 10k */

## DEFAULT_CACHE_TIMEOUT

#define DEFAULT_CACHE_TIMEOUT 180 /* 3 minutes */

## DEFAULT_OBEXFTP_QUIRKS

#define DEFAULT_OBEXFTP_QUIRKS (OBEXFTP_LEADING_SLASH | OBEXFTP_TRAILING_SLASH | OBEXFTP_SPLIT_SETPATH | OBEXFTP_CONN_HEADER)

## OBEX_TRANS_USB

#define OBEX_TRANS_USB 6

## obexftp_cdtop

#define obexftp_cdtop | ( |  | cli | ) |

Value:
obexftp_setpath(cli, "", 0)
obexftp_setpath
int obexftp_setpath(obexftp_client_t *cli, const char *name, int create)
Send OBEX SETPATH request (multiple requests if split path flag is set).
Definition client.c:1006

## obexftp_cdup

#define obexftp_cdup | ( |  | cli | ) |

Value:
obexftp_setpath(cli, NULL, 0)

## obexftp_chpath

#define obexftp_chpath | ( |  | cli,
|  |  | name )

Value:
obexftp_setpath(cli, name, 0)

## OBEXFTP_CONN_HEADER

#define OBEXFTP_CONN_HEADER 0x08 /* do we even need this? */

## obexftp_connect

#define obexftp_connect | ( |  | cli,
|  |  | device,
|  |  | port )

Value:
obexftp_connect_uuid(cli, device, port, UUID_FBS, sizeof(UUID_FBS))
obexftp_connect_uuid
int obexftp_connect_uuid(obexftp_client_t *cli, const char *device, int port, const uint8_t uuid[], uint32_t uuid_len)
Do simple connect as client.
Definition client.c:557
UUID_FBS
#define UUID_FBS
Definition uuid.h:21

## obexftp_connect_ftp

#define obexftp_connect_ftp | ( |  | cli,
|  |  | device,
|  |  | port )

Value:
obexftp_connect_uuid(cli, device, port, UUID_FBS, sizeof(UUID_FBS))

## obexftp_connect_push

#define obexftp_connect_push | ( |  | cli,
|  |  | device,
|  |  | port )

Value:
obexftp_connect_uuid(cli, device, port, NULL, 0)

## obexftp_connect_sync

#define obexftp_connect_sync | ( |  | cli,
|  |  | device,
|  |  | port )

Value:
obexftp_connect_uuid(cli, device, port, UUID_IRMC, sizeof(UUID_IRMC))
UUID_IRMC
#define UUID_IRMC
Definition uuid.h:41

## obexftp_get

#define obexftp_get | ( |  | cli,
|  |  | localname,
|  |  | remotename )

Value:
obexftp_get_type(cli, NULL, localname, remotename)
obexftp_get_type
int obexftp_get_type(obexftp_client_t *cli, const char *type, const char *localname, const char *remotename)
Send an OBEX GET with optional TYPE.
Definition client.c:855

## obexftp_get_capability

#define obexftp_get_capability | ( |  | cli,
|  |  | localname,
|  |  | remotename )

Value:
obexftp_get_type(cli, XOBEX_CAPABILITY, localname, remotename)

## OBEXFTP_LEADING_SLASH

#define OBEXFTP_LEADING_SLASH 0x01 /* used in get (and alike) */

## obexftp_list

#define obexftp_list | ( |  | cli,
|  |  | localname,
|  |  | remotename )

Value:
obexftp_get_type(cli, XOBEX_LISTING, localname, remotename)

## obexftp_mkpath

#define obexftp_mkpath | ( |  | cli,
|  |  | name )

Value:
obexftp_setpath(cli, name, 1)

## OBEXFTP_SPLIT_SETPATH

#define OBEXFTP_SPLIT_SETPATH 0x04 /* some phones dont have a cwd */

## OBEXFTP_TRAILING_SLASH

#define OBEXFTP_TRAILING_SLASH 0x02 /* used in list */

## OBEXFTP_USE_CONN_HEADER

#define OBEXFTP_USE_CONN_HEADER | ( |  | x | ) |

Value:
((x & OBEXFTP_CONN_HEADER) != 0)
OBEXFTP_CONN_HEADER
#define OBEXFTP_CONN_HEADER
Definition client.h:46

## OBEXFTP_USE_LEADING_SLASH

#define OBEXFTP_USE_LEADING_SLASH | ( |  | x | ) |

Value:
((x & OBEXFTP_LEADING_SLASH) != 0)
OBEXFTP_LEADING_SLASH
#define OBEXFTP_LEADING_SLASH
Definition client.h:43

## OBEXFTP_USE_SPLIT_SETPATH

#define OBEXFTP_USE_SPLIT_SETPATH | ( |  | x | ) |

Value:
((x & OBEXFTP_SPLIT_SETPATH) != 0)
OBEXFTP_SPLIT_SETPATH
#define OBEXFTP_SPLIT_SETPATH
Definition client.h:45

## OBEXFTP_USE_TRAILING_SLASH

#define OBEXFTP_USE_TRAILING_SLASH | ( |  | x | ) |

Value:
((x & OBEXFTP_TRAILING_SLASH) != 0)
OBEXFTP_TRAILING_SLASH
#define OBEXFTP_TRAILING_SLASH
Definition client.h:44

## Typedef Documentation

## cache_object_t

typedef struct cache_object cache_object_t

## Function Documentation

## obexftp_close()

void obexftp_close | ( | obexftp_client_t * | cli | ) |

Close an obexftp client and free the resources.

Parameters

  cli | the obexftp_client_t to be shut done and free'd. It's save to pass NULL here.

Closes the given obexftp client and frees the resources. It's recommended to set the client reference to NULL afterwards.

## obexftp_closedir()

int obexftp_closedir | ( | void * | dir | ) |

Close a directory after reading.

The stat entry is a cache object so we do nothing.

## obexftp_connect_service()

int obexftp_connect_service | ( | obexftp_client_t * | cli,
|  | const char * | src,
|  | const char * | device,
|  | int | port,
|  | int | service )

## obexftp_connect_src()

int obexftp_connect_src | ( | obexftp_client_t * | cli,
|  | const char * | src,
|  | const char * | device,
|  | int | port,
|  | const uint8_t | uuid[],
|  | uint32_t | uuid_len )

Connect this ObexFTP client using a given source address by sending an OBEX CONNECT request.

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  src | optional local source interface address (transport specific)
  device | the device address to connect to (transport specific)
  port | the port/channel for the device address
  uuid | UUID string for CONNECT (no default)
  uuid_len | length of the UUID string (excluding terminating zero)

Returns
  the result of the CONNECT request, -1 on error

Note
  Always use a UUID (except for OBEX PUSH)

## obexftp_connect_uuid()

int obexftp_connect_uuid | ( | obexftp_client_t * | cli,
|  | const char * | device,
|  | int | port,
|  | const uint8_t | uuid[],
|  | uint32_t | uuid_len )

Do simple connect as client.

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  device | the device address to connect to (transport specific)
  port | the port/channel for the device address
  uuid | UUID string for CONNECT (no default)
  uuid_len | length of the UUID string (excluding terminating zero)

Returns
  the result of the CONNECT request, -1 on error

Note
  Wrapper function for obexftp_connect_src()

Warning
  Always use a UUID (except for OBEX PUSH)

## obexftp_del()

int obexftp_del | ( | obexftp_client_t * | cli,
|  | const char * | name )

Send an OBEX PUT with empty file name (delete).

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  name | the remote filename/foldername to be removed.

Returns
  the result of the empty OBEX PUT request

## obexftp_disconnect()

int obexftp_disconnect | ( | obexftp_client_t * | cli | ) |

Disconnect this ObexFTP client by sending an OBEX DISCONNECT request.

Parameters

  cli | an obexftp_client_t created by obexftp_open().

Returns
  the result of the DISCONNECT request

## obexftp_get_type()

int obexftp_get_type | ( | obexftp_client_t * | cli,
|  | const char * | type,
|  | const char * | localname,
|  | const char * | remotename )

Send an OBEX GET with optional TYPE.

Directories will be changed into first if split path quirk is set.

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  type | OBEX TYPE of the request
  localname | optional file to write
  remotename | OBEX NAME to request

Returns
  the result of GET request

Note
  localname and remotename may be null.

## obexftp_info()

int obexftp_info | ( | obexftp_client_t * | cli,
|  | uint8_t | opcode )

Send a custom Siemens OBEX app info opcode.

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  opcode | the info opcode, 0x01 to inquire installed memory, 0x02 to get free memory

Returns
  the result of the app info request

## obexftp_open()

obexftp_client_t * obexftp_open | ( | int | transport,
|  | obex_ctrans_t * | ctrans,
|  | obexftp_info_cb_t | infocb,
|  | void * | infocb_data )

Create an obexftp client.

Parameters

  transport | the transport type that will be used
  ctrans | optional custom transport (don't use)
  infocb | optional info callback
  infocb_data | optional info callback data

Returns
  a new allocated ObexFTP client instance, NULL on error

## obexftp_opendir()

void * obexftp_opendir | ( | obexftp_client_t * | cli,
|  | const char * | name )

Prepare a directory for reading.

## obexftp_put_data()

int obexftp_put_data | ( | obexftp_client_t * | cli,
|  | const uint8_t * | data,
|  | int | size,
|  | const char * | remotename )

Send memory data by OBEX PUT, optionally with (some) SETPATHs.

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  data | data to send
  size | length of the data
  remotename | remote name to write

Returns
  the result of the OBEX PUT (and SETPATH) request(s).

Note
  A remotename must be given always.

## obexftp_put_file()

int obexftp_put_file | ( | obexftp_client_t * | cli,
|  | const char * | filename,
|  | const char * | remotename )

Send an OBEX PUT, optionally with (some) SETPATHs for a local file.

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  filename | local file to send
  remotename | remote name to write

Returns
  the result of the OBEX PUT (and SETPATH) request(s).

Note
  Puts to filename's basename if remotename is NULL or ends with a slash.

## obexftp_readdir()

stat_entry_t * obexftp_readdir | ( | void * | dir | ) |

Read the next entry from an open directory.

## obexftp_rename()

int obexftp_rename | ( | obexftp_client_t * | cli,
|  | const char * | sourcename,
|  | const char * | targetname )

Send an custom Siemens OBEX rename request.

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  sourcename | remote filename to be renamed
  targetname | remote target filename

Returns
  the result of Siemens rename request

## obexftp_setpath()

int obexftp_setpath | ( | obexftp_client_t * | cli,
|  | const char * | name,
|  | int | create )

Send OBEX SETPATH request (multiple requests if split path flag is set).

Parameters

  cli | an obexftp_client_t created by obexftp_open().
  name | path to change into
  create | flag whether to create missing folders or fail

Returns
  the result of the OBEX SETPATH request(s).

Note
  handles NULL, "", "/" and everything else correctly.

## obexftp_stat()

stat_entry_t * obexftp_stat | ( | obexftp_client_t * | cli,
|  | const char * | name )

Stat a directory entry.