obex.c File Reference

OpenOBEX API definition. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <fcntl.h>
#include <signal.h>
#include <unistd.h>
#include "obex_main.h"
#include "obex_object.h"
#include "obex_connect.h"
#include "obex_client.h"
#include "inobex.h"
#include "irobex.h"
#include "usbobex.h"
#include "btobex.h"


Defines

#define WSA_VER_MAJOR   2
#define WSA_VER_MINOR   2

Functions

void OBEX_FreeInterfaces (obex_t *self)
 Free memory allocated to OBEX interface structures.
obex_t * OBEX_Init (int transport, obex_event_t eventcb, unsigned int flags)
 Initialize OBEX.
int OBEX_RegisterCTransport (obex_t *self, obex_ctrans_t *ctrans)
 Register a custom transport.
void OBEX_Cleanup (obex_t *self)
 Close down an OBEX instance.
void OBEX_SetUserData (obex_t *self, void *data)
 Set userdata of an OBEX handle.
void * OBEX_GetUserData (obex_t *self)
 Read the userdata from an OBEX handle.
void OBEX_SetUserCallBack (obex_t *self, obex_event_t eventcb, void *data)
 Change user callback on an OBEX handle.
int OBEX_SetTransportMTU (obex_t *self, uint16_t mtu_rx, uint16_t mtu_tx_max)
 Set MTU to be used for receive and transmit.
int OBEX_ServerRegister (obex_t *self, struct sockaddr *saddr, int addrlen)
 Start listening for incoming connections.
obex_t * OBEX_ServerAccept (obex_t *server, obex_event_t eventcb, void *data)
 Accept an incoming connection.
int OBEX_HandleInput (obex_t *self, int timeout)
 Let the OBEX parser do some work.
int OBEX_CustomDataFeed (obex_t *self, uint8_t *inputbuf, int actual)
 Feed OBEX with data when using a custom transport.
int OBEX_TransportConnect (obex_t *self, struct sockaddr *saddr, int addrlen)
 Try to connect to peer.
int OBEX_TransportDisconnect (obex_t *self)
 Disconnect transport.
int OBEX_GetFD (obex_t *self)
 Get FD.
int OBEX_Request (obex_t *self, obex_object_t *object)
 Start a request (as client).
int OBEX_CancelRequest (obex_t *self, int nice)
 Cancel an ongoing operation.
int OBEX_SuspendRequest (obex_t *self, obex_object_t *object)
 Suspend transfer of an object.
int OBEX_ResumeRequest (obex_t *self)
 Resume transfer of an object.
obex_object_t * OBEX_ObjectNew (obex_t *self, uint8_t cmd)
 Create a new OBEX Object.
int OBEX_ObjectDelete (obex_t *self, obex_object_t *object)
 Delete an OBEX object.
int OBEX_ObjectAddHeader (obex_t *self, obex_object_t *object, uint8_t hi, obex_headerdata_t hv, uint32_t hv_size, unsigned int flags)
 Attach a header to an object.
int OBEX_ObjectGetNextHeader (obex_t *self, obex_object_t *object, uint8_t *hi, obex_headerdata_t *hv, uint32_t *hv_size)
 Get next available header from an object.
int OBEX_ObjectReParseHeaders (obex_t *self, obex_object_t *object)
 Allow the user to parse again the rx headers.
int OBEX_ObjectReadStream (obex_t *self, obex_object_t *object, const uint8_t **buf)
 Read data from body stream.
int OBEX_ObjectSetRsp (obex_object_t *object, uint8_t rsp, uint8_t lastrsp)
 Sets the response to a received request.
int OBEX_ObjectGetNonHdrData (obex_object_t *object, uint8_t **buffer)
 Get any data which was before headers.
int OBEX_ObjectSetNonHdrData (obex_object_t *object, const uint8_t *buffer, unsigned int len)
 Set data to send before headers.
