libimobiledevice  1.3.0
Macros | Typedefs | Enumerations | Functions
preboard.h File Reference

Service to 'preboard' a device, which allows to ask for passcode during firmware updates. More...

Macros

#define PREBOARD_SERVICE_NAME   "com.apple.preboardservice_v2"
 

Typedefs

typedef struct preboard_client_private preboard_client_private
 
typedef preboard_client_private * preboard_client_t
 The client handle.
 
typedef void(* preboard_status_cb_t) (plist_t message, void *user_data)
 Reports the status response of the given command.
 

Enumerations

enum  preboard_error_t {
  PREBOARD_E_SUCCESS = 0,
  PREBOARD_E_INVALID_ARG = -1,
  PREBOARD_E_PLIST_ERROR = -2,
  PREBOARD_E_MUX_ERROR = -3,
  PREBOARD_E_SSL_ERROR = -4,
  PREBOARD_E_NOT_ENOUGH_DATA = -5,
  PREBOARD_E_TIMEOUT = -6,
  PREBOARD_E_OP_IN_PROGRESS = -10,
  PREBOARD_E_UNKNOWN_ERROR = -256
}
 Error Codes.
 

Functions

preboard_error_t preboard_client_new (idevice_t device, lockdownd_service_descriptor_t service, preboard_client_t *client)
 Connects to the preboard service on the specified device. More...
 
preboard_error_t preboard_client_start_service (idevice_t device, preboard_client_t *client, const char *label)
 Starts a new preboard service on the specified device and connects to it. More...
 
preboard_error_t preboard_client_free (preboard_client_t client)
 Disconnects a preboard client from the device and frees up the preboard client data. More...
 
preboard_error_t preboard_send (preboard_client_t client, plist_t plist)
 Sends a plist to the service. More...
 
preboard_error_t preboard_receive (preboard_client_t client, plist_t *plist)
 Receives a plist from the service. More...
 
preboard_error_t preboard_receive_with_timeout (preboard_client_t client, plist_t *plist, uint32_t timeout_ms)
 Receives a plist from the service with the specified timeout. More...
 
preboard_error_t preboard_create_stashbag (preboard_client_t client, plist_t manifest, preboard_status_cb_t status_cb, void *user_data)
 Tells the preboard service to create a stashbag. More...
 
preboard_error_t preboard_commit_stashbag (preboard_client_t client, plist_t manifest, preboard_status_cb_t status_cb, void *user_data)
 Instructs the preboard service to commit a previously created stashbag. More...
 

Detailed Description

Service to 'preboard' a device, which allows to ask for passcode during firmware updates.

Function Documentation

◆ preboard_client_free()

preboard_error_t preboard_client_free ( preboard_client_t  client)

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

Parameters
clientThe preboard client to disconnect and free.
Returns
PREBOARD_E_SUCCESS on success, PREBOARD_E_INVALID_ARG when client is NULL, or a PREBOARD_E_* error code otherwise.

◆ preboard_client_new()

preboard_error_t preboard_client_new ( idevice_t  device,
lockdownd_service_descriptor_t  service,
preboard_client_t client 
)

Connects to the preboard service on the specified device.

Parameters
deviceThe device to connect to.
serviceThe service descriptor returned by lockdownd_start_service.
clientPointer that will point to a newly allocated preboard_client_t upon successful return. Must be freed using preboard_client_free() after use.
Returns
PREBOARD_E_SUCCESS on success, PREBOARD_E_INVALID_ARG when client is NULL, or an PREBOARD_E_* error code otherwise.

◆ preboard_client_start_service()

preboard_error_t preboard_client_start_service ( idevice_t  device,
preboard_client_t client,
const char *  label 
)

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

Parameters
deviceThe device to connect to.
clientPointer that will point to a newly allocated preboard_client_t upon successful return. Must be freed using preboard_client_free() after use.
labelThe label to use for communication. Usually the program name. Pass NULL to disable sending the label in requests to lockdownd.
Returns
PREBOARD_E_SUCCESS on success, or a PREBOARD_E_* error code otherwise.

◆ preboard_commit_stashbag()

preboard_error_t preboard_commit_stashbag ( preboard_client_t  client,
plist_t  manifest,
preboard_status_cb_t  status_cb,
void *  user_data 
)

Instructs the preboard service to commit a previously created stashbag.

Parameters
clientThe preboard client to use for receiving
manifestAn optional manifest
status_cbCallback function that will receive status and error messages Can be NULL if you want to handle receiving messages in your own code.
user_dataUser data for callback function or NULL.

The callback or following preboard_receive* invocations will usually receive a dictionary with: { StashbagCommitComplete: true } or in case of an error: { StashbagCommitComplete: 0, Error: 1, <optional> ErrorString: <error string>=""> }

Returns
PREBOARD_E_SUCCESS if the command was successfully submitted, PREBOARD_E_INVALID_ARG when client is invalid, or a PREBOARD_E_* error code on error.

◆ preboard_create_stashbag()

preboard_error_t preboard_create_stashbag ( preboard_client_t  client,
plist_t  manifest,
preboard_status_cb_t  status_cb,
void *  user_data 
)

Tells the preboard service to create a stashbag.

This will make the device show a passcode entry so it can generate and store a token that is later used during restore.

Parameters
clientThe preboard client
manifestAn optional manifest
status_cbCallback function that will receive status and error messages. Can be NULL if you want to handle receiving messages in your own code.
user_dataUser data for callback function or NULL.

The callback or following preboard_receive* invocations will usually receive a dictionary with: { ShowDialog: true } If the user does not enter a passcode, after 2 minutes a timeout is reached and the device sends a dictionary with: { Timeout: true } followed by { HideDialog: true } If the user aborts the passcode entry, the device sends a dictionary: { Error: 1, ErrorString: <error string>=""> } followed by { HideDialog: true }

Returns
PREBOARD_E_SUCCESS if the command was successfully submitted, PREBOARD_E_INVALID_ARG when client is invalid, or a PREBOARD_E_* error code on error.

◆ preboard_receive()

preboard_error_t preboard_receive ( preboard_client_t  client,
plist_t *  plist 
)

Receives a plist from the service.

Parameters
clientThe preboard client
plistPointer to a plist_t what will be set to the received plist
Returns
PREBOARD_E_SUCCESS on success, PREBOARD_E_INVALID_ARG when client or plist is NULL, PREBOARD_E_TIMEOUT when no data was received after 5 seconds, or a PREBOARD_E_* error code on error

◆ preboard_receive_with_timeout()

preboard_error_t preboard_receive_with_timeout ( preboard_client_t  client,
plist_t *  plist,
uint32_t  timeout_ms 
)

Receives a plist from the service with the specified timeout.

Parameters
clientThe preboard client
plistPointer to a plist_t what will be set to the received plist
Returns
PREBOARD_E_SUCCESS on success, PREBOARD_E_INVALID_ARG when client or plist is NULL, PREBOARD_E_TIMEOUT when no data was received after the given timeout, or a PREBOARD_E_* error code on error.

◆ preboard_send()

preboard_error_t preboard_send ( preboard_client_t  client,
plist_t  plist 
)

Sends a plist to the service.

Parameters
clientThe preboard client
plistThe plist to send
Returns
PREBOARD_E_SUCCESS on success, PREBOARD_E_INVALID_ARG when client or plist is NULL, or a PREBOARD_E_* error code on error