libimobiledevice: libimobiledevice/preboard.h File Reference

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

  client | The 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

  device | The device to connect to.
  service | The service descriptor returned by lockdownd_start_service.
  client | Pointer 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

  device | The device to connect to.
  client | Pointer that will point to a newly allocated preboard_client_t upon successful return. Must be freed using preboard_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
  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

  client | The preboard client to use for receiving
  manifest | An optional manifest
  status_cb | Callback function that will receive status and error messages Can be NULL if you want to handle receiving messages in your own code.
  user_data | User 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

  client | The preboard client
  manifest | An optional manifest
  status_cb | Callback function that will receive status and error messages. Can be NULL if you want to handle receiving messages in your own code.
  user_data | User 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

  client | The preboard client
  plist | Pointer 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

  client | The preboard client
  plist | Pointer 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

  client | The preboard client
  plist | The 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