int OBEX_ObjectSetHdrOffset (obex_object_t *object, unsigned int offset)
 Set headeroffset.
int OBEX_ObjectGetCommand (obex_t *self, obex_object_t *object)
 Get the OBEX commmand of an object.
int OBEX_UnicodeToChar (uint8_t *c, const uint8_t *uc, int size)
 Simple unicode to char function.
int OBEX_CharToUnicode (uint8_t *uc, const uint8_t *c, int size)
 Simple char to unicode function.
char * OBEX_ResponseToString (int rsp)
 Return a human understandable string from a response-code.
char * OBEX_GetResponseMessage (obex_t *self, int rsp)
 Return a human understandable string from a response-code.
void OBEX_SetCustomData (obex_t *self, void *data)
 Set customdata of an OBEX handle.
void * OBEX_GetCustomData (obex_t *self)
 Read the customdata from an OBEX handle.
int TcpOBEX_ServerRegister (obex_t *self, struct sockaddr *addr, int addrlen)
 Start listening for incoming TCP connections.
int TcpOBEX_TransportConnect (obex_t *self, struct sockaddr *addr, int addrlen)
 Connect TCP transport.
int InOBEX_ServerRegister (obex_t *self)
 Start listening for incoming connections.
int InOBEX_TransportConnect (obex_t *self, struct sockaddr *saddr, int addrlen)
 Connect Inet transport (deprecated).
int IrOBEX_ServerRegister (obex_t *self, const char *service)
 Start listening for incoming connections.
int IrOBEX_TransportConnect (obex_t *self, const char *service)
 Connect Irda transport.
int BtOBEX_ServerRegister (obex_t *self, bdaddr_t *src, uint8_t channel)
 Start listening for incoming connections.
int BtOBEX_TransportConnect (obex_t *self, bdaddr_t *src, bdaddr_t *dst, uint8_t channel)
 Connect Bluetooth transport.
int FdOBEX_TransportSetup (obex_t *self, int rfd, int wfd, int mtu)
int OBEX_InterfaceConnect (obex_t *self, obex_interface_t *intf)
 Connect USB interface.
int OBEX_FindInterfaces (obex_t *self, obex_interface_t **interfaces)
 Get a list of OBEX interfaces on the system.

Detailed Description

OpenOBEX API definition.

OpenOBEX library - Free implementation of the Object Exchange protocol.

Copyright (c) 1999, 2000 Dag Brattli, All Rights Reserved. Copyright (c) 1999, 2000 Pontus Fuchs, All Rights Reserved.

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

Define Documentation

#define WSA_VER_MAJOR   2

#define WSA_VER_MINOR   2

Function Documentation

int BtOBEX_ServerRegister ( obex_t *  self,
bdaddr_t *  src,
uint8_t  channel 
)

Start listening for incoming connections.

Parameters:
self OBEX handle
src source address to listen on
channel source channel to listen on
Returns:
-1 or negative error code on error
An easier server function to use for Bluetooth (Bluetooth OBEX) only.

int BtOBEX_TransportConnect ( obex_t *  self,
bdaddr_t *  src,
bdaddr_t *  dst,
uint8_t  channel 
)

Connect Bluetooth transport.

Parameters:
self OBEX handle
src source address to connect from
dst destination address to connect to
channel destination channel to connect to
Returns:
-1 or negative error code on error
An easier connect function to use for Bluetooth (Bluetooth OBEX) only.

int FdOBEX_TransportSetup ( obex_t *  self,
int  rfd,
int  wfd,
int  mtu 
)

int InOBEX_ServerRegister ( obex_t *  self  ) 

Start listening for incoming connections.

Parameters:
self OBEX handle
Returns:
-1 on error
An easier server function to use for TCP/IP (InOBEX) only.

This function is deprecated, use TcpOBEX_ServerRegister() instead.

int InOBEX_TransportConnect ( obex_t *  self,
struct sockaddr *  saddr,
int  addrlen 
)

