libimobiledevice  1.3.0
Data Structures | Typedefs | Enumerations | Functions
libimobiledevice.h File Reference

Device/Connection handling and communication. More...

Data Structures

struct  idevice_info_t
 
struct  idevice_event_t
 Provides information about the occurred event. More...
 

Typedefs

typedef struct idevice_private idevice_private
 
typedef idevice_private * idevice_t
 The device handle.
 
typedef struct idevice_connection_private idevice_connection_private
 
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_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_SSL_ERROR = -6,
  IDEVICE_E_TIMEOUT = -7
}
 Error Codes.
 
enum  idevice_options {
  IDEVICE_LOOKUP_USBMUX = 1 << 1,
  IDEVICE_LOOKUP_NETWORK = 1 << 2,
  IDEVICE_LOOKUP_PREFER_NETWORK = 1 << 3
}
 Options for idevice_new_with_options() More...
 
enum  idevice_connection_type {
  CONNECTION_USBMUXD = 1,
  CONNECTION_NETWORK
}
 Type of connection a device is available on.
 
enum  idevice_event_type {
  IDEVICE_DEVICE_ADD = 1,
  IDEVICE_DEVICE_REMOVE,
  IDEVICE_DEVICE_PAIRED
}
 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 UDIDs of currently available devices (USBMUX devices only). More...
 
idevice_error_t idevice_device_list_free (char **devices)
 Free a list of device UDIDs. More...
 
idevice_error_t idevice_get_device_list_extended (idevice_info_t **devices, int *count)
 Get a list of currently available devices. More...
 
idevice_error_t idevice_device_list_extended_free (idevice_info_t *devices)
 Free an extended device list retrieved through idevice_get_device_list_extended(). 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 (USBMUX devices only). More...
 
idevice_error_t idevice_new_with_options (idevice_t *device, const char *udid, enum idevice_options options)
 Creates an idevice_t structure for the device specified by UDID, if the device is available, with the given lookup options. 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_connection_disable_bypass_ssl (idevice_connection_t connection, uint8_t sslBypass)
 Disable bypass SSL for the given connection without sending out terminate messages. More...
 
idevice_error_t idevice_connection_get_fd (idevice_connection_t connection, int *fd)
 Get the underlying file descriptor for a connection. More...
 
idevice_error_t idevice_get_handle (idevice_t device, uint32_t *handle)
 Gets the handle or (usbmux device id) of the device.
 
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.

Enumeration Type Documentation

◆ idevice_options

Options for idevice_new_with_options()

Enumerator
IDEVICE_LOOKUP_USBMUX 

include USBMUX devices during lookup

IDEVICE_LOOKUP_NETWORK 

include network devices during lookup

IDEVICE_LOOKUP_PREFER_NETWORK 

prefer network connection if device is available via USBMUX and network

Function Documentation

◆ idevice_connect()

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_connection_disable_bypass_ssl()

idevice_error_t idevice_connection_disable_bypass_ssl ( idevice_connection_t  connection,
uint8_t  sslBypass 
)

Disable bypass SSL for the given connection without sending out terminate messages.

Parameters
connectionThe connection to disable SSL for.
sslBypassif true ssl connection will not be terminated but just cleaned up, allowing plain text data going on underlying connection
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_connection_disable_ssl()

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_connection_enable_ssl()

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_connection_get_fd()

idevice_error_t idevice_connection_get_fd ( idevice_connection_t  connection,
int *  fd 
)

Get the underlying file descriptor for a connection.

Parameters
connectionThe connection to get fd of
fdPointer to an int where the fd is stored
Returns
IDEVICE_E_SUCCESS if ok, otherwise an error code.

◆ idevice_connection_receive()

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_connection_receive_timeout()

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_connection_send()

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_device_list_extended_free()

idevice_error_t idevice_device_list_extended_free ( idevice_info_t *  devices)

Free an extended device list retrieved through idevice_get_device_list_extended().

Parameters
devicesDevice list to free.
Returns
IDEVICE_E_SUCCESS on success or an error value when an error occurred.

◆ idevice_device_list_free()

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_disconnect()

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_event_subscribe()

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 occurred.

◆ idevice_event_unsubscribe()

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 occurred.

◆ idevice_free()

idevice_error_t idevice_free ( idevice_t  device)

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

Parameters
deviceidevice_t to free.

◆ idevice_get_device_list()

idevice_error_t idevice_get_device_list ( char ***  devices,
int *  count 
)

Get a list of UDIDs of currently available devices (USBMUX devices only).

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 occurred.
Note
This function only returns the UDIDs of USBMUX devices. To also include network devices in the list, use idevice_get_device_list_extended().
See also
idevice_get_device_list_extended

◆ idevice_get_device_list_extended()

idevice_error_t idevice_get_device_list_extended ( idevice_info_t **  devices,
int *  count 
)

Get a list of currently available devices.

Parameters
devicesList of idevice_info_t records with device information. This list is terminated by a NULL pointer.
countNumber of devices included in the list.
Returns
IDEVICE_E_SUCCESS on success or an error value when an error occurred.

◆ idevice_new()

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 (USBMUX devices only).

Note
The resulting idevice_t structure has to be freed with idevice_free() if it is no longer used. If you need to connect to a device available via network, use idevice_new_with_options() and include IDEVICE_LOOKUP_NETWORK in options.
See also
idevice_new_with_options
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.

◆ idevice_new_with_options()

idevice_error_t idevice_new_with_options ( idevice_t device,
const char *  udid,
enum idevice_options  options 
)

Creates an idevice_t structure for the device specified by UDID, if the device is available, with the given lookup options.

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.
optionsSpecifies what connection types should be considered when looking up devices. Accepts bitwise or'ed values of idevice_options. If 0 (no option) is specified it will default to IDEVICE_LOOKUP_USBMUX. To lookup both USB and network-connected devices, pass IDEVICE_LOOKUP_USBMUX | IDEVICE_LOOKUP_NETWORK. If a device is available both via USBMUX and network, it will select the USB connection. This behavior can be changed by adding IDEVICE_LOOKUP_PREFER_NETWORK to the options in which case it will select the network connection.
Returns
IDEVICE_E_SUCCESS if ok, otherwise an error code.

◆ idevice_set_debug_level()

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.