libimobiledevice: libimobiledevice/mobile_image_mounter.h File Reference

libimobiledevice 1.3.0

Macros | Typedefs | Enumerations | Functions
mobile_image_mounter.h File Reference

Mount developer/debug disk images on the device. More...

## Macros
#define | MOBILE_IMAGE_MOUNTER_SERVICE_NAME "com.apple.mobile.mobile_image_mounter"

## Typedefs
typedef struct mobile_image_mounter_client_private | mobile_image_mounter_client_private
typedef mobile_image_mounter_client_private * | mobile_image_mounter_client_t
| The client handle.
typedef ssize_t(* | mobile_image_mounter_upload_cb_t) (void *buffer, size_t length, void *user_data)
| callback for image upload

## Enumerations
enum | mobile_image_mounter_error_t { MOBILE_IMAGE_MOUNTER_E_SUCCESS = 0, MOBILE_IMAGE_MOUNTER_E_INVALID_ARG = -1, MOBILE_IMAGE_MOUNTER_E_PLIST_ERROR = -2, MOBILE_IMAGE_MOUNTER_E_CONN_FAILED = -3, MOBILE_IMAGE_MOUNTER_E_COMMAND_FAILED = -4, MOBILE_IMAGE_MOUNTER_E_DEVICE_LOCKED = -5, MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
mobile_image_mounter_error_t | mobile_image_mounter_new (idevice_t device, lockdownd_service_descriptor_t service, mobile_image_mounter_client_t *client)
| Connects to the mobile_image_mounter service on the specified device. More...
mobile_image_mounter_error_t | mobile_image_mounter_start_service (idevice_t device, mobile_image_mounter_client_t *client, const char *label)
| Starts a new mobile_image_mounter service on the specified device and connects to it. More...
mobile_image_mounter_error_t | mobile_image_mounter_free (mobile_image_mounter_client_t client)
| Disconnects a mobile_image_mounter client from the device and frees up the mobile_image_mounter client data. More...
mobile_image_mounter_error_t | mobile_image_mounter_lookup_image (mobile_image_mounter_client_t client, const char *image_type, plist_t *result)
| Tells if the image of ImageType is already mounted. More...
mobile_image_mounter_error_t | mobile_image_mounter_upload_image (mobile_image_mounter_client_t client, const char *image_type, size_t image_size, const char *signature, uint16_t signature_size, mobile_image_mounter_upload_cb_t upload_cb, void *userdata)
| Uploads an image with an optional signature to the device. More...
mobile_image_mounter_error_t | mobile_image_mounter_mount_image (mobile_image_mounter_client_t client, const char *image_path, const char *signature, uint16_t signature_size, const char *image_type, plist_t *result)
| Mounts an image on the device. More...
mobile_image_mounter_error_t | mobile_image_mounter_hangup (mobile_image_mounter_client_t client)
| Hangs up the connection to the mobile_image_mounter service. More...

## Detailed Description

Mount developer/debug disk images on the device.

## Function Documentation

## ◆ mobile_image_mounter_free()

mobile_image_mounter_error_t mobile_image_mounter_free | ( | mobile_image_mounter_client_t | client | ) |

Disconnects a mobile_image_mounter client from the device and frees up the mobile_image_mounter client data.

Parameters

  client | The mobile_image_mounter client to disconnect and free.

Returns
  MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is NULL.

## ◆ mobile_image_mounter_hangup()

mobile_image_mounter_error_t mobile_image_mounter_hangup | ( | mobile_image_mounter_client_t | client | ) |

Hangs up the connection to the mobile_image_mounter service.

This functions has to be called before freeing up a mobile_image_mounter instance. If not, errors appear in the device's syslog.

Parameters

  client | The client to hang up

Returns
  MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is invalid, or another error code otherwise.

## ◆ mobile_image_mounter_lookup_image()

mobile_image_mounter_error_t mobile_image_mounter_lookup_image | ( | mobile_image_mounter_client_t | client,
|  | const char * | image_type,
|  | plist_t * | result
| ) |  |

Tells if the image of ImageType is already mounted.

Parameters

  client | The client use
  image_type | The type of the image to look up
  result | Pointer to a plist that will receive the result of the operation.

Note
  This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the operation has failed. Check the resulting plist for further information.

Returns
  MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an error code on error

## ◆ mobile_image_mounter_mount_image()

mobile_image_mounter_error_t mobile_image_mounter_mount_image | ( | mobile_image_mounter_client_t | client,
|  | const char * | image_path,
|  | const char * | signature,
|  | uint16_t | signature_size,
|  | const char * | image_type,
|  | plist_t * | result
| ) |  |

Mounts an image on the device.

Parameters

  client | The connected mobile_image_mounter client.
  image_path | The absolute path of the image to mount. The image must be present before calling this function.
  signature | Pointer to a buffer holding the images' signature
  signature_size | Length of the signature image_signature points to
  image_type | Type of image to mount
  result | Pointer to a plist that will receive the result of the operation.

Note
  This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the operation has failed. Check the resulting plist for further information. Note that there is no unmounting function. The mount persists until the device is rebooted.

Returns
  MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if on ore more parameters are invalid, or another error code otherwise.

## ◆ mobile_image_mounter_new()

mobile_image_mounter_error_t mobile_image_mounter_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | mobile_image_mounter_client_t * | client
| ) |  |

Connects to the mobile_image_mounter service on the specified device.

Parameters

  device | The device to connect to.
  service | The service descriptor returned by lockdownd_start_service.
  client | Pointer that will be set to a newly allocated mobile_image_mounter_client_t upon successful return.

Returns
  MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if device is NULL, or MOBILE_IMAGE_MOUNTER_E_CONN_FAILED if the connection to the device could not be established.

## ◆ mobile_image_mounter_start_service()

mobile_image_mounter_error_t mobile_image_mounter_start_service | ( | idevice_t | device,
|  | mobile_image_mounter_client_t * | client,
|  | const char * | label
| ) |  |

Starts a new mobile_image_mounter service on the specified device and connects to it.

Parameters

  device | The device to connect to.
  client | Pointer that will point to a newly allocated mobile_image_mounter_t upon successful return. Must be freed using mobile_image_mounter_free() after use.
  label | The label to use for communication. Usually the program name. Pass NULL to disable sending the label in requests to lockdownd.

Returns
  MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an MOBILE_IMAGE_MOUNTER_E_* error code otherwise.

## ◆ mobile_image_mounter_upload_image()

mobile_image_mounter_error_t mobile_image_mounter_upload_image | ( | mobile_image_mounter_client_t | client,
|  | const char * | image_type,
|  | size_t | image_size,
|  | const char * | signature,
|  | uint16_t | signature_size,
|  | mobile_image_mounter_upload_cb_t | upload_cb,
|  | void * | userdata
| ) |  |

Uploads an image with an optional signature to the device.

Parameters

  client | The connected mobile_image_mounter client.
  image_type | Type of image that is being uploaded.
  image_size | Total size of the image.
  signature | Buffer with a signature of the image being uploaded. If NULL, no signature will be used.
  signature_size | Total size of the image signature buffer. If 0, no signature will be used.
  upload_cb | Callback function that gets the data chunks for uploading the image.
  userdata | User defined data for the upload callback function.

Returns
  MOBILE_IMAGE_MOUNTER_E_SUCCESS on succes, or a MOBILE_IMAGE_MOUNTER_E_* error code otherwise.