Connect Inet transport (deprecated).

Parameters:
self OBEX handle
saddr Address to connect to
addrlen Length of address
Returns:
-1 on error
An easier connect function to use for TCP/IP (InOBEX) only.

This function is deprecated, use TcpOBEX_TransportConnect() instead.

int IrOBEX_ServerRegister ( obex_t *  self,
const char *  service 
)

Start listening for incoming connections.

Parameters:
self OBEX handle
service Service to bind to.
Returns:
-1 or negative error code on error
An easier server function to use for IrDA (IrOBEX) only.

int IrOBEX_TransportConnect ( obex_t *  self,
const char *  service 
)

Connect Irda transport.

Parameters:
self OBEX handle
service IrIAS service name to connect to
Returns:
-1 or negative error code on error
An easier connect function to use for IrDA (IrOBEX) only.

int OBEX_CancelRequest ( obex_t *  self,
int  nice 
)

Cancel an ongoing operation.

Parameters:
self OBEX handle
nice If true an OBEX Abort will be sent if beeing client or OBEX_RSP_UNAUTHORIZED as reponse if beeing server.
Returns:
-1 on error

int OBEX_CharToUnicode ( uint8_t *  uc,
const uint8_t *  c,
int  size 
)

Simple char to unicode function.

Parameters:
uc Destination (unicode)
c Source (char)
size Length of destination buffer, at least twice the size of source
Returns:
-1 on error
Buffers may not overlap. Returns -1 on error.

void OBEX_Cleanup ( obex_t *  self  ) 

Close down an OBEX instance.

Parameters:
self OBEX handle
Disconnects the transport and frees the interface (see OBEX_FreeInterfaces).

int OBEX_CustomDataFeed ( obex_t *  self,
uint8_t *  inputbuf,
int  actual 
)

Feed OBEX with data when using a custom transport.

Parameters:
self OBEX handle
inputbuf Pointer to custom data
actual Length of buffer
Returns:
-1 on error

int OBEX_FindInterfaces ( obex_t *  self,
obex_interface_t **  interfaces 
)

Get a list of OBEX interfaces on the system.

Parameters:
self OBEX handle
interfaces A list of OBEX interfaces
Returns:
a list of OBEX interfaces, or NULL if there are none.

void OBEX_FreeInterfaces ( obex_t *  self  ) 

Free memory allocated to OBEX interface structures.

Parameters:
self OBEX handle
Frees memory allocated to OBEX interface structures after it has been allocated by OBEX_FindInterfaces.

void* OBEX_GetCustomData ( obex_t *  self  ) 

Read the customdata from an OBEX handle.

Parameters:
self OBEX handle
Returns:
custom transport data, NULL on error

int OBEX_GetFD ( obex_t *  self  ) 

Get FD.

Parameters:
self OBEX handle
Returns:
file descriptor of the transport, -1 on error
Returns the filedescriptor of the transport. Returns -1 on error. Note that if you for example have a custom transport, no fd is available.

The returned filehandle can be used to do select() on, before calling OBEX_HandleInput()

There is one subtelty about this function. When the OBEX connection is established, it returns the connection filedescriptor, while for an unconnected server it will return the listening filedescriptor. This mean that after receiving an incomming connection, you need to call this function again.

char* OBEX_GetResponseMessage ( obex_t *  self,
int  rsp 
)

Return a human understandable string from a response-code.

Parameters:
self OBEX handle
rsp Response code.
Returns:
static response code string, NULL on error
The returned char must not be freed. Returns NULL on error.

void* OBEX_GetUserData ( obex_t *  self  ) 

Read the userdata from an OBEX handle.

Parameters:
self OBEX handle
Returns:
the userdata
Returns userdata set with OBEX_SetUserData.

int OBEX_HandleInput ( obex_t *  self,
int  timeout 
)

Let the OBEX parser do some work.

