libimobiledevice/libimobiledevice.h File Reference

Device/Connection handling and communication. More...

Data Structures

struct  idevice_event_t
 Provides information about the occured event. More...

Typedefs

typedef int16_t idevice_error_t
 Represents an error code.
typedef idevice_privateidevice_t
 The device handle.
typedef
idevice_connection_private
idevice_connection_t
 The connection handle.
typedef void(* idevice_event_cb_t )(const idevice_event_t *event, void *user_data)
 Callback to notifiy if a device was added or removed.

Enumerations

enum  idevice_event_type {
  IDEVICE_DEVICE_ADD = 1,
  IDEVICE_DEVICE_REMOVE
}
 

The event type for device add or removal.


Functions

void idevice_set_debug_level (int level)
 Sets the level of debugging.
idevice_error_t idevice_event_subscribe (idevice_event_cb_t callback, void *user_data)
 Register a callback function that will be called when device add/remove events occur.
idevice_error_t idevice_event_unsubscribe ()
 Release the event callback function that has been registered with idevice_event_subscribe().
idevice_error_t idevice_get_device_list (char ***devices, int *count)
 Get a list of currently available devices.
idevice_error_t idevice_device_list_free (char **devices)
 Free a list of device uuids.
idevice_error_t idevice_new (idevice_t *device, const char *uuid)
 Creates an idevice_t structure for the device specified by uuid, if the device is available.
idevice_error_t idevice_free (idevice_t device)
 Cleans up an idevice structure, then frees the structure itself.
idevice_error_t idevice_connect (idevice_t device, uint16_t port, idevice_connection_t *connection)
 Set up a connection to the given device.
idevice_error_t idevice_disconnect (idevice_connection_t connection)
 Disconnect from the device and clean up the connection structure.
idevice_error_t idevice_connection_send (idevice_connection_t connection, const char *data, uint32_t len, uint32_t *sent_bytes)
 Send data to a device via the given connection.
idevice_error_t idevice_connection_receive_timeout (idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout)
 Receive data from a device via the given connection.
idevice_error_t idevice_connection_receive (idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes)
 Receive data from a device via the given connection.
idevice_error_t idevice_get_handle (idevice_t device, uint32_t *handle)
 Gets the handle of the device.
idevice_error_t idevice_get_uuid (idevice_t device, char **uuid)
 Gets the unique id for the device.

Error Codes



#define IDEVICE_E_SUCCESS   0
#define IDEVICE_E_INVALID_ARG   -1
#define IDEVICE_E_UNKNOWN_ERROR   -2
#define IDEVICE_E_NO_DEVICE   -3
#define IDEVICE_E_NOT_ENOUGH_DATA   -4
#define IDEVICE_E_BAD_HEADER   -5
#define IDEVICE_E_SSL_ERROR   -6

Detailed Description

Device/Connection handling and communication.


Typedef Documentation

The connection handle.

typedef int16_t idevice_error_t

Represents an error code.

typedef void(* idevice_event_cb_t)(const idevice_event_t *event, void *user_data)

Callback to notifiy if a device was added or removed.

The device handle.


Function Documentation

idevice_error_t idevice_connect ( idevice_t  device,
uint16_t  port,
idevice_connection_t connection 
)

Set up a connection to the given device.

Parameters:
device The device to connect to.
Parameters:
port The destination port to connect to.
Parameters:
connection Pointer to an idevice_connection_t that will be filled with the necessary data of the connection.
Returns:
IDEVICE_E_SUCCESS if ok, otherwise an error code.
idevice_error_t idevice_connection_receive ( idevice_connection_t  connection,
char *  data,
uint32_t  len,
uint32_t *  recv_bytes 
)

Receive data from a device via the given connection.

This function is like idevice_connection_receive_timeout, but with a predefined reasonable timeout.

