libimobiledevice 1.1.1
Typedefs | Functions

libimobiledevice/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_privateinstproxy_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, uint16_t port, 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,...) G_GNUC_NULL_TERMINATED
 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

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:
clientThe connected installation proxy client
appidApplicationIdentifier of the app to archive.
client_optionsThe client options to use, as PLIST_DICT, or NULL. Valid options include: "SkipUninstall" -> Boolean "ArchiveType" -> "ApplicationOnly"
status_cbCallback function for progress and status information. If NULL is passed, this function will run synchronously.
user_dataCallback 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:
clientThe connected installation_proxy client
client_optionsThe client options to use, as PLIST_DICT, or NULL. Valid client options include: "ApplicationType" -> "User" "ApplicationType" -> "System"
resultPointer 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:
clientThe 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,
uint16_t  port,
instproxy_client_t client 
)

Connects to the installation_proxy service on the specified device.

Parameters:
deviceThe device to connect to
portDestination port (usually given by lockdownd_start_service).
clientPointer 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_optionsThe client options to modify.
...KEY, VALUE, [KEY, VALUE], NULL
Note:
The keys and values passed are expected to be strings, except for "ApplicationSINF" and "iTunesMetadata" expecting a plist node of type PLIST_DATA as value, or "SkipUninstall" needing int as value.
void instproxy_client_options_free ( plist_t  client_options)

Free client_options plist.

Parameters:
client_optionsThe 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:
clientThe connected installation_proxy client
pkg_pathPath of the installation package (inside the AFC jail)
client_optionsThe 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_cbCallback function for progress and status information. If NULL is passed, this function will run synchronously.
user_dataCallback 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:
clientThe connected installation_proxy client
client_optionsThe client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so pass NULL here.
resultPointer 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:
clientThe connected installation proxy client
appidApplicationIdentifier of the archived app to remove.
client_optionsThe client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so passing NULL is fine.
status_cbCallback function for progress and status information. If NULL is passed, this function will run synchronously.
user_dataCallback 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:
clientThe connected installation proxy client
appidApplicationIdentifier of the app to restore.
client_optionsThe client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so pass NULL here.
status_cbCallback function for progress and status information. If NULL is passed, this function will run synchronously.
user_dataCallback 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:
clientThe connected installation proxy client
appidApplicationIdentifier of the app to uninstall
client_optionsThe client options to use, as PLIST_DICT, or NULL. Currently there are no known client options, so pass NULL here.
status_cbCallback function for progress and status information. If NULL is passed, this function will run synchronously.
user_dataCallback 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:
clientThe connected installation_proxy client
pkg_pathPath of the installation package (inside the AFC jail)
client_optionsThe 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_cbCallback function for progress and status information. If NULL is passed, this function will run synchronously.
user_dataCallback 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.