Parameters:
self OBEX handle
timeout Maximum time to wait in seconds
Returns:
-1 on error, 0 on timeout, positive on success
Let the OBEX parser read and process incoming data. If no data is available this call will block.

When a request has been sent or you are waiting for an incoming server- request you should call this function until the request has finished.

Like select() this function returns -1 on error, 0 on timeout or positive on success.

obex_t* OBEX_Init ( int  transport,
obex_event_t  eventcb,
unsigned int  flags 
)

Initialize OBEX.

Parameters:
transport Which transport to use. The following transports are available :
eventcb Function pointer to your event callback. See obex.h for prototype of this callback.
flags Bitmask of flags. The following flags are available :
Returns:
an OBEX handle or NULL on error.

int OBEX_InterfaceConnect ( obex_t *  self,
obex_interface_t *  intf 
)

Connect USB interface.

Parameters:
self OBEX handle
intf USB interface to connect to
Returns:
-1 or negative error code on error
An easier connect function to connect to a discovered interface (currently USB OBEX only).

int OBEX_ObjectAddHeader ( obex_t *  self,
obex_object_t *  object,
uint8_t  hi,
obex_headerdata_t  hv,
uint32_t  hv_size,
unsigned int  flags 
)

Attach a header to an object.

Parameters:
self OBEX handle
object OBEX object
hi Header identifier
hv Header value
hv_size Header size
flags See obex.h for possible values
Returns:
-1 on error
Add a new header to an object.

If you want all headers to fit in one packet, use the flag OBEX_FL_FIT_ONE_PACKET on all headers you add to an object.

To stream a body add a body header with hv.bs = NULL and set the flag OBEX_FL_STREAM_START. You will now get OBEX_EV_STREAMEMPTY events as soon as the the parser wants you to feed it with more data.

When you get an OBEX_EV_STREAMEMPTY event give the parser some data by adding a body-header and set the flag OBEX_FL_STREAM_DATA. When you have no more data to send set the flag OBEX_FL_STREAM_DATAEND instead.

After adding a header you are free to do whatever you want with the buffer if you are NOT streaming. If you are streaming you may not touch the buffer until you get another OBEX_EV_STREAMEMPTY or until the request finishes.

The headers will be sent in the order you add them.

int OBEX_ObjectDelete ( obex_t *  self,
obex_object_t *  object 
)

Delete an OBEX object.

Parameters:
self OBEX handle
object object to delete.
Returns:
-1 on error
Note that as soon as you have passed an object to the lib using OBEX_Request(), you shall not delete it yourself.

int OBEX_ObjectGetCommand ( obex_t *  self,
obex_object_t *  object 
)

Get the OBEX commmand of an object.

Parameters:
self OBEX context
object OBEX object (or NULL to access the current object)
Returns:
-1 on error
Call this function to get the OBEX command of an object.

int OBEX_ObjectGetNextHeader ( obex_t *  self,
obex_object_t *  object,
uint8_t *  hi,
obex_headerdata_t *  hv,
uint32_t *  hv_size 
)

Get next available header from an object.

Parameters:
self OBEX handle
object OBEX object
hi Pointer to header identifier
hv Pointer to hv
hv_size Pointer to hv_size
Returns:
0 when no more headers are available, -1 on error
Returns 0 when no more headers are available.

All headers are read-only.

You will get the headers in the received order.

int OBEX_ObjectGetNonHdrData ( obex_object_t *  object,
uint8_t **  buffer 
)

Get any data which was before headers.

Parameters:
object OBEX object
buffer Pointer to a pointer which will point to a read-only buffer
Returns:
size of the buffer or -1 for error

obex_object_t* OBEX_ObjectNew ( obex_t *  self,
uint8_t  cmd 
)

Create a new OBEX Object.

Parameters:
self OBEX handle
cmd command of object
Returns:
pointer to a new OBEX Object, NULL on error

int OBEX_ObjectReadStream ( obex_t *  self,
obex_object_t *  object,
const uint8_t **  buf 
)

