libimobiledevice  1.2.0
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 struct idevice_private idevice_private
 
typedef idevice_private * idevice_t
 The device handle. More...
 
typedef struct
idevice_connection_private 
idevice_connection_private
 
typedef
idevice_connection_private * 
idevice_connection_t
 The connection handle. More...
 
typedef void(* idevice_event_cb_t )(const idevice_event_t *event, void *user_data)
 Callback to notifiy if a device was added or removed. More...
 

Enumerations

enum  idevice_error_t {
  IDEVICE_E_SUCCESS = 0,
  IDEVICE_E_INVALID_ARG = -1,
  IDEVICE_E_UNKNOWN_ERROR = -2,
  IDEVICE_E_NO_DEVICE = -3,
  IDEVICE_E_NOT_ENOUGH_DATA = -4,
  IDEVICE_E_BAD_HEADER = -5,
  IDEVICE_E_SSL_ERROR = -6
}
 Error Codes.
 
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)
 Set the level of debugging. More...
 
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. More...
 
idevice_error_t idevice_event_unsubscribe (void)
 Release the event callback function that has been registered with idevice_event_subscribe(). More...
 
idevice_error_t idevice_get_device_list (char ***devices, int *count)
 Get a list of currently available devices. More...
 
idevice_error_t idevice_device_list_free (char **devices)
 Free a list of device udids. More...
 
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. More...
 
idevice_error_t idevice_free (idevice_t device)
 Cleans up an idevice structure, then frees the structure itself. More...
 
idevice_error_t idevice_connect (idevice_t device, uint16_t port, idevice_connection_t *connection)
 Set up a connection to the given device. More...
 
idevice_error_t idevice_disconnect (idevice_connection_t connection)
 Disconnect from the device and clean up the connection structure. More...
 
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. More...
 
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. More...
 
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. More...
 
idevice_error_t idevice_connection_enable_ssl (idevice_connection_t connection)
 Enables SSL for the given connection. More...
 
idevice_error_t idevice_connection_disable_ssl (idevice_connection_t connection)
 Disable SSL for the given connection. More...
 
idevice_error_t idevice_get_handle (idevice_t device, uint32_t *handle)
 Gets the handle of the device. More...
 
idevice_error_t idevice_get_udid (idevice_t device, char **udid)
 Gets the unique id for the device.
 

Detailed Description

Device/Connection handling and communication.

Typedef Documentation

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.

typedef idevice_private* idevice_t

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_disable_ssl ( idevice_connection_t  connection)

Disable SSL for the given connection.

Parameters
connectionThe connection to disable SSL for.
Returns
IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection is NULL. This function also returns IDEVICE_E_SUCCESS when SSL is not enabled and does no further error checking on cleanup.
idevice_error_t idevice_connection_enable_ssl ( idevice_connection_t  connection)

Enables SSL for the given connection.

Parameters
connectionThe connection to enable SSL for.
Returns
IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection is NULL or connection->ssl_data is non-NULL, or IDEVICE_E_SSL_ERROR when SSL initialization, setup, or handshake fails.
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 ( void  )

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)

Set the level of debugging.

Parameters
levelSet to 0 for no debug output or 1 to enable debug output.