libimobiledevice: libimobiledevice/restore.h File Reference

libimobiledevice 1.3.0

Typedefs | Enumerations | Functions
restore.h File Reference

Initiate restore process or reboot device. More...

## Typedefs
typedef struct restored_client_private | restored_client_private
typedef restored_client_private * | restored_client_t
| The client handle.

## Enumerations
enum | restored_error_t { RESTORE_E_SUCCESS = 0, RESTORE_E_INVALID_ARG = -1, RESTORE_E_PLIST_ERROR = -2, RESTORE_E_MUX_ERROR = -3, RESTORE_E_NOT_ENOUGH_DATA = -4, RESTORE_E_RECEIVE_TIMEOUT = -5, RESTORE_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
restored_error_t | restored_client_new (idevice_t device, restored_client_t *client, const char *label)
| Creates a new restored client for the device. More...
restored_error_t | restored_client_free (restored_client_t client)
| Closes the restored client session if one is running and frees up the restored_client struct. More...
restored_error_t | restored_query_type (restored_client_t client, char **type, uint64_t *version)
| Query the type of the service daemon. More...
restored_error_t | restored_query_value (restored_client_t client, const char *key, plist_t *value)
| Queries a value from the device specified by a key. More...
restored_error_t | restored_get_value (restored_client_t client, const char *key, plist_t *value)
| Retrieves a value from information plist specified by a key. More...
restored_error_t | restored_send (restored_client_t client, plist_t plist)
| Sends a plist to restored. More...
restored_error_t | restored_receive (restored_client_t client, plist_t *plist)
| Receives a plist from restored. More...
restored_error_t | restored_goodbye (restored_client_t client)
| Sends the Goodbye request to restored signaling the end of communication. More...
restored_error_t | restored_start_restore (restored_client_t client, plist_t options, uint64_t version)
| Requests to start a restore and retrieve it's port on success. More...
restored_error_t | restored_reboot (restored_client_t client)
| Requests device to reboot. More...
void | restored_client_set_label (restored_client_t client, const char *label)
| Sets the label to send for requests to restored. More...

## Detailed Description

Initiate restore process or reboot device.

Note
  This service is only available if the device is in restore mode.

## Function Documentation

## ◆ restored_client_free()

restored_error_t restored_client_free | ( | restored_client_t | client | ) |

Closes the restored client session if one is running and frees up the restored_client struct.

Parameters

  client | The restore client

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL

## ◆ restored_client_new()

restored_error_t restored_client_new | ( | idevice_t | device,
|  | restored_client_t * | client,
|  | const char * | label
| ) |  |

Creates a new restored client for the device.

Parameters

  device | The device to create a restored client for
  client | The pointer to the location of the new restored_client
  label | The label to use for communication. Usually the program name.

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL

## ◆ restored_client_set_label()

void restored_client_set_label | ( | restored_client_t | client,
|  | const char * | label
| ) |  |

Sets the label to send for requests to restored.

Parameters

  client | The restore client
  label | The label to set or NULL to disable sending a label

## ◆ restored_get_value()

restored_error_t restored_get_value | ( | restored_client_t | client,
|  | const char * | key,
|  | plist_t * | value
| ) |  |

Retrieves a value from information plist specified by a key.

Parameters

  client | An initialized restored client.
  key | The key name to request or NULL to query for all keys
  value | A plist node representing the result value node

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found

## ◆ restored_goodbye()

restored_error_t restored_goodbye | ( | restored_client_t | client | ) |

Sends the Goodbye request to restored signaling the end of communication.

Parameters

  client | The restore client

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if the device did not acknowledge the request

## ◆ restored_query_type()

restored_error_t restored_query_type | ( | restored_client_t | client,
|  | char ** | type,
|  | uint64_t * | version
| ) |  |

Query the type of the service daemon.

Depending on whether the device is queried in normal mode or restore mode, different types will be returned.

Parameters

  client | The restored client
  type | The type returned by the service daemon. Pass NULL to ignore.
  version | The restore protocol version. Pass NULL to ignore.

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL

## ◆ restored_query_value()

restored_error_t restored_query_value | ( | restored_client_t | client,
|  | const char * | key,
|  | plist_t * | value
| ) |  |

Queries a value from the device specified by a key.

Parameters

  client | An initialized restored client.
  key | The key name to request
  value | A plist node representing the result value node

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found

## ◆ restored_reboot()

restored_error_t restored_reboot | ( | restored_client_t | client | ) |

Requests device to reboot.

Parameters

  client | The restored client

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG if a parameter is NULL

## ◆ restored_receive()

restored_error_t restored_receive | ( | restored_client_t | client,
|  | plist_t * | plist
| ) |  |

Receives a plist from restored.

Parameters

  client | The restored client
  plist | The plist to store the received data

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client or plist is NULL

## ◆ restored_send()

restored_error_t restored_send | ( | restored_client_t | client,
|  | plist_t | plist
| ) |  |

Sends a plist to restored.

Note
  This function is low-level and should only be used if you need to send a new type of message.

Parameters

  client | The restored client
  plist | The plist to send

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG when client or plist is NULL

## ◆ restored_start_restore()

restored_error_t restored_start_restore | ( | restored_client_t | client,
|  | plist_t | options,
|  | uint64_t | version
| ) |  |

Requests to start a restore and retrieve it's port on success.

Parameters

  client | The restored client
  options | PLIST_DICT with options for the restore process or NULL
  version | the restore protocol version, see restored_query_type()

Returns
  RESTORE_E_SUCCESS on success, RESTORE_E_INVALID_ARG if a parameter is NULL, RESTORE_E_START_RESTORE_FAILED if the request fails