libimobiledevice 1.1.5

- Main Page
- Data Structures
- Files

- File List
- Globals

Typedefs | Functions
installation_proxy.h File Reference

Manage applications on a device. More...

## Typedefs
typedef int16_t | instproxy_error_t
| Represents an error code.
typedef instproxy_client_private * | instproxy_client_t
| The client handle.
typedef void(* | instproxy_status_cb_t )(const char *operation, plist_t status, void *user_data)
| Reports the status of the given operation.

## Functions
instproxy_error_t | instproxy_client_new (idevice_t device, lockdownd_service_descriptor_t service, instproxy_client_t *client)
| Connects to the installation_proxy service on the specified device.
instproxy_error_t | instproxy_client_free (instproxy_client_t client)
| Disconnects an installation_proxy client from the device and frees up the installation_proxy client data.
instproxy_error_t | instproxy_browse (instproxy_client_t client, plist_t client_options, plist_t *result)
| List installed applications.
instproxy_error_t | instproxy_install (instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data)
| Install an application on the device.
instproxy_error_t | instproxy_upgrade (instproxy_client_t client, const char *pkg_path, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data)
| Upgrade an application on the device.
instproxy_error_t | instproxy_uninstall (instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data)
| Uninstall an application from the device.
instproxy_error_t | instproxy_lookup_archives (instproxy_client_t client, plist_t client_options, plist_t *result)
| List archived applications.
instproxy_error_t | instproxy_archive (instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data)
| Archive an application on the device.
instproxy_error_t | instproxy_restore (instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data)
| Restore a previously archived application on the device.
instproxy_error_t | instproxy_remove_archive (instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data)
| Removes a previously archived application from the device.
plist_t | instproxy_client_options_new ()
| Create a new client_options plist.
void | instproxy_client_options_add (plist_t client_options,...)
| Add one or more new key:value pairs to the given client_options.
void | instproxy_client_options_free (plist_t client_options)
| Free client_options plist.

## Error Codes
#define | INSTPROXY_E_SUCCESS 0
#define | INSTPROXY_E_INVALID_ARG -1
#define | INSTPROXY_E_PLIST_ERROR -2
#define | INSTPROXY_E_CONN_FAILED -3
#define | INSTPROXY_E_OP_IN_PROGRESS -4
#define | INSTPROXY_E_OP_FAILED -5
#define | INSTPROXY_E_UNKNOWN_ERROR -256

## Detailed Description

Manage applications on a device.

## Typedef Documentation

typedef instproxy_client_private* instproxy_client_t

The client handle.

typedef int16_t instproxy_error_t

Represents an error code.

## Function Documentation

instproxy_error_t instproxy_archive | ( | instproxy_client_t | client,
|  | const char * | appid,
|  | plist_t | client_options,
|  | instproxy_status_cb_t | status_cb,
|  | void * | user_data
| ) |  |

Archive an application on the device.

This function tells the device to make an archive of the specified application. This results in the device creating a ZIP archive in the 'ApplicationArchives' directory and uninstalling the application.

Parameters:

  client | The connected installation proxy client
  appid | ApplicationIdentifier of the app to archive.
  client_options | The client options to use, as PLIST_DICT, or NULL. Valid options include: "SkipUninstall" -> Boolean "ArchiveType" -> "ApplicationOnly"
  status_cb | Callback function for progress and status information. If NULL is passed, this function will run synchronously.
  user_data | Callback data passed to status_cb.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

Note:
  If a callback function is given (async mode), this function returns INSTPROXY_E_SUCCESS immediately if the status updater thread has been created successfully; any error occuring during the operation has to be handled inside the specified callback function.

instproxy_error_t instproxy_browse | ( | instproxy_client_t | client,
|  | plist_t | client_options,
|  | plist_t * | result
| ) |  |

List installed applications.

This function runs synchronously.

Parameters:

  client | The connected installation_proxy client
  client_options | The client options to use, as PLIST_DICT, or NULL. Valid client options include: "ApplicationType" -> "User" "ApplicationType" -> "System"
  result | Pointer that will be set to a plist that will hold an array of PLIST_DICT holding information about the applications found.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

instproxy_error_t instproxy_client_free | ( | instproxy_client_t | client | ) |

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

Parameters:

  client | The installation_proxy client to disconnect and free.

Returns:
  INSTPROXY_E_SUCCESS on success or INSTPROXY_E_INVALID_ARG if client is NULL.

instproxy_error_t instproxy_client_new | ( | idevice_t | device,
|  | lockdownd_service_descriptor_t | service,
|  | instproxy_client_t * | client
| ) |  |

Connects to the installation_proxy 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 be set to a newly allocated instproxy_client_t upon successful return.

Returns:
  INSTPROXY_E_SUCCESS on success, or an INSTPROXY_E_* error value when an error occured.

void instproxy_client_options_add | ( | plist_t | client_options,
|  |  | ...
| ) |  |

Add one or more new key:value pairs to the given client_options.

Parameters:

  client_options | The client options to modify.
  ... | KEY, VALUE, [KEY, VALUE], NULL

Note:
  The keys and values passed are expected to be strings, except for the keys "ApplicationSINF", "iTunesMetadata", "ReturnAttributes" which are expecting a plist_t node as value and "SkipUninstall" expects int.

