libimobiledevice  1.1.6
Typedefs | Functions
restore.h File Reference

Initiate restore process or reboot device. More...

Typedefs

typedef int16_t restored_error_t
 Represents an error code. More...
 
typedef restored_client_privaterestored_client_t
 The client handle. More...
 

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

Error Codes

#define RESTORE_E_SUCCESS   0
 
#define RESTORE_E_INVALID_ARG   -1
 
#define RESTORE_E_INVALID_CONF   -2
 
#define RESTORE_E_PLIST_ERROR   -3
 
#define RESTORE_E_DICT_ERROR   -4
 
#define RESTORE_E_NOT_ENOUGH_DATA   -5
 
#define RESTORE_E_MUX_ERROR   -6
 
#define RESTORE_E_START_RESTORE_FAILED   -7
 
#define RESTORE_E_UNKNOWN_ERROR   -256
 

Detailed Description

Initiate restore process or reboot device.

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

Typedef Documentation

The client handle.

typedef int16_t restored_error_t

Represents an error code.

Function Documentation

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
clientThe restore client
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL

References restored_goodbye().

Referenced by 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
deviceThe device to create a restored client for
clientThe pointer to the location of the new restored_client
labelThe label to use for communication. Usually the program name.
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL

References idevice_get_udid(), and restored_client_free().

void restored_client_set_label ( restored_client_t  client,
const char *  label 
)

Sets the label to send for requests to restored.

Parameters
clientThe restore client
labelThe label to set or NULL to disable sending a label
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
clientAn initialized restored client.
keyThe key name to request or NULL to query for all keys
valueA plist node representing the result value node
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found
restored_error_t restored_goodbye ( restored_client_t  client)

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

Parameters
clientThe restore client
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if the device did not acknowledge the request

References restored_receive(), and restored_send().

Referenced by restored_client_free().

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
clientThe restored client
typeThe type returned by the service daemon. Pass NULL to ignore.
versionThe restore protocol version. Pass NULL to ignore.
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL

References restored_receive(), and restored_send().

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
clientAn initialized restored client.
keyThe key name to request
valueA plist node representing the result value node
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, RESTORE_E_PLIST_ERROR if value for key can't be found

References restored_receive(), and restored_send().

restored_error_t restored_reboot ( restored_client_t  client)

Requests device to reboot.

Parameters
clientThe restored client
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter is NULL

References restored_receive(), and restored_send().

restored_error_t restored_receive ( restored_client_t  client,
plist_t *  plist 
)

Receives a plist from restored.

Parameters
clientThe restored client
plistThe plist to store the received data
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or plist is NULL

Referenced by restored_goodbye(), restored_query_type(), restored_query_value(), and restored_reboot().

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
clientThe restored client
plistThe plist to send
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or plist is NULL

Referenced by restored_goodbye(), restored_query_type(), restored_query_value(), restored_reboot(), and 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
clientThe restored client
optionsPLIST_DICT with options for the restore process or NULL
versionthe restore protocol version, see restored_query_type()
Returns
RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter is NULL, RESTORE_E_START_RESTORE_FAILED if the request fails

References restored_send().