Read data from body stream.

Parameters:
self OBEX handle
object OBEX object
buf A pointer to a pointer which this function will set to a buffer which shall be read (and ONLY read) after this function returns.
Returns:
number of bytes in buffer, or 0 for end-of-stream, -1 on error
To recieve the body as a stream call this function with buf = NULL as soon as you get an OBEX_EV_REQHINT event.

You will now recieve OBEX_EV_STREAMAVAIL events when data is available for you. Call this function to get the data.

Note! When receiving a stream data is not buffered so if you don't call this function when you get an OBEX_EV_STREAMAVAIL event data will be lost.

int OBEX_ObjectReParseHeaders ( obex_t *  self,
obex_object_t *  object 
)

Allow the user to parse again the rx headers.

Parameters:
self OBEX handle
object OBEX object
Returns:
1 on success, 0 if previous parsing not completed, -1 on error
The user must have extracted all headers from the object before calling this function (until OBEX_ObjectGetNextHeader() returns 0). Next call to OBEX_ObjectGetNextHeader() will return the first received header.

int OBEX_ObjectSetHdrOffset ( obex_object_t *  object,
unsigned int  offset 
)

Set headeroffset.

Parameters:
object OBEX object
offset Desired offset
Returns:
1 on success, -1 on error
Call this function when you get a OBEX_EV_REQHINT and you know that the command has data before the headers comes. You do NOT need to use this function on Connect and SetPath, they are handled automatically.

int OBEX_ObjectSetNonHdrData ( obex_object_t *  object,
const uint8_t *  buffer,
unsigned int  len 
)

Set data to send before headers.

Parameters:
object OBEX object
buffer Data to send
len Length to data
Returns:
1 on success, -1 on error
Some commands (notably SetPath) send data before headers. Use this function to set this data.

int OBEX_ObjectSetRsp ( obex_object_t *  object,
uint8_t  rsp,
uint8_t  lastrsp 
)

Sets the response to a received request.

Parameters:
object OBEX object
rsp Respose code in non-last packets
lastrsp Response code in last packet
Returns:
-1 on error

int OBEX_RegisterCTransport ( obex_t *  self,
obex_ctrans_t *  ctrans 
)

Register a custom transport.

Parameters:
self OBEX handle
ctrans Structure with callbacks to transport operations (see obex_const.h for details)
Returns:
-1 on error
Call this function directly after OBEX_Init if you are using a custom transport.

int OBEX_Request ( obex_t *  self,
obex_object_t *  object 
)

Start a request (as client).

Parameters:
self OBEX handle
object Object containing request
Returns:
-1 or negative error code on error

char* OBEX_ResponseToString ( int  rsp  ) 

Return a human understandable string from a response-code.

Parameters:
rsp Response code.
Returns:
static response code string, NULL on error
The returned char must not be freed. Returns NULL on error.

int OBEX_ResumeRequest ( obex_t *  self  ) 

Resume transfer of an object.

Parameters:
self OBEX handle
Returns:
-1 on error

obex_t* OBEX_ServerAccept ( obex_t *  server,
obex_event_t  eventcb,
void *  data 
)

Accept an incoming connection.

Parameters:
server OBEX handle
eventcb Event callback for client (use NULL for same as server)
data Userdata for client (use NULL for same as server)
Returns:
the client instance or NULL on error
Create a new OBEX instance to handle the incomming connection. The old OBEX instance will continue to listen for new connections. The two OBEX instances become totally independant from each other.

This function should be called after the library generates an OBEX_EV_ACCEPTHINT event to the user, but before the user start to pull data out of the incomming connection.

Using this function also requires that the OBEX handle was created with the OBEX_FL_KEEPSERVER flag set while calling OBEX_Init().

int OBEX_ServerRegister ( obex_t *  self,
struct sockaddr *  saddr,
int  addrlen 
)

Start listening for incoming connections.