void instproxy_client_options_free | ( | plist_t | client_options | ) |

Free client_options plist.

Parameters:

  client_options | The client options plist to free. Does nothing if NULL is passed.

plist_t instproxy_client_options_new | ( |  | ) |

Create a new client_options plist.

Returns:
  A new plist_t of type PLIST_DICT.

instproxy_error_t instproxy_install | ( | instproxy_client_t | client,
|  | const char * | pkg_path,
|  | plist_t | client_options,
|  | instproxy_status_cb_t | status_cb,
|  | void * | user_data
| ) |  |

Install an application on the device.

Parameters:

  client | The connected installation_proxy client
  pkg_path | Path of the installation package (inside the AFC jail)
  client_options | The client options to use, as PLIST_DICT, or NULL. Valid options include: "iTunesMetadata" -> PLIST_DATA "ApplicationSINF" -> PLIST_DATA "PackageType" -> "Developer" If PackageType -> Developer is specified, then pkg_path points to an .app directory instead of an install package.
  status_cb | Callback function for progress and status information. If NULL is passed, this function will run synchronously.
  user_data | Callback data passed to status_cb.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

Note:
  If a callback function is given (async mode), this function returns INSTPROXY_E_SUCCESS immediately if the status updater thread has been created successfully; any error occuring during the operation has to be handled inside the specified callback function.

instproxy_error_t instproxy_lookup_archives | ( | instproxy_client_t | client,
|  | plist_t | client_options,
|  | plist_t * | result
| ) |  |

List archived applications.

This function runs synchronously.

See also:
  instproxy_archive

Parameters:

  client | The connected installation_proxy client
  client_options | The client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so pass NULL here.
  result | Pointer that will be set to a plist containing a PLIST_DICT holding information about the archived applications found.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

instproxy_error_t instproxy_remove_archive | ( | instproxy_client_t | client,
|  | const char * | appid,
|  | plist_t | client_options,
|  | instproxy_status_cb_t | status_cb,
|  | void * | user_data
| ) |  |

Removes a previously archived application from the device.

This function removes the ZIP archive from the 'ApplicationArchives' directory.

Parameters:

  client | The connected installation proxy client
  appid | ApplicationIdentifier of the archived app to remove.
  client_options | The client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so passing NULL is fine.
  status_cb | Callback function for progress and status information. If NULL is passed, this function will run synchronously.
  user_data | Callback data passed to status_cb.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

Note:
  If a callback function is given (async mode), this function returns INSTPROXY_E_SUCCESS immediately if the status updater thread has been created successfully; any error occuring during the operation has to be handled inside the specified callback function.

instproxy_error_t instproxy_restore | ( | instproxy_client_t | client,
|  | const char * | appid,
|  | plist_t | client_options,
|  | instproxy_status_cb_t | status_cb,
|  | void * | user_data
| ) |  |

Restore a previously archived application on the device.

This function is the counterpart to instproxy_archive.

See also:
  instproxy_archive

Parameters:

  client | The connected installation proxy client
  appid | ApplicationIdentifier of the app to restore.
  client_options | The client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so pass NULL here.
  status_cb | Callback function for progress and status information. If NULL is passed, this function will run synchronously.
  user_data | Callback data passed to status_cb.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

Note:
  If a callback function is given (async mode), this function returns INSTPROXY_E_SUCCESS immediately if the status updater thread has been created successfully; any error occuring during the operation has to be handled inside the specified callback function.

instproxy_error_t instproxy_uninstall | ( | instproxy_client_t | client,
|  | const char * | appid,
|  | plist_t | client_options,
|  | instproxy_status_cb_t | status_cb,
|  | void * | user_data
| ) |  |

Uninstall an application from the device.

Parameters:

  client | The connected installation proxy client
  appid | ApplicationIdentifier of the app to uninstall
  client_options | The client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so pass NULL here.
  status_cb | Callback function for progress and status information. If NULL is passed, this function will run synchronously.
  user_data | Callback data passed to status_cb.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

Note:
  If a callback function is given (async mode), this function returns INSTPROXY_E_SUCCESS immediately if the status updater thread has been created successfully; any error occuring during the operation has to be handled inside the specified callback function.

instproxy_error_t instproxy_upgrade | ( | instproxy_client_t | client,
|  | const char * | pkg_path,
|  | plist_t | client_options,
|  | instproxy_status_cb_t | status_cb,
|  | void * | user_data
| ) |  |

Upgrade an application on the device.

This function is nearly the same as instproxy_install; the difference is that the installation progress on the device is faster if the application is already installed.

Parameters:

  client | The connected installation_proxy client
  pkg_path | Path of the installation package (inside the AFC jail)
  client_options | The client options to use, as PLIST_DICT, or NULL. Valid options include: "iTunesMetadata" -> PLIST_DATA "ApplicationSINF" -> PLIST_DATA "PackageType" -> "Developer" If PackageType -> Developer is specified, then pkg_path points to an .app directory instead of an install package.
  status_cb | Callback function for progress and status information. If NULL is passed, this function will run synchronously.
  user_data | Callback data passed to status_cb.

Returns:
  INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if an error occured.

Note:
  If a callback function is given (async mode), this function returns INSTPROXY_E_SUCCESS immediately if the status updater thread has been created successfully; any error occuring during the operation has to be handled inside the specified callback function.