libimobiledevice: libimobiledevice/libimobiledevice.h File Reference

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

enum 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

  device | The device to connect to.
  port | The destination port to connect to.
  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_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

  connection | The connection to disable SSL for.
  sslBypass | if 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

  connection | The 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

  connection | The 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

  connection | The connection to get fd of
  fd | Pointer 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

  connection | The connection to receive data from.
  data | Buffer that will be filled with the received data. This buffer has to be large enough to hold len bytes.
  len | Buffer size or number of bytes to receive.
  recv_bytes | Number 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

  connection | The connection to receive data from.
  data | Buffer that will be filled with the received data. This buffer has to be large enough to hold len bytes.
  len | Buffer size or number of bytes to receive.
  recv_bytes | Number of bytes actually received.
  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_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

  connection | The connection to send data over.
  data | Buffer with data to send.
  len | Size of the buffer to send.
  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_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

  devices | Device 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

  devices | List 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

  connection | The 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

  callback | Callback function to call.
  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 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

  device | idevice_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

  devices | List of UDIDs of devices that are currently available. This list is terminated by a NULL pointer.
  count | Number 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

  devices | List of idevice_info_t records with device information. This list is terminated by a NULL pointer.
  count | Number 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

  device | Upon calling this function, a pointer to a location of type idevice_t. On successful return, this location will be populated.
  udid | The 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

  device | Upon calling this function, a pointer to a location of type idevice_t. On successful return, this location will be populated.
  udid | The UDID to match.
  options | Specifies 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

  level | Set to 0 for no debug output or 1 to enable debug output.