Parameters:
self OBEX handle
saddr Local address to bind to
addrlen Length of address
Returns:
-1 on error
Bind a server socket to an Obex service. Common transport have specialised version of this function. Note : between 0.9.8 and 0.10.0, the prototype of this function changed to make it generic. If you want your code to work across new and old version of OpenObex, you may use #ifdef OBEX_MAXIMUM_MTU to test the Obex version.

void OBEX_SetCustomData ( obex_t *  self,
void *  data 
)

Set customdata of an OBEX handle.

Parameters:
self OBEX handle
data Custom Transport data
Note : this call is *reserved* to the Custom Transport and should not be use by the user/client. It allow to update the Custom Transport data originally set via OBEX_RegisterCTransport(). The Custom Transport data (or instance handle) is used to store data relative to the specific instance (i.e. connection), such as file descriptors, offsets and others, so that the Custom Transport can manage multiple connections transparently (i.e. without a lookup table).
  • Jean II

int OBEX_SetTransportMTU ( obex_t *  self,
uint16_t  mtu_rx,
uint16_t  mtu_tx_max 
)

Set MTU to be used for receive and transmit.

Parameters:
self OBEX handle
mtu_rx maximum receive transport packet size
mtu_tx_max maximum transmit transport packet size negociated
Returns:
-1 or negative error code on error
Changing those values can increase the performance of the underlying transport, but will increase memory consumption and latency (especially abort latency), and may trigger bugs in buggy transport. This need to be set *before* establishing the connection.

void OBEX_SetUserCallBack ( obex_t *  self,
obex_event_t  eventcb,
void *  data 
)

Change user callback on an OBEX handle.

Parameters:
self OBEX handle
eventcb Function pointer to your new event callback.
data Pointer to the new user data to pass to the new callback (optional)

void OBEX_SetUserData ( obex_t *  self,
void *  data 
)

Set userdata of an OBEX handle.

Parameters:
self OBEX handle
data It's all up to you!

int OBEX_SuspendRequest ( obex_t *  self,
obex_object_t *  object 
)

Suspend transfer of an object.

Parameters:
self OBEX handle
object object to suspend (NULL to suspend currently transfered object)
Returns:
-1 on error

int OBEX_TransportConnect ( obex_t *  self,
struct sockaddr *  saddr,
int  addrlen 
)

Try to connect to peer.

Parameters:
self OBEX handle
saddr Address to connect to
addrlen Length of address
Returns:
-1 on error

int OBEX_TransportDisconnect ( obex_t *  self  ) 

Disconnect transport.

Parameters:
self OBEX handle
Returns:
-1 on error

int OBEX_UnicodeToChar ( uint8_t *  c,
const uint8_t *  uc,
int  size 
)

Simple unicode to char function.

Parameters:
c Destination (char)
uc Source (unicode)
size Length of destination buffer, at least half the size of source
Returns:
-1 on error
Buffers may not overlap. Returns -1 on error.

int TcpOBEX_ServerRegister ( obex_t *  self,
struct sockaddr *  addr,
int  addrlen 
)

Start listening for incoming TCP connections.

Parameters:
self OBEX handle
addr Address to bind to (*:650 if NULL)
addrlen Length of address structure
Returns:
-1 on error
An easier server function to use for TCP/IP (TcpOBEX) only. It supports IPv4 (AF_INET) and IPv6 (AF_INET6). Note: INADDR_ANY will get mapped to IN6ADDR_ANY and using port 0 will select the default OBEX port.

int TcpOBEX_TransportConnect ( obex_t *  self,
struct sockaddr *  addr,
int  addrlen 
)

Connect TCP transport.

Parameters:
self OBEX handle
addr Address to connect to ([::1]:650 if NULL)
addrlen Length of address structure
Returns:
-1 on error
An easier connect function to use for TCP/IP (TcpOBEX) only. It supports IPv4 (AF_INET) and IPv6 (AF_INET6).