Parameters:
connection The connection to receive data from.
Parameters:
data Buffer that will be filled with the received data. This buffer has to be large enough to hold len bytes.
Parameters:
len Buffer size or number of bytes to receive.
Parameters:
recv_bytes Number of bytes actually received.
Returns:
IDEVICE_E_SUCCESS if ok, otherwise an error code.
idevice_error_t idevice_connection_receive_timeout ( idevice_connection_t  connection,
char *  data,
uint32_t  len,
uint32_t *  recv_bytes,
unsigned int  timeout 
)

Receive data from a device via the given connection.

This function will return after the given timeout even if no data has been received.

Parameters:
connection The connection to receive data from.
Parameters:
data Buffer that will be filled with the received data. This buffer has to be large enough to hold len bytes.
Parameters:
len Buffer size or number of bytes to receive.
Parameters:
recv_bytes Number of bytes actually received.
Parameters:
timeout Timeout in milliseconds after which this function should return even if no data has been received.
Returns:
IDEVICE_E_SUCCESS if ok, otherwise an error code.
idevice_error_t idevice_connection_send ( idevice_connection_t  connection,
const char *  data,
uint32_t  len,
uint32_t *  sent_bytes 
)

Send data to a device via the given connection.

Parameters:
connection The connection to send data over.
Parameters:
data Buffer with data to send.
Parameters:
len Size of the buffer to send.
Parameters:
sent_bytes Pointer to an uint32_t that will be filled with the number of bytes actually sent.
Returns:
IDEVICE_E_SUCCESS if ok, otherwise an error code.
idevice_error_t idevice_device_list_free ( char **  devices  ) 

Free a list of device uuids.

Parameters:
devices List of uuids to free.
Returns:
Always returnes IDEVICE_E_SUCCESS.
idevice_error_t idevice_disconnect ( idevice_connection_t  connection  ) 

Disconnect from the device and clean up the connection structure.

Parameters:
connection The connection to close.
Returns:
IDEVICE_E_SUCCESS if ok, otherwise an error code.
idevice_error_t idevice_event_subscribe ( idevice_event_cb_t  callback,
void *  user_data 
)

Register a callback function that will be called when device add/remove events occur.

Parameters:
callback Callback function to call.
Parameters:
user_data Application-specific data passed as parameter to the registered callback function.
Returns:
IDEVICE_E_SUCCESS on success or an error value when an error occured.
idevice_error_t idevice_event_unsubscribe (  ) 

Release the event callback function that has been registered with idevice_event_subscribe().

Returns:
IDEVICE_E_SUCCESS on success or an error value when an error occured.
idevice_error_t idevice_free ( idevice_t  device  ) 

Cleans up an idevice structure, then frees the structure itself.

This is a library-level function; deals directly with the device to tear down relations, but otherwise is mostly internal.

Parameters:
device idevice_t to free.
idevice_error_t idevice_get_device_list ( char ***  devices,
int *  count 
)

Get a list of currently available devices.

Parameters:
devices List of uuids of devices that are currently available. This list is terminated by a NULL pointer.
Parameters:
count Number of devices found.
Returns:
IDEVICE_E_SUCCESS on success or an error value when an error occured.
idevice_error_t idevice_get_handle ( idevice_t  device,
uint32_t *  handle 
)

Gets the handle of the device.

Depends on the connection type.

idevice_error_t idevice_new ( idevice_t device,
const char *  uuid 
)

Creates an idevice_t structure for the device specified by uuid, if the device is available.

Note:
The resulting idevice_t structure has to be freed with idevice_free() if it is no longer used.
Parameters:
device Upon calling this function, a pointer to a location of type idevice_t. On successful return, this location will be populated.
Parameters:
uuid The UUID to match.
Returns:
IDEVICE_E_SUCCESS if ok, otherwise an error code.
void idevice_set_debug_level ( int  level  ) 

Sets the level of debugging.

Currently the only acceptable values are 0 and 1.

Parameters:
level Set to 0 for no debugging or 1 for debugging.
Generated on Thu Dec 16 22:53:47 2010 for libimobiledevice by  doxygen 1.6.3