libimobiledevice 1.1.5

- Main Page
- Data Structures
- Files

- File List
- Globals

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_private * | idevice_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

typedef idevice_connection_private* idevice_connection_t

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.

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:

  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_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_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_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_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_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.
  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 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 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:

  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.

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.