libimobiledevice  1.1.5
Data Structures | Typedefs | Enumerations | Functions
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 udids.
idevice_error_t idevice_new (idevice_t *device, const char *udid)
 Creates an idevice_t structure for the device specified by udid, 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_udid (idevice_t device, char **udid)
 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:
deviceThe device to connect to.
portThe destination port to connect to.
connectionPointer 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:
connectionThe connection to receive data from.
dataBuffer that will be filled with the received data. This buffer has to be large enough to hold len bytes.
lenBuffer size or number of bytes to receive.
recv_bytesNumber 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:
connectionThe connection to receive data from.
dataBuffer that will be filled with the received data. This buffer has to be large enough to hold len bytes.
lenBuffer size or number of bytes to receive.
recv_bytesNumber of bytes actually received.
timeoutTimeout 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:
connectionThe connection to send data over.
dataBuffer with data to send.
lenSize of the buffer to send.
sent_bytesPointer 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 udids.

Parameters:
devicesList of udids 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:
connectionThe 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:
callbackCallback function to call.
user_dataApplication-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:
deviceidevice_t to free.
idevice_error_t idevice_get_device_list ( char ***  devices,
int *  count 
)

Get a list of currently available devices.

Parameters:
devicesList of udids of devices that are currently available. This list is terminated by a NULL pointer.
countNumber 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 *  udid 
)

Creates an idevice_t structure for the device specified by udid, 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:
deviceUpon calling this function, a pointer to a location of type idevice_t. On successful return, this location will be populated.
udidThe UDID 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:
levelSet to 0 for no debugging or 1 for debugging.