libimobiledevice: libimobiledevice/house_arrest.h File Reference

libimobiledevice 1.3.0

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

Access app folders and their contents. More...

## Macros
#define | HOUSE_ARREST_SERVICE_NAME "com.apple.mobile.house_arrest"

## Typedefs
typedef struct house_arrest_client_private | house_arrest_client_private
typedef house_arrest_client_private * | house_arrest_client_t
| The client handle.

## Enumerations
enum | house_arrest_error_t { HOUSE_ARREST_E_SUCCESS = 0, HOUSE_ARREST_E_INVALID_ARG = -1, HOUSE_ARREST_E_PLIST_ERROR = -2, HOUSE_ARREST_E_CONN_FAILED = -3, HOUSE_ARREST_E_INVALID_MODE = -4, HOUSE_ARREST_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
house_arrest_error_t | house_arrest_client_new (idevice_t device, lockdownd_service_descriptor_t service, house_arrest_client_t *client)
| Connects to the house_arrest service on the specified device. More...
house_arrest_error_t | house_arrest_client_start_service (idevice_t device, house_arrest_client_t *client, const char *label)
| Starts a new house_arrest service on the specified device and connects to it. More...
house_arrest_error_t | house_arrest_client_free (house_arrest_client_t client)
| Disconnects an house_arrest client from the device and frees up the house_arrest client data. More...
house_arrest_error_t | house_arrest_send_request (house_arrest_client_t client, plist_t dict)
| Sends a generic request to the connected house_arrest service. More...
house_arrest_error_t | house_arrest_send_command (house_arrest_client_t client, const char *command, const char *appid)
| Send a command to the connected house_arrest service. More...
house_arrest_error_t | house_arrest_get_result (house_arrest_client_t client, plist_t *dict)
| Retrieves the result of a previously sent house_arrest_request_* request. More...
afc_error_t | afc_client_new_from_house_arrest_client (house_arrest_client_t client, afc_client_t *afc_client)
| Creates an AFC client using the given house_arrest client's connection allowing file access to a specific application directory requested by functions like house_arrest_request_vendor_documents(). More...

## Detailed Description

Access app folders and their contents.

## Function Documentation

## ◆ afc_client_new_from_house_arrest_client()

afc_error_t afc_client_new_from_house_arrest_client | ( | house_arrest_client_t | client,
|  | afc_client_t * | afc_client
| ) |  |

Creates an AFC client using the given house_arrest client's connection allowing file access to a specific application directory requested by functions like house_arrest_request_vendor_documents().

Parameters

  client | The house_arrest client to use.
  afc_client | Pointer that will be set to a newly allocated afc_client_t upon successful return.

Note
  After calling this function the house_arrest client will go in an AFC mode that will only allow calling house_arrest_client_free(). Only call house_arrest_client_free() if all AFC operations have completed since it will close the connection.

Returns
  AFC_E_SUCCESS if the afc client was successfully created, AFC_E_INVALID_ARG if client is invalid or was already used to create an afc client, or an AFC_E_* error code returned by afc_client_new_with_service_client().

## ◆ house_arrest_client_free()

house_arrest_error_t house_arrest_client_free | ( | house_arrest_client_t | client | ) |

Disconnects an house_arrest client from the device and frees up the house_arrest client data.

Note
  After using afc_client_new_from_house_arrest_client(), make sure you call afc_client_free() before calling this function to ensure a proper cleanup. Do not call this function if you still need to perform AFC operations since it will close the connection.

Parameters

  client | The house_arrest client to disconnect and free.

Returns
  HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when client is NULL, or an HOUSE_ARREST_E_* error code otherwise.

## ◆ house_arrest_client_new()

house_arrest_error_t house_arrest_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | house_arrest_client_t * | client
| ) |  |

Connects to the house_arrest 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 point to a newly allocated housearrest_client_t upon successful return.

Returns
  HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when client is NULL, or an HOUSE_ARREST_E_* error code otherwise.

## ◆ house_arrest_client_start_service()

house_arrest_error_t house_arrest_client_start_service | ( | idevice_t | device,
|  | house_arrest_client_t * | client,
|  | const char * | label
| ) |  |

Starts a new house_arrest 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 house_arrest_client_t upon successful return. Must be freed using house_arrest_client_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
  HOUSE_ARREST_E_SUCCESS on success, or an HOUSE_ARREST_E_* error code otherwise.

## ◆ house_arrest_get_result()

house_arrest_error_t house_arrest_get_result | ( | house_arrest_client_t | client,
|  | plist_t * | dict
| ) |  |

Retrieves the result of a previously sent house_arrest_request_* request.

Parameters

  client | The house_arrest client to use
  dict | Pointer that will be set to a plist containing the result to the last performed operation. It holds a key 'Status' with the value 'Complete' on success or a key 'Error' with an error description as value. The caller is responsible for freeing the returned plist.

Returns
  HOUSE_ARREST_E_SUCCESS if a result plist was retrieved, HOUSE_ARREST_E_INVALID_ARG if client is invalid, HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, or HOUSE_ARREST_E_CONN_FAILED if a connection error occurred.

## ◆ house_arrest_send_command()

house_arrest_error_t house_arrest_send_command | ( | house_arrest_client_t | client,
|  | const char * | command,
|  | const char * | appid
| ) |  |

Send a command to the connected house_arrest service.

Calls house_arrest_send_request() internally.

Parameters

  client | The house_arrest client to use.
  command | The command to send. Currently, only VendContainer and VendDocuments are known.
  appid | The application identifier to pass along with the .

Note
  If this function returns HOUSE_ARREST_E_SUCCESS it does not mean that the command was successful. To check for success or failure you need to call house_arrest_get_result().

See also
  house_arrest_get_result

Returns
  HOUSE_ARREST_E_SUCCESS if the command was successfully sent, HOUSE_ARREST_E_INVALID_ARG if client, command, or appid is invalid, HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, or HOUSE_ARREST_E_CONN_FAILED if a connection error occurred.

## ◆ house_arrest_send_request()

house_arrest_error_t house_arrest_send_request | ( | house_arrest_client_t | client,
|  | plist_t | dict
| ) |  |

Sends a generic request to the connected house_arrest service.

Parameters

  client | The house_arrest client to use.
  dict | The request to send as a plist of type PLIST_DICT.

Note
  If this function returns HOUSE_ARREST_E_SUCCESS it does not mean that the request was successful. To check for success or failure you need to call house_arrest_get_result().

See also
  house_arrest_get_result

Returns
  HOUSE_ARREST_E_SUCCESS if the request was successfully sent, HOUSE_ARREST_E_INVALID_ARG if client or dict is invalid, HOUSE_ARREST_E_PLIST_ERROR if dict is not a plist of type PLIST_DICT, HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, or HOUSE_ARREST_E_CONN_FAILED if a connection error occurred.