diff options
Diffstat (limited to 'include/libimobiledevice')
20 files changed, 2701 insertions, 0 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h index 289c749..2f272e0 100644 --- a/include/libimobiledevice/afc.h +++ b/include/libimobiledevice/afc.h @@ -95,30 +95,263 @@ typedef struct afc_client_private afc_client_private; typedef afc_client_private *afc_client_t; /**< The client handle. */ /* Interface */ + +/** + * Makes a connection to the AFC service on the device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated afc_client_t + * upon successful return. + * + * @return AFC_E_SUCCESS on success, AFC_E_INVALID_ARG if device or service is + * invalid, AFC_E_MUX_ERROR if the connection cannot be established, + * or AFC_E_NO_MEM if there is a memory allocation problem. + */ afc_error_t afc_client_new(idevice_t device, lockdownd_service_descriptor_t service, afc_client_t *client); + +/** + * Starts a new AFC service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * afc_client_t upon successful return. Must be freed using + * afc_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return AFC_E_SUCCESS on success, or an AFC_E_* error + * code otherwise. + */ afc_error_t afc_client_start_service(idevice_t device, afc_client_t* client, const char* label); + +/** + * Frees up an AFC client. If the connection was created by the + * client itself, the connection will be closed. + * + * @param client The client to free. + */ afc_error_t afc_client_free(afc_client_t client); +/** + * Get device information for a connected client. The device information + * returned is the device model as well as the free space, the total capacity + * and blocksize on the accessed disk partition. + * + * @param client The client to get device info for. + * @param infos A char ** list of parameters as given by AFC or NULL if there + * was an error. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_get_device_info(afc_client_t client, char ***infos); + +/** + * Gets a directory listing of the directory requested. + * + * @param client The client to get a directory listing from. + * @param dir The directory to list. (must be a fully-qualified path) + * @param list A char list of files in that directory, terminated by an empty + * string or NULL if there was an error. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***list); + +/** + * Gets information about a specific file. + * + * @param client The client to use to get the information of the file. + * @param path The fully-qualified path to the file. + * @param infolist Pointer to a buffer that will be filled with a NULL-terminated + * list of strings with the file information. + * Set to NULL before calling this function. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_get_file_info(afc_client_t client, const char *filename, char ***infolist); + +/** + * Opens a file on the device. + * + * @param client The client to use to open the file. + * @param filename The file to open. (must be a fully-qualified path) + * @param file_mode The mode to use to open the file. Can be AFC_FILE_READ or + * AFC_FILE_WRITE; the former lets you read and write, + * however, and the second one will *create* the file, + * destroying anything previously there. + * @param handle Pointer to a uint64_t that will hold the handle of the file + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_file_open(afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle); + +/** + * Closes a file on the device. + * + * @param client The client to close the file with. + * @param handle File handle of a previously opened file. + */ afc_error_t afc_file_close(afc_client_t client, uint64_t handle); + +/** + * Locks or unlocks a file on the device. + * + * makes use of flock on the device, see + * http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/flock.2.html + * + * @param client The client to lock the file with. + * @param handle File handle of a previously opened file. + * @param operation the lock or unlock operation to perform, this is one of + * AFC_LOCK_SH (shared lock), AFC_LOCK_EX (exclusive lock), + * or AFC_LOCK_UN (unlock). + */ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t operation); + +/** + * Attempts to the read the given number of bytes from the given file. + * + * @param client The relevant AFC client + * @param handle File handle of a previously opened file + * @param data The pointer to the memory region to store the read data + * @param length The number of bytes to read + * @param bytes_read The number of bytes actually read. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read); + +/** + * Writes a given number of bytes to a file. + * + * @param client The client to use to write to the file. + * @param handle File handle of previously opened file. + * @param data The data to write to the file. + * @param length How much data to write. + * @param bytes_written The number of bytes actually written to the file. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written); + +/** + * Seeks to a given position of a pre-opened file on the device. + * + * @param client The client to use to seek to the position. + * @param handle File handle of a previously opened. + * @param offset Seek offset. + * @param whence Seeking direction, one of SEEK_SET, SEEK_CUR, or SEEK_END. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, int whence); + +/** + * Returns current position in a pre-opened file on the device. + * + * @param client The client to use. + * @param handle File handle of a previously opened file. + * @param position Position in bytes of indicator + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *position); + +/** + * Sets the size of a file on the device. + * + * @param client The client to use to set the file size. + * @param handle File handle of a previously opened file. + * @param newsize The size to set the file to. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + * + * @note This function is more akin to ftruncate than truncate, and truncate + * calls would have to open the file before calling this, sadly. + */ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t newsize); + +/** + * Deletes a file or directory. + * + * @param client The client to use. + * @param path The path to delete. (must be a fully-qualified path) + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_remove_path(afc_client_t client, const char *path); + +/** + * Renames a file or directory on the device. + * + * @param client The client to have rename. + * @param from The name to rename from. (must be a fully-qualified path) + * @param to The new name. (must also be a fully-qualified path) + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *to); + +/** + * Creates a directory on the device. + * + * @param client The client to use to make a directory. + * @param dir The directory's path. (must be a fully-qualified path, I assume + * all other mkdir restrictions apply as well) + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_make_directory(afc_client_t client, const char *dir); + +/** + * Sets the size of a file on the device without prior opening it. + * + * @param client The client to use to set the file size. + * @param path The path of the file to be truncated. + * @param newsize The size to set the file to. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize); + +/** + * Creates a hard link or symbolic link on the device. + * + * @param client The client to use for making a link + * @param linktype 1 = hard link, 2 = symlink + * @param target The file to be linked. + * @param linkname The name of link. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const char *target, const char *linkname); + +/** + * Sets the modification time of a file on the device. + * + * @param client The client to use to set the file size. + * @param path Path of the file for which the modification time should be set. + * @param mtime The modification time to set in nanoseconds since epoch. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_set_file_time(afc_client_t client, const char *path, uint64_t mtime); /* Helper functions */ + +/** + * Get a specific key of the device info list for a client connection. + * Known key values are: Model, FSTotalBytes, FSFreeBytes and FSBlockSize. + * This is a helper function for afc_get_device_info(). + * + * @param client The client to get device info for. + * @param key The key to get the value of. + * @param value The value for the key if successful or NULL otherwise. + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char **value); + afc_error_t afc_dictionary_free(char **dictionary); #ifdef __cplusplus diff --git a/include/libimobiledevice/diagnostics_relay.h b/include/libimobiledevice/diagnostics_relay.h index 17e73dd..b25750b 100644 --- a/include/libimobiledevice/diagnostics_relay.h +++ b/include/libimobiledevice/diagnostics_relay.h @@ -58,17 +58,128 @@ typedef int16_t diagnostics_relay_error_t; typedef struct diagnostics_relay_client_private diagnostics_relay_client_private; typedef diagnostics_relay_client_private *diagnostics_relay_client_t; /**< The client handle. */ +/** + * Connects to the diagnostics_relay service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Reference that will point to a newly allocated + * diagnostics_relay_client_t upon successful return. + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when one of the parameters is invalid, + * or DIAGNOSTICS_RELAY_E_MUX_ERROR when the connection failed. + */ diagnostics_relay_error_t diagnostics_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, diagnostics_relay_client_t *client); + +/** + * Starts a new diagnostics_relay service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * diagnostics_relay_client_t upon successful return. Must be freed using + * diagnostics_relay_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, or an DIAGNOSTICS_RELAY_E_* error + * code otherwise. + */ diagnostics_relay_error_t diagnostics_relay_client_start_service(idevice_t device, diagnostics_relay_client_t* client, const char* label); + +/** + * Disconnects a diagnostics_relay client from the device and frees up the + * diagnostics_relay client data. + * + * @param client The diagnostics_relay client to disconnect and free. + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when one of client or client->parent + * is invalid, or DIAGNOSTICS_RELAY_E_UNKNOWN_ERROR when the was an + * error freeing the parent property_list_service client. + */ diagnostics_relay_error_t diagnostics_relay_client_free(diagnostics_relay_client_t client); + +/** + * Sends the Goodbye request signaling the end of communication. + * + * @param client The diagnostics_relay client + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_goodbye(diagnostics_relay_client_t client); + +/** + * Puts the device into deep sleep mode and disconnects from host. + * + * @param client The diagnostics_relay client + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_sleep(diagnostics_relay_client_t client); + +/** + * Restart the device and optionally show a user notification. + * + * @param client The diagnostics_relay client + * @param flags A binary flag combination of + * DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT to wait until + * diagnostics_relay_client_free() disconnects before execution and + * DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL to show a "FAIL" dialog + * or DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS to show an "OK" dialog + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_restart(diagnostics_relay_client_t client, int flags); + +/** + * Shutdown of the device and optionally show a user notification. + * + * @param client The diagnostics_relay client + * @param flags A binary flag combination of + * DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT to wait until + * diagnostics_relay_client_free() disconnects before execution and + * DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL to show a "FAIL" dialog + * or DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS to show an "OK" dialog + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_shutdown(diagnostics_relay_client_t client, int flags); + +/** + * Shutdown of the device and optionally show a user notification. + * + * @param client The diagnostics_relay client + * @param flags A binary flag combination of + * DIAGNOSTICS_RELAY_ACTION_FLAG_WAIT_FOR_DISCONNECT to wait until + * diagnostics_relay_client_free() disconnects before execution and + * DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_FAIL to show a "FAIL" dialog + * or DIAGNOSTICS_RELAY_ACTION_FLAG_DISPLAY_PASS to show an "OK" dialog + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client is NULL, + * DIAGNOSTICS_RELAY_E_PLIST_ERROR if the device did not acknowledge the + * request + */ diagnostics_relay_error_t diagnostics_relay_request_diagnostics(diagnostics_relay_client_t client, const char* type, plist_t* diagnostics); + diagnostics_relay_error_t diagnostics_relay_query_mobilegestalt(diagnostics_relay_client_t client, plist_t keys, plist_t* result); + diagnostics_relay_error_t diagnostics_relay_query_ioregistry_entry(diagnostics_relay_client_t client, const char* name, const char* class, plist_t* result); + diagnostics_relay_error_t diagnostics_relay_query_ioregistry_plane(diagnostics_relay_client_t client, const char* plane, plist_t* result); #ifdef __cplusplus diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h index d197f2e..f9318bd 100644 --- a/include/libimobiledevice/file_relay.h +++ b/include/libimobiledevice/file_relay.h @@ -50,11 +50,113 @@ typedef int16_t file_relay_error_t; typedef struct file_relay_client_private file_relay_client_private; typedef file_relay_client_private *file_relay_client_t; /**< The client handle. */ +/** + * Connects to the file_relay service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Reference that will point to a newly allocated + * file_relay_client_t upon successful return. + * + * @return FILE_RELAY_E_SUCCESS on success, + * FILE_RELAY_E_INVALID_ARG when one of the parameters is invalid, + * or FILE_RELAY_E_MUX_ERROR when the connection failed. + */ file_relay_error_t file_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, file_relay_client_t *client); + +/** + * Starts a new file_relay service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * file_relay_client_t upon successful return. Must be freed using + * file_relay_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return FILE_RELAY_E_SUCCESS on success, or an FILE_RELAY_E_* error + * code otherwise. + */ file_relay_error_t file_relay_client_start_service(idevice_t device, file_relay_client_t* client, const char* label); + +/** + * Disconnects a file_relay client from the device and frees up the file_relay + * client data. + * + * @param client The file_relay client to disconnect and free. + * + * @return FILE_RELAY_E_SUCCESS on success, + * FILE_RELAY_E_INVALID_ARG when one of client or client->parent + * is invalid, or FILE_RELAY_E_UNKNOWN_ERROR when the was an error + * freeing the parent property_list_service client. + */ file_relay_error_t file_relay_client_free(file_relay_client_t client); + +/** + * Request data for the given sources. + * + * @param client The connected file_relay client. + * @param sources A NULL-terminated list of sources to retrieve. + * Valid sources are: + * - AppleSupport + * - Network + * - VPN + * - WiFi + * - UserDatabases + * - CrashReporter + * - tmp + * - SystemConfiguration + * @param connection The connection that has to be used for receiving the + * data using idevice_connection_receive(). The connection will be closed + * automatically by the device, but use file_relay_client_free() to clean + * up properly. + * @param timeout Maximum time in milliseconds to wait for data. + * + * @note WARNING: Don't call this function without reading the data afterwards. + * A directory mobile_file_relay.XXXX used for creating the archive will + * remain in the /tmp directory otherwise. + * + * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or + * more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication + * error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL + * or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more + * sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available + * for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise. + */ file_relay_error_t file_relay_request_sources(file_relay_client_t client, const char **sources, idevice_connection_t *connection); + +/** + * Request data for the given sources. Calls file_relay_request_sources_timeout() with + * a timeout of 60000 milliseconds (60 seconds). + * + * @param client The connected file_relay client. + * @param sources A NULL-terminated list of sources to retrieve. + * Valid sources are: + * - AppleSupport + * - Network + * - VPN + * - WiFi + * - UserDatabases + * - CrashReporter + * - tmp + * - SystemConfiguration + * @param connection The connection that has to be used for receiving the + * data using idevice_connection_receive(). The connection will be closed + * automatically by the device, but use file_relay_client_free() to clean + * up properly. + * + * @note WARNING: Don't call this function without reading the data afterwards. + * A directory mobile_file_relay.XXXX used for creating the archive will + * remain in the /tmp directory otherwise. + * + * @return FILE_RELAY_E_SUCCESS on succes, FILE_RELAY_E_INVALID_ARG when one or + * more parameters are invalid, FILE_RELAY_E_MUX_ERROR if a communication + * error occurs, FILE_RELAY_E_PLIST_ERROR when the received result is NULL + * or is not a valid plist, FILE_RELAY_E_INVALID_SOURCE if one or more + * sources are invalid, FILE_RELAY_E_STAGING_EMPTY if no data is available + * for the given sources, or FILE_RELAY_E_UNKNOWN_ERROR otherwise. + */ file_relay_error_t file_relay_request_sources_timeout(file_relay_client_t client, const char **sources, idevice_connection_t *connection, unsigned int timeout); #ifdef __cplusplus diff --git a/include/libimobiledevice/heartbeat.h b/include/libimobiledevice/heartbeat.h index 8db2941..c943e51 100644 --- a/include/libimobiledevice/heartbeat.h +++ b/include/libimobiledevice/heartbeat.h @@ -48,12 +48,84 @@ typedef int16_t heartbeat_error_t; typedef struct heartbeat_client_private heartbeat_client_private; typedef heartbeat_client_private *heartbeat_client_t; /**< The client handle. */ +/** + * Connects to the heartbeat service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * heartbeat_client_t upon successful return. Must be freed using + * heartbeat_client_free() after use. + * + * @return HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when + * client is NULL, or an HEARTBEAT_E_* error code otherwise. + */ heartbeat_error_t heartbeat_client_new(idevice_t device, lockdownd_service_descriptor_t service, heartbeat_client_t * client); + +/** + * Starts a new heartbeat service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * heartbeat_client_t upon successful return. Must be freed using + * heartbeat_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return HEARTBEAT_E_SUCCESS on success, or an HEARTBEAT_E_* error + * code otherwise. + */ heartbeat_error_t heartbeat_client_start_service(idevice_t device, heartbeat_client_t * client, const char* label); + +/** + * Disconnects a heartbeat client from the device and frees up the + * heartbeat client data. + * + * @param client The heartbeat client to disconnect and free. + * + * @return HEARTBEAT_E_SUCCESS on success, HEARTBEAT_E_INVALID_ARG when + * client is NULL, or an HEARTBEAT_E_* error code otherwise. + */ heartbeat_error_t heartbeat_client_free(heartbeat_client_t client); + +/** + * Sends a plist to the service. + * + * @param client The heartbeat client + * @param plist The plist to send + * + * @return HEARTBEAT_E_SUCCESS on success, + * HEARTBEAT_E_INVALID_ARG when client or plist is NULL + */ heartbeat_error_t heartbeat_send(heartbeat_client_t client, plist_t plist); + +/** + * Receives a plist from the service. + * + * @param client The heartbeat client + * @param plist The plist to store the received data + * + * @return HEARTBEAT_E_SUCCESS on success, + * HEARTBEAT_E_INVALID_ARG when client or plist is NULL + */ heartbeat_error_t heartbeat_receive(heartbeat_client_t client, plist_t * plist); + +/** + * Receives a plist using the given heartbeat client. + * + * @param client The heartbeat client to use for receiving + * @param plist pointer to a plist_t that will point to the received plist + * upon successful return + * @param timeout Maximum time in milliseconds to wait for data. + * + * @return HEARTBEAT_E_SUCCESS on success, + * HEARTBEAT_E_INVALID_ARG when client or *plist is NULL, + * HEARTBEAT_E_PLIST_ERROR when the received data cannot be + * converted to a plist, HEARTBEAT_E_MUX_ERROR when a + * communication error occurs, or HEARTBEAT_E_UNKNOWN_ERROR + * when an unspecified error occurs. + */ heartbeat_error_t heartbeat_receive_with_timeout(heartbeat_client_t client, plist_t * plist, uint32_t timeout_ms); #ifdef __cplusplus diff --git a/include/libimobiledevice/house_arrest.h b/include/libimobiledevice/house_arrest.h index ccd6ac7..170cad2 100644 --- a/include/libimobiledevice/house_arrest.h +++ b/include/libimobiledevice/house_arrest.h @@ -51,14 +51,128 @@ typedef struct house_arrest_client_private house_arrest_client_private; typedef house_arrest_client_private *house_arrest_client_t; /**< The client handle. */ /* Interface */ + +/** + * Connects to the house_arrest service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * housearrest_client_t upon successful return. + * + * @return HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when + * client is NULL, or an HOUSE_ARREST_E_* error code otherwise. + */ house_arrest_error_t house_arrest_client_new(idevice_t device, lockdownd_service_descriptor_t service, house_arrest_client_t *client); + +/** + * Starts a new house_arrest service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * house_arrest_client_t upon successful return. Must be freed using + * house_arrest_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return HOUSE_ARREST_E_SUCCESS on success, or an HOUSE_ARREST_E_* error + * code otherwise. + */ house_arrest_error_t house_arrest_client_start_service(idevice_t device, house_arrest_client_t* client, const char* label); + +/** + * Disconnects an house_arrest client from the device and frees up the + * house_arrest client data. + * + * @note After using afc_client_new_from_house_arrest_client(), make sure + * you call afc_client_free() before calling this function to ensure + * a proper cleanup. Do not call this function if you still need to + * perform AFC operations since it will close the connection. + * + * @param client The house_arrest client to disconnect and free. + * + * @return HOUSE_ARREST_E_SUCCESS on success, HOUSE_ARREST_E_INVALID_ARG when + * client is NULL, or an HOUSE_ARREST_E_* error code otherwise. + */ house_arrest_error_t house_arrest_client_free(house_arrest_client_t client); + +/** + * Sends a generic request to the connected house_arrest service. + * + * @param client The house_arrest client to use. + * @param dict The request to send as a plist of type PLIST_DICT. + * + * @note If this function returns HOUSE_ARREST_E_SUCCESS it does not mean + * that the request was successful. To check for success or failure you + * need to call house_arrest_get_result(). + * @see house_arrest_get_result + * + * @return HOUSE_ARREST_E_SUCCESS if the request was successfully sent, + * HOUSE_ARREST_E_INVALID_ARG if client or dict is invalid, + * HOUSE_ARREST_E_PLIST_ERROR if dict is not a plist of type PLIST_DICT, + * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, + * or HOUSE_ARREST_E_CONN_FAILED if a connection error occured. + */ house_arrest_error_t house_arrest_send_request(house_arrest_client_t client, plist_t dict); + +/** + * Send a command to the connected house_arrest service. + * Calls house_arrest_send_request() internally. + * + * @param client The house_arrest client to use. + * @param command The command to send. Currently, only VendContainer and + * VendDocuments are known. + * @param appid The application identifier to pass along with the . + * + * @note If this function returns HOUSE_ARREST_E_SUCCESS it does not mean + * that the command was successful. To check for success or failure you + * need to call house_arrest_get_result(). + * @see house_arrest_get_result + * + * @return HOUSE_ARREST_E_SUCCESS if the command was successfully sent, + * HOUSE_ARREST_E_INVALID_ARG if client, command, or appid is invalid, + * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, + * or HOUSE_ARREST_E_CONN_FAILED if a connection error occured. + */ house_arrest_error_t house_arrest_send_command(house_arrest_client_t client, const char *command, const char *appid); + +/** + * Retrieves the result of a previously sent house_arrest_request_* request. + * + * @param client The house_arrest client to use + * @param dict Pointer that will be set to a plist containing the result to + * the last performed operation. It holds a key 'Status' with the value + * 'Complete' on success or a key 'Error' with an error description as + * value. The caller is responsible for freeing the returned plist. + * + * @return HOUSE_ARREST_E_SUCCESS if a result plist was retrieved, + * HOUSE_ARREST_E_INVALID_ARG if client is invalid, + * HOUSE_ARREST_E_INVALID_MODE if the client is not in the correct mode, + * or HOUSE_ARREST_E_CONN_FAILED if a connection error occured. + */ house_arrest_error_t house_arrest_get_result(house_arrest_client_t client, plist_t *dict); + +/** + * Creates an AFC client using the given house_arrest client's connection + * allowing file access to a specific application directory requested by + * functions like house_arrest_request_vendor_documents(). + * + * @param client The house_arrest client to use. + * @param afc_client Pointer that will be set to a newly allocated afc_client_t + * upon successful return. + * + * @note After calling this function the house_arrest client will go in an + * AFC mode that will only allow calling house_arrest_client_free(). + * Only call house_arrest_client_free() if all AFC operations have + * completed since it will close the connection. + * + * @return AFC_E_SUCCESS if the afc client was successfully created, + * AFC_E_INVALID_ARG if client is invalid or was already used to create + * an afc client, or an AFC_E_* error code returned by + * afc_client_new_with_service_client(). + */ afc_error_t afc_client_new_from_house_arrest_client(house_arrest_client_t client, afc_client_t *afc_client); #ifdef __cplusplus diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h index 18b7804..4740b20 100644 --- a/include/libimobiledevice/installation_proxy.h +++ b/include/libimobiledevice/installation_proxy.h @@ -55,24 +55,271 @@ 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); /* Interface */ + +/** + * Connects to the installation_proxy service on the specified device. + * + * @param device The device to connect to + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * instproxy_client_t upon successful return. + * + * @return INSTPROXY_E_SUCCESS on success, or an INSTPROXY_E_* error value + * when an error occured. + */ instproxy_error_t instproxy_client_new(idevice_t device, lockdownd_service_descriptor_t service, instproxy_client_t *client); + +/** + * Starts a new installation_proxy service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * instproxy_client_t upon successful return. Must be freed using + * instproxy_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return INSTPROXY_E_SUCCESS on success, or an INSTPROXY_E_* error + * code otherwise. + */ instproxy_error_t instproxy_client_start_service(idevice_t device, instproxy_client_t * client, const char* label); + +/** + * Disconnects an installation_proxy client from the device and frees up the + * installation_proxy client data. + * + * @param client The installation_proxy client to disconnect and free. + * + * @return INSTPROXY_E_SUCCESS on success + * or INSTPROXY_E_INVALID_ARG if client is NULL. + */ instproxy_error_t instproxy_client_free(instproxy_client_t client); + +/** + * List installed applications. This function runs synchronously. + * + * @param client The connected installation_proxy client + * @param client_options The client options to use, as PLIST_DICT, or NULL. + * Valid client options include: + * "ApplicationType" -> "User" + * "ApplicationType" -> "System" + * @param result Pointer that will be set to a plist that will hold an array + * of PLIST_DICT holding information about the applications found. + * + * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if + * an error occured. + */ instproxy_error_t instproxy_browse(instproxy_client_t client, plist_t client_options, plist_t *result); + +/** + * Install an application on the device. + * + * @param client The connected installation_proxy client + * @param pkg_path Path of the installation package (inside the AFC jail) + * @param 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. + * @param status_cb Callback function for progress and status information. If + * NULL is passed, this function will run synchronously. + * @param user_data Callback data passed to status_cb. + * + * @return 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_install(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. + * + * @param client The connected installation_proxy client + * @param pkg_path Path of the installation package (inside the AFC jail) + * @param 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. + * @param status_cb Callback function for progress and status information. If + * NULL is passed, this function will run synchronously. + * @param user_data Callback data passed to status_cb. + * + * @return 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); + +/** + * Uninstall an application from the device. + * + * @param client The connected installation proxy client + * @param appid ApplicationIdentifier of the app to uninstall + * @param client_options The client options to use, as PLIST_DICT, or NULL. + * Currently there are no known client options, so pass NULL here. + * @param status_cb Callback function for progress and status information. If + * NULL is passed, this function will run synchronously. + * @param user_data Callback data passed to status_cb. + * + * @return 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); + +/** + * List archived applications. This function runs synchronously. + * + * @see instproxy_archive + * + * @param client The connected installation_proxy client + * @param client_options The client options to use, as PLIST_DICT, or NULL. + * Currently there are no known client options, so pass NULL here. + * @param result Pointer that will be set to a plist containing a PLIST_DICT + * holding information about the archived applications found. + * + * @return INSTPROXY_E_SUCCESS on success or an INSTPROXY_E_* error value if + * an error occured. + */ instproxy_error_t instproxy_lookup_archives(instproxy_client_t client, plist_t client_options, plist_t *result); + +/** + * 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. + * + * @param client The connected installation proxy client + * @param appid ApplicationIdentifier of the app to archive. + * @param client_options The client options to use, as PLIST_DICT, or NULL. + * Valid options include: + * "SkipUninstall" -> Boolean + * "ArchiveType" -> "ApplicationOnly" + * @param status_cb Callback function for progress and status information. If + * NULL is passed, this function will run synchronously. + * @param user_data Callback data passed to status_cb. + * + * @return 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_archive(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 instproxy_archive + * + * @param client The connected installation proxy client + * @param appid ApplicationIdentifier of the app to restore. + * @param client_options The client options to use, as PLIST_DICT, or NULL. + * Currently there are no known client options, so pass NULL here. + * @param status_cb Callback function for progress and status information. If + * NULL is passed, this function will run synchronously. + * @param user_data Callback data passed to status_cb. + * + * @return 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); + +/** + * Removes a previously archived application from the device. + * This function removes the ZIP archive from the 'ApplicationArchives' + * directory. + * + * @param client The connected installation proxy client + * @param appid ApplicationIdentifier of the archived app to remove. + * @param client_options The client options to use, as PLIST_DICT, or NULL. + * Currently there are no known client options, so passing NULL is fine. + * @param status_cb Callback function for progress and status information. If + * NULL is passed, this function will run synchronously. + * @param user_data Callback data passed to status_cb. + * + * @return 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_remove_archive(instproxy_client_t client, const char *appid, plist_t client_options, instproxy_status_cb_t status_cb, void *user_data); /* Helper */ + +/** + * Create a new client_options plist. + * + * @return A new plist_t of type PLIST_DICT. + */ plist_t instproxy_client_options_new(); + +/** + * Add one or more new key:value pairs to the given client_options. + * + * @param client_options The client options to modify. + * @param ... 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_add(plist_t client_options, ...); + +/** + * Free client_options plist. + * + * @param client_options The client options plist to free. Does nothing if NULL + * is passed. + */ void instproxy_client_options_free(plist_t client_options); + +/** + * Query the device for the path of an application. + * + * @param client The connected installation proxy client. + * @param appid ApplicationIdentifier of app to retrieve the path for. + * @param path Pointer to store the device path for the application + * which is set to NULL if it could not be determined. + * + * @return INSTPROXY_E_SUCCESS on success, INSTPROXY_E_OP_FAILED if + * the path could not be determined or an INSTPROXY_E_* error + * value if an error occured. + * + * @note This implementation browses all applications and matches the + * right entry by the application identifier. + */ instproxy_error_t instproxy_client_get_path_for_bundle_identifier(instproxy_client_t client, const char* bundle_id, char** path); #ifdef __cplusplus diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h index e33715f..3cbb96b 100644 --- a/include/libimobiledevice/libimobiledevice.h +++ b/include/libimobiledevice/libimobiledevice.h @@ -75,30 +75,177 @@ typedef struct { typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data); /* functions */ + +/** + * Register a callback function that will be called when device add/remove + * events occur. + * + * @param callback Callback function to call. + * @param user_data Application-specific data passed as parameter + * to the registered callback function. + * + * @return IDEVICE_E_SUCCESS on success or an error value when an error occured. + */ idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data); + +/** + * Release the event callback function that has been registered with + * idevice_event_subscribe(). + * + * @return IDEVICE_E_SUCCESS on success or an error value when an error occured. + */ idevice_error_t idevice_event_unsubscribe(); /* discovery (synchronous) */ + +/** + * Get a list of currently available devices. + * + * @param devices List of udids of devices that are currently available. + * This list is terminated by a NULL pointer. + * @param count Number of devices found. + * + * @return IDEVICE_E_SUCCESS on success or an error value when an error occured. + */ idevice_error_t idevice_get_device_list(char ***devices, int *count); + +/** + * Free a list of device udids. + * + * @param devices List of udids to free. + * + * @return Always returnes IDEVICE_E_SUCCESS. + */ idevice_error_t idevice_device_list_free(char **devices); /* device structure creation and destruction */ + +/** + * Creates an idevice_t structure for the device specified by udid, + * if the device is available. + * + * @note The resulting idevice_t structure has to be freed with + * idevice_free() if it is no longer used. + * + * @param device Upon calling this function, a pointer to a location of type + * idevice_t. On successful return, this location will be populated. + * @param udid The UDID to match. + * + * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. + */ idevice_error_t idevice_new(idevice_t *device, const char *udid); + +/** + * Cleans up an idevice structure, then frees the structure itself. + * This is a library-level function; deals directly with the device to tear + * down relations, but otherwise is mostly internal. + * + * @param device idevice_t to free. + */ idevice_error_t idevice_free(idevice_t device); /* connection/disconnection */ + +/** + * Set up a connection to the given device. + * + * @param device The device to connect to. + * @param port The destination port to connect to. + * @param connection Pointer to an idevice_connection_t that will be filled + * with the necessary data of the connection. + * + * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. + */ idevice_error_t idevice_connect(idevice_t device, uint16_t port, idevice_connection_t *connection); + +/** + * Disconnect from the device and clean up the connection structure. + * + * @param connection The connection to close. + * + * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. + */ idevice_error_t idevice_disconnect(idevice_connection_t connection); /* communication */ + +/** + * Send data to a device via the given connection. + * + * @param connection The connection to send data over. + * @param data Buffer with data to send. + * @param len Size of the buffer to send. + * @param sent_bytes Pointer to an uint32_t that will be filled + * with the number of bytes actually sent. + * + * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. + */ idevice_error_t idevice_connection_send(idevice_connection_t connection, const char *data, uint32_t len, uint32_t *sent_bytes); + +/** + * Receive data from a device via the given connection. + * This function will return after the given timeout even if no data has been + * received. + * + * @param connection The connection to receive data from. + * @param data Buffer that will be filled with the received data. + * This buffer has to be large enough to hold len bytes. + * @param len Buffer size or number of bytes to receive. + * @param recv_bytes Number of bytes actually received. + * @param timeout Timeout in milliseconds after which this function should + * return even if no data has been received. + * + * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. + */ idevice_error_t idevice_connection_receive_timeout(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes, unsigned int timeout); + +/** + * Receive data from a device via the given connection. + * This function is like idevice_connection_receive_timeout, but with a + * predefined reasonable timeout. + * + * @param connection The connection to receive data from. + * @param data Buffer that will be filled with the received data. + * This buffer has to be large enough to hold len bytes. + * @param len Buffer size or number of bytes to receive. + * @param recv_bytes Number of bytes actually received. + * + * @return IDEVICE_E_SUCCESS if ok, otherwise an error code. + */ idevice_error_t idevice_connection_receive(idevice_connection_t connection, char *data, uint32_t len, uint32_t *recv_bytes); + +/** + * Enables SSL for the given connection. + * + * @param connection The connection to enable SSL for. + * + * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection + * is NULL or connection->ssl_data is non-NULL, or IDEVICE_E_SSL_ERROR when + * SSL initialization, setup, or handshake fails. + */ idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection); + +/** + * Disable SSL for the given connection. + * + * @param connection The connection to disable SSL for. + * + * @return IDEVICE_E_SUCCESS on success, IDEVICE_E_INVALID_ARG when connection + * is NULL. This function also returns IDEVICE_E_SUCCESS when SSL is not + * enabled and does no further error checking on cleanup. + */ idevice_error_t idevice_connection_disable_ssl(idevice_connection_t connection); /* misc */ + +/** + * Gets the handle of the device. Depends on the connection type. + */ idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle); + +/** + * Gets the unique id for the device. + */ idevice_error_t idevice_get_udid(idevice_t device, char **udid); #ifdef __cplusplus diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h index 233c796..d59c489 100644 --- a/include/libimobiledevice/lockdown.h +++ b/include/libimobiledevice/lockdown.h @@ -81,33 +81,335 @@ struct lockdownd_service_descriptor { typedef struct lockdownd_service_descriptor *lockdownd_service_descriptor_t; /* Interface */ + +/** + * Creates a new lockdownd client for the device. + * + * @note This function does not pair with the device or start a session. This + * has to be done manually by the caller after the client is created. + * The device disconnects automatically if the lockdown connection idles + * for more than 10 seconds. Make sure to call lockdownd_client_free() as soon + * as the connection is no longer needed. + * + * @param device The device to create a lockdownd client for + * @param client The pointer to the location of the new lockdownd_client + * @param label The label to use for communication. Usually the program name. + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *client, const char *label); + +/** + * Creates a new lockdownd client for the device and starts initial handshake. + * The handshake consists out of query_type, validate_pair, pair and + * start_session calls. It uses the internal pairing record management. + * + * @note The device disconnects automatically if the lockdown connection idles + * for more than 10 seconds. Make sure to call lockdownd_client_free() as soon + * as the connection is no longer needed. + * + * @param device The device to create a lockdownd client for + * @param client The pointer to the location of the new lockdownd_client + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_INVALID_CONF if configuration data is wrong + */ lockdownd_error_t lockdownd_client_new_with_handshake(idevice_t device, lockdownd_client_t *client, const char *label); + +/** + * Closes the lockdownd client session if one is running and frees up the + * lockdownd_client struct. + * + * @param client The lockdown client + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ lockdownd_error_t lockdownd_client_free(lockdownd_client_t client); + +/** + * 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. + * + * @param client The lockdownd client + * @param type The type returned by the service daemon. Pass NULL to ignore. + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type); + +/** + * Retrieves a preferences plist using an optional domain and/or key name. + * + * @param client An initialized lockdownd client. + * @param domain The domain to query on or NULL for global domain + * @param key The key name to request or NULL to query for all keys + * @param value A plist node representing the result value node + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *domain, const char *key, plist_t *value); + +/** + * Sets a preferences value using a plist and optional by domain and/or key name. + * + * @param client an initialized lockdownd client. + * @param domain the domain to query on or NULL for global domain + * @param key the key name to set the value or NULL to set a value dict plist + * @param value a plist node of any node type representing the value to set + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * value is NULL + */ lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *domain, const char *key, plist_t value); + +/** + * Removes a preference node by domain and/or key name. + * + * @note: Use with caution as this could remove vital information on the device + * + * @param client An initialized lockdownd client. + * @param domain The domain to query on or NULL for global domain + * @param key The key name to remove or NULL remove all keys for the current domain + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char *domain, const char *key); + +/** + * Requests to start a service and retrieve it's port on success. + * + * @param client The lockdownd client + * @param identifier The identifier of the service to start + * @param descriptor The service descriptor on success or NULL on failure + + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter + * is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known + * by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not because + * started by the device + */ lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char *identifier, lockdownd_service_descriptor_t *service); + +/** + * Opens a session with lockdownd and switches to SSL mode if device wants it. + * + * @param client The lockdownd client + * @param host_id The HostID of the computer + * @param session_id The new session_id of the created session + * @param ssl_enabled Whether SSL communication is used in the session + * + * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when a client + * or host_id is NULL, LOCKDOWN_E_PLIST_ERROR if the response plist had errors, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the supplied HostID, + * LOCKDOWN_E_SSL_ERROR if enabling SSL communication failed + */ lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled); + +/** + * Closes the lockdownd session by sending the StopSession request. + * + * @see lockdownd_start_session + * + * @param client The lockdown client + * @param session_id The id of a running session + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ lockdownd_error_t lockdownd_stop_session(lockdownd_client_t client, const char *session_id); + +/** + * Sends a plist to lockdownd. + * + * @note This function is low-level and should only be used if you need to send + * a new type of message. + * + * @param client The lockdownd client + * @param plist The plist to send + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL + */ lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist); + +/** + * Receives a plist from lockdownd. + * + * @param client The lockdownd client + * @param plist The plist to store the received data + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL + */ lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist); + +/** + * Pairs the device using the supplied pair record. + * + * @param client The lockdown client to pair with. + * @param pair_record The pair record to use for pairing. If NULL is passed, then + * the pair records from the current machine are used. New records will be + * generated automatically when pairing is done for the first time. + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, + * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, + * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id + */ lockdownd_error_t lockdownd_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); + +/** + * Validates if the device is paired with the given HostID. If succeeded them + * specified host will become trusted host of the device indicated by the + * lockdownd preference named TrustedHostAttached. Otherwise the host must because + * paired using lockdownd_pair() first. + * + * @param client The lockdown client to pair with. + * @param pair_record The pair record to validate pairing with. If NULL is + * passed, then the pair record is read from the internal pairing record + * management. + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, + * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, + * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id + */ lockdownd_error_t lockdownd_validate_pair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); + +/** + * Unpairs the device with the given HostID and removes the pairing records + * from the device and host if the internal pairing record management is used. + * + * @param client The lockdown client to pair with. + * @param pair_record The pair record to use for unpair. If NULL is passed, then + * the pair records from the current machine are used. + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, + * LOCKDOWN_E_PAIRING_FAILED if the pairing failed, + * LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, + * LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id + */ lockdownd_error_t lockdownd_unpair(lockdownd_client_t client, lockdownd_pair_record_t pair_record); + +/** + * Activates the device. Only works within an open session. + * The ActivationRecord plist dictionary must be obtained using the + * activation protocol requesting from Apple's https webservice. + * + * @see http://iphone-docs.org/doku.php?id=docs:protocols:activation + * + * @param client The lockdown client + * @param activation_record The activation record plist dictionary + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * activation_record is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is + * open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken, + * LOCKDOWN_E_ACTIVATION_FAILED if the activation failed, + * LOCKDOWN_E_INVALID_ACTIVATION_RECORD if the device reports that the + * activation_record is invalid + */ lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record); + +/** + * Deactivates the device, returning it to the locked “Activate with iTunes” + * screen. + * + * @param client The lockdown client + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, + * LOCKDOWN_E_PLIST_ERROR if the received plist is broken + */ lockdownd_error_t lockdownd_deactivate(lockdownd_client_t client); + +/** + * Tells the device to immediately enter recovery mode. + * + * @param client The lockdown client + * + * @return LOCKDOWN_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client); + +/** + * Sends the Goodbye request to lockdownd signaling the end of communication. + * + * @param client The lockdown client + * + * @return LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client + * is NULL, LOCKDOWN_E_PLIST_ERROR if the device did not acknowledge the + * request + */ lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client); /* Helper */ + +/** + * Sets the label to send for requests to lockdownd. + * + * @param client The lockdown client + * @param label The label to set or NULL to disable sending a label + * + */ void lockdownd_client_set_label(lockdownd_client_t client, const char *label); + +/** + * Returns the unique id of the device from lockdownd. + * + * @param client An initialized lockdownd client. + * @param udid Holds the unique id of the device. The caller is responsible + * for freeing the memory. + * + * @return LOCKDOWN_E_SUCCESS on success + */ lockdownd_error_t lockdownd_get_device_udid(lockdownd_client_t control, char **udid); + +/** + * Retrieves the name of the device from lockdownd set by the user. + * + * @param client An initialized lockdownd client. + * @param device_name Holds the name of the device. The caller is + * responsible for freeing the memory. + * + * @return LOCKDOWN_E_SUCCESS on success + */ lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **device_name); + +/** + * Calculates and returns the data classes the device supports from lockdownd. + * + * @param client An initialized lockdownd client. + * @param classes A pointer to store an array of class names. The caller is responsible + * for freeing the memory which can be done using mobilesync_data_classes_free(). + * @param count The number of items in the classes array. + * + * @return LOCKDOWN_E_SUCCESS on success, + * LOCKDOWN_E_INVALID_ARG when client is NULL, + * LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, + * LOCKDOWN_E_PLIST_ERROR if the received plist is broken + */ lockdownd_error_t lockdownd_get_sync_data_classes(lockdownd_client_t client, char ***classes, int *count); + +/** + * Frees memory of an allocated array of data classes as returned by lockdownd_get_sync_data_classes() + * + * @param classes An array of class names to free. + * + * @return LOCKDOWN_E_SUCCESS on success + */ lockdownd_error_t lockdownd_data_classes_free(char **classes); + +/** + * Frees memory of a service descriptor as returned by lockdownd_start_service() + * + * @param sevice A service descriptor instance to free. + * + * @return LOCKDOWN_E_SUCCESS on success + */ lockdownd_error_t lockdownd_service_descriptor_free(lockdownd_service_descriptor_t service); #ifdef __cplusplus diff --git a/include/libimobiledevice/misagent.h b/include/libimobiledevice/misagent.h index fe0acb2..7bb7333 100644 --- a/include/libimobiledevice/misagent.h +++ b/include/libimobiledevice/misagent.h @@ -50,13 +50,95 @@ typedef struct misagent_client_private misagent_client_private; typedef misagent_client_private *misagent_client_t; /**< The client handle. */ /* Interface */ + +/** + * Connects to the misagent service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * misagent_client_t upon successful return. + * + * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when + * client is NULL, or an MISAGENT_E_* error code otherwise. + */ misagent_error_t misagent_client_new(idevice_t device, lockdownd_service_descriptor_t service, misagent_client_t *client); + +/** + * Starts a new misagent service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * misagent_client_t upon successful return. Must be freed using + * misagent_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return MISAGENT_E_SUCCESS on success, or an MISAGENT_E_* error + * code otherwise. + */ misagent_error_t misagent_client_start_service(idevice_t device, misagent_client_t* client, const char* label); + +/** + * Disconnects an misagent client from the device and frees up the + * misagent client data. + * + * @param client The misagent client to disconnect and free. + * + * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when + * client is NULL, or an MISAGENT_E_* error code otherwise. + */ misagent_error_t misagent_client_free(misagent_client_t client); + +/** + * Installs the given provisioning profile. Only works with valid profiles. + * + * @param client The connected misagent to use for installation + * @param profile The valid provisioning profile to install. This has to be + * passed as a PLIST_DATA, otherwise the function will fail. + * + * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when + * client is invalid, or an MISAGENT_E_* error code otherwise. + */ misagent_error_t misagent_install(misagent_client_t client, plist_t profile); + +/** + * Retrieves an array of all installed provisioning profiles. + * + * @param client The connected misagent to use. + * @param profiles Pointer to a plist_t that will be set to a PLIST_ARRAY + * if the function is successful. + * + * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when + * client is invalid, or an MISAGENT_E_* error code otherwise. + * + * @note If no provisioning profiles are installed on the device, this function + * still returns MISAGENT_E_SUCCESS and profiles will just point to an + * empty array. + */ misagent_error_t misagent_copy(misagent_client_t client, plist_t* profiles); + +/** + * Removes a given provisioning profile. + * + * @param client The connected misagent to use. + * @param profileID Identifier of the provisioning profile to remove. + * This is a UUID that can be obtained from the provisioning profile data. + * @see misagent_copy + * + * @return MISAGENT_E_SUCCESS on success, MISAGENT_E_INVALID_ARG when + * client is invalid, or an MISAGENT_E_* error code otherwise. + */ misagent_error_t misagent_remove(misagent_client_t client, const char* profileID); + +/** + * Retrieves the status code from the last operation. + * + * @param client The misagent to use. + * + * @return -1 if client is invalid, or the status code from the last operation + */ int misagent_get_status_code(misagent_client_t client); #ifdef __cplusplus diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h index 560fec6..569b288 100644 --- a/include/libimobiledevice/mobile_image_mounter.h +++ b/include/libimobiledevice/mobile_image_mounter.h @@ -53,13 +53,113 @@ typedef mobile_image_mounter_client_private *mobile_image_mounter_client_t; /**< typedef ssize_t (*mobile_image_mounter_upload_cb_t) (void* buffer, size_t length, void *user_data); /* Interface */ + +/** + * Connects to the mobile_image_mounter service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * mobile_image_mounter_client_t upon successful return. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if device is NULL, + * or MOBILE_IMAGE_MOUNTER_E_CONN_FAILED if the connection to the + * device could not be established. + */ mobile_image_mounter_error_t mobile_image_mounter_new(idevice_t device, lockdownd_service_descriptor_t service, mobile_image_mounter_client_t *client); + +/** + * Starts a new mobile_image_mounter service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * mobile_image_mounter_t upon successful return. Must be freed using + * mobile_image_mounter_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an MOBILE_IMAGE_MOUNTER_E_* error + * code otherwise. + */ mobile_image_mounter_error_t mobile_image_mounter_start_service(idevice_t device, mobile_image_mounter_client_t* client, const char* label); + +/** + * Disconnects a mobile_image_mounter client from the device and frees up the + * mobile_image_mounter client data. + * + * @param client The mobile_image_mounter client to disconnect and free. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is NULL. + */ mobile_image_mounter_error_t mobile_image_mounter_free(mobile_image_mounter_client_t client); + +/** + * Tells if the image of ImageType is already mounted. + * + * @param client The client use + * @param image_type The type of the image to look up + * @param result Pointer to a plist that will receive the result of the + * operation. + * + * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the + * operation has failed. Check the resulting plist for further information. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, or an error code on error + */ mobile_image_mounter_error_t mobile_image_mounter_lookup_image(mobile_image_mounter_client_t client, const char *image_type, plist_t *result); + +/** + * Uploads an image to the device. + * + * @param client The connected mobile_image_mounter client. + * @param image_type Type of image that is being uploaded. + * @param image_size Total size of the image. + * @param upload_cb Callback function that gets the data chunks for uploading + * the image. + * @param userdata User defined data for the upload callback function. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on succes, or a + * MOBILE_IMAGE_MOUNTER_E_* error code otherwise. + */ mobile_image_mounter_error_t mobile_image_mounter_upload_image(mobile_image_mounter_client_t client, const char *image_type, size_t image_size, mobile_image_mounter_upload_cb_t upload_cb, void* userdata); + +/** + * Mounts an image on the device. + * + * @param client The connected mobile_image_mounter client. + * @param image_path The absolute path of the image to mount. The image must + * be present before calling this function. + * @param image_signature Pointer to a buffer holding the images' signature + * @param signature_length Length of the signature image_signature points to + * @param image_type Type of image to mount + * @param result Pointer to a plist that will receive the result of the + * operation. + * + * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the + * operation has failed. Check the resulting plist for further information. + * Note that there is no unmounting function. The mount persists until the + * device is rebooted. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if on ore more parameters are + * invalid, or another error code otherwise. + */ mobile_image_mounter_error_t mobile_image_mounter_mount_image(mobile_image_mounter_client_t client, const char *image_path, const char *image_signature, uint16_t signature_length, const char *image_type, plist_t *result); + +/** + * Hangs up the connection to the mobile_image_mounter service. + * This functions has to be called before freeing up a mobile_image_mounter + * instance. If not, errors appear in the device's syslog. + * + * @param client The client to hang up + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if client is invalid, + * or another error code otherwise. + */ mobile_image_mounter_error_t mobile_image_mounter_hangup(mobile_image_mounter_client_t client); #ifdef __cplusplus diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h index c62e99e..c07ba68 100644 --- a/include/libimobiledevice/mobilebackup.h +++ b/include/libimobiledevice/mobilebackup.h @@ -56,18 +56,187 @@ typedef enum { MB_RESTORE_PRESERVE_CAMERA_ROLL = 1 << 2 } mobilebackup_flags_t; + +/** + * Connects to the mobilebackup service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * mobilebackup_client_t upon successful return. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID ARG if one + * or more parameters are invalid, or DEVICE_LINK_SERVICE_E_BAD_VERSION if + * the mobilebackup version on the device is newer. + */ mobilebackup_error_t mobilebackup_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilebackup_client_t * client); + +/** + * Starts a new mobilebackup service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * mobilebackup_client_t upon successful return. Must be freed using + * mobilebackup_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return MOBILEBACKUP_E_SUCCESS on success, or an MOBILEBACKUP_E_* error + * code otherwise. + */ mobilebackup_error_t mobilebackup_client_start_service(idevice_t device, mobilebackup_client_t* client, const char* label); + +/** + * Disconnects a mobilebackup client from the device and frees up the + * mobilebackup client data. + * + * @param client The mobilebackup client to disconnect and free. + * + * @return MOBILEBACKUP_E_SUCCESS on success, or MOBILEBACKUP_E_INVALID_ARG + * if client is NULL. + */ mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client); + +/** + * Polls the device for mobilebackup data. + * + * @param client The mobilebackup client + * @param plist A pointer to the location where the plist should be stored + * + * @return an error code + */ mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t *plist); + +/** + * Sends mobilebackup data to the device + * + * @note This function is low-level and should only be used if you need to send + * a new type of message. + * + * @param client The mobilebackup client + * @param plist The location of the plist to send + * + * @return an error code + */ mobilebackup_error_t mobilebackup_send(mobilebackup_client_t client, plist_t plist); + +/** + * Request a backup from the connected device. + * + * @param client The connected MobileBackup client to use. + * @param backup_manifest The backup manifest, a plist_t of type PLIST_DICT + * containing the backup state of the last backup. For a first-time backup + * set this parameter to NULL. + * @param base_path The base path on the device to use for the backup + * operation, usually "/". + * @param proto_version A string denoting the version of the backup protocol + * to use. Latest known version is "1.6" + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if + * one of the parameters is invalid, MOBILEBACKUP_E_PLIST_ERROR if + * backup_manifest is not of type PLIST_DICT, MOBILEBACKUP_E_MUX_ERROR + * if a communication error occurs, MOBILEBACKUP_E_REPLY_NOT_OK + */ mobilebackup_error_t mobilebackup_request_backup(mobilebackup_client_t client, plist_t backup_manifest, const char *base_path, const char *proto_version); + +/** + * Sends a confirmation to the device that a backup file has been received. + * + * @param client The connected MobileBackup client to use. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if + * client is invalid, or MOBILEBACKUP_E_MUX_ERROR if a communication error + * occurs. + */ mobilebackup_error_t mobilebackup_send_backup_file_received(mobilebackup_client_t client); + +/** + * Request that a backup should be restored to the connected device. + * + * @param client The connected MobileBackup client to use. + * @param backup_manifest The backup manifest, a plist_t of type PLIST_DICT + * containing the backup state to be restored. + * @param flags Flags to send with the request. Currently this is a combination + * of the following mobilebackup_flags_t: + * MB_RESTORE_NOTIFY_SPRINGBOARD - let SpringBoard show a 'Restore' screen + * MB_RESTORE_PRESERVE_SETTINGS - do not overwrite any settings + * MB_RESTORE_PRESERVE_CAMERA_ROLL - preserve the photos of the camera roll + * @param proto_version A string denoting the version of the backup protocol + * to use. Latest known version is "1.6". Ideally this value should be + * extracted from the given manifest plist. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if + * one of the parameters is invalid, MOBILEBACKUP_E_PLIST_ERROR if + * backup_manifest is not of type PLIST_DICT, MOBILEBACKUP_E_MUX_ERROR + * if a communication error occurs, or MOBILEBACKUP_E_REPLY_NOT_OK + * if the device did not accept the request. + */ mobilebackup_error_t mobilebackup_request_restore(mobilebackup_client_t client, plist_t backup_manifest, mobilebackup_flags_t flags, const char *proto_version); + +/** + * Receive a confirmation from the device that it successfully received + * a restore file. + * + * @param client The connected MobileBackup client to use. + * @param result Pointer to a plist_t that will be set to the received plist + * for further processing. The caller has to free it using plist_free(). + * Note that it will be set to NULL if the operation itself fails due to + * a communication or plist error. + * If this parameter is NULL, it will be ignored. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if + * client is invalid, MOBILEBACKUP_E_REPLY_NOT_OK if the expected + * 'BackupMessageRestoreFileReceived' message could not be received, + * MOBILEBACKUP_E_PLIST_ERROR if the received message is not a valid backup + * message plist, or MOBILEBACKUP_E_MUX_ERROR if a communication error + * occurs. + */ mobilebackup_error_t mobilebackup_receive_restore_file_received(mobilebackup_client_t client, plist_t *result); + +/** + * Receive a confirmation from the device that it successfully received + * application data file. + * + * @param client The connected MobileBackup client to use. + * @param result Pointer to a plist_t that will be set to the received plist + * for further processing. The caller has to free it using plist_free(). + * Note that it will be set to NULL if the operation itself fails due to + * a communication or plist error. + * If this parameter is NULL, it will be ignored. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if + * client is invalid, MOBILEBACKUP_E_REPLY_NOT_OK if the expected + * 'BackupMessageRestoreApplicationReceived' message could not be received, + * MOBILEBACKUP_E_PLIST_ERROR if the received message is not a valid backup + * message plist, or MOBILEBACKUP_E_MUX_ERROR if a communication error + * occurs. + */ mobilebackup_error_t mobilebackup_receive_restore_application_received(mobilebackup_client_t client, plist_t *result); + +/** + * Tells the device that the restore process is complete and waits for the + * device to close the connection. After that, the device should reboot. + * + * @param client The connected MobileBackup client to use. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if + * client is invalid, MOBILEBACKUP_E_PLIST_ERROR if the received disconnect + * message plist is invalid, or MOBILEBACKUP_E_MUX_ERROR if a communication + * error occurs. + */ mobilebackup_error_t mobilebackup_send_restore_complete(mobilebackup_client_t client); + +/** + * Sends a backup error message to the device. + * + * @param client The connected MobileBackup client to use. + * @param reason A string describing the reason for the error message. + * + * @return MOBILEBACKUP_E_SUCCESS on success, MOBILEBACKUP_E_INVALID_ARG if + * one of the parameters is invalid, or MOBILEBACKUP_E_MUX_ERROR if a + * communication error occurs. + */ mobilebackup_error_t mobilebackup_send_error(mobilebackup_client_t client, const char *reason); #ifdef __cplusplus diff --git a/include/libimobiledevice/mobilebackup2.h b/include/libimobiledevice/mobilebackup2.h index 65bbfc7..ad1dcea 100644 --- a/include/libimobiledevice/mobilebackup2.h +++ b/include/libimobiledevice/mobilebackup2.h @@ -51,16 +51,160 @@ typedef int16_t mobilebackup2_error_t; typedef struct mobilebackup2_client_private mobilebackup2_client_private; typedef mobilebackup2_client_private *mobilebackup2_client_t; /**< The client handle. */ + +/** + * Connects to the mobilebackup2 service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * mobilebackup2_client_t upon successful return. + * + * @return MOBILEBACKUP2_E_SUCCESS on success, MOBILEBACKUP2_E_INVALID ARG + * if one or more parameter is invalid, or MOBILEBACKUP2_E_BAD_VERSION + * if the mobilebackup2 version on the device is newer. + */ mobilebackup2_error_t mobilebackup2_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilebackup2_client_t * client); + +/** + * Starts a new mobilebackup2 service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * mobilebackup2_client_t upon successful return. Must be freed using + * mobilebackup2_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return MOBILEBACKUP2_E_SUCCESS on success, or an MOBILEBACKUP2_E_* error + * code otherwise. + */ mobilebackup2_error_t mobilebackup2_client_start_service(idevice_t device, mobilebackup2_client_t* client, const char* label); + +/** + * Disconnects a mobilebackup2 client from the device and frees up the + * mobilebackup2 client data. + * + * @param client The mobilebackup2 client to disconnect and free. + * + * @return MOBILEBACKUP2_E_SUCCESS on success, or MOBILEBACKUP2_E_INVALID_ARG + * if client is NULL. + */ mobilebackup2_error_t mobilebackup2_client_free(mobilebackup2_client_t client); + +/** + * Sends a backup message plist. + * + * @param client The connected MobileBackup client to use. + * @param message The message to send. This will be inserted into the request + * plist as value for MessageName. If this parameter is NULL, + * the plist passed in the options parameter will be sent directly. + * @param options Additional options as PLIST_DICT to add to the request. + * The MessageName key with the value passed in the message parameter + * will be inserted into this plist before sending it. This parameter + * can be NULL if message is not NULL. + */ mobilebackup2_error_t mobilebackup2_send_message(mobilebackup2_client_t client, const char *message, plist_t options); + +/** + * Receives a DL* message plist from the device. + * This function is a wrapper around device_link_service_receive_message. + * + * @param client The connected MobileBackup client to use. + * @param msg_plist Pointer to a plist that will be set to the contents of the + * message plist upon successful return. + * @param dlmessage A pointer that will be set to a newly allocated char* + * containing the DL* string from the given plist. It is up to the caller + * to free the allocated memory. If this parameter is NULL + * it will be ignored. + * + * @return MOBILEBACKUP2_E_SUCCESS if a DL* message was received, + * MOBILEBACKUP2_E_INVALID_ARG if client or message is invalid, + * MOBILEBACKUP2_E_PLIST_ERROR if the received plist is invalid + * or is not a DL* message plist, or MOBILEBACKUP2_E_MUX_ERROR if + * receiving from the device failed. + */ mobilebackup2_error_t mobilebackup2_receive_message(mobilebackup2_client_t client, plist_t *msg_plist, char **dlmessage); + +/** + * Send binary data to the device. + * + * @note This function returns MOBILEBACKUP2_E_SUCCESS even if less than the + * requested length has been sent. The fourth parameter is required and + * must be checked to ensure if the whole data has been sent. + * + * @param client The MobileBackup client to send to. + * @param data Pointer to the data to send + * @param length Number of bytes to send + * @param bytes Number of bytes actually sent + * + * @return MOBILEBACKUP2_E_SUCCESS if any data was successfully sent, + * MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid, + * or MOBILEBACKUP2_E_MUX_ERROR if sending of the data failed. + */ mobilebackup2_error_t mobilebackup2_send_raw(mobilebackup2_client_t client, const char *data, uint32_t length, uint32_t *bytes); + +/** + * Receive binary from the device. + * + * @note This function returns MOBILEBACKUP2_E_SUCCESS even if no data + * has been received (unless a communication error occured). + * The fourth parameter is required and must be checked to know how + * many bytes were actually received. + * + * @param client The MobileBackup client to receive from. + * @param data Pointer to a buffer that will be filled with the received data. + * @param length Number of bytes to receive. The data buffer needs to be large + * enough to store this amount of data. + * @paran bytes Number of bytes actually received. + * + * @return MOBILEBACKUP2_E_SUCCESS if any or no data was received, + * MOBILEBACKUP2_E_INVALID_ARG if one of the parameters is invalid, + * or MOBILEBACKUP2_E_MUX_ERROR if receiving the data failed. + */ mobilebackup2_error_t mobilebackup2_receive_raw(mobilebackup2_client_t client, char *data, uint32_t length, uint32_t *bytes); + +/** + * Performs the mobilebackup2 protocol version exchange. + * + * @param client The MobileBackup client to use. + * @param local_versions An array of supported versions to send to the remote. + * @param count The number of items in local_versions. + * @param remote_version Holds the protocol version of the remote on success. + * + * @return MOBILEBACKUP2_E_SUCCESS on success, or a MOBILEBACKUP2_E_* error + * code otherwise. + */ mobilebackup2_error_t mobilebackup2_version_exchange(mobilebackup2_client_t client, double local_versions[], char count, double *remote_version); + +/** + * Send a request to the connected mobilebackup2 service. + * + * @param client + * @param request The request to send to the backup service. + * Currently, this is one of "Backup", "Restore", "Info", or "List". + * @param target_identifier UDID of the target device. + * @param source_identifier UDID of backup data? + * @param options Additional options in a plist of type PLIST_DICT. + * + * @return MOBILEBACKUP2_E_SUCCESS if the request was successfully sent, + * or a MOBILEBACKUP2_E_* error value otherwise. + */ mobilebackup2_error_t mobilebackup2_send_request(mobilebackup2_client_t client, const char *request, const char *target_identifier, const char *source_identifier, plist_t options); + +/** + * Sends a DLMessageStatusResponse to the device. + * + * @param client The MobileBackup client to use. + * @param status_code The status code to send. + * @param status1 A status message to send. Can be NULL if not required. + * @param status2 An additional status plist to attach to the response. + * Can be NULL if not required. + * + * @return MOBILEBACKUP2_E_SUCCESS on success, MOBILEBACKUP2_E_INVALID_ARG + * if client is invalid, or another MOBILEBACKUP2_E_* otherwise. + */ mobilebackup2_error_t mobilebackup2_send_status_response(mobilebackup2_client_t client, int status_code, const char *status1, plist_t status2); #ifdef __cplusplus diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h index 8e263ce..6ba197b 100644 --- a/include/libimobiledevice/mobilesync.h +++ b/include/libimobiledevice/mobilesync.h @@ -68,35 +68,284 @@ typedef struct { typedef mobilesync_anchors *mobilesync_anchors_t; /**< Anchors used by the device and computer. */ /* Interface */ + +/** + * Connects to the mobilesync service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * #mobilesync_client_t upon successful return. + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one or more parameters are invalid + * @retval DEVICE_LINK_SERVICE_E_BAD_VERSION if the mobilesync version on + * the device is newer. + */ mobilesync_error_t mobilesync_client_new(idevice_t device, lockdownd_service_descriptor_t service, mobilesync_client_t * client); + +/** + * Starts a new mobilesync service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * mobilesync_client_t upon successful return. Must be freed using + * mobilesync_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return MOBILESYNC_E_SUCCESS on success, or an MOBILESYNC_E_* error + * code otherwise. + */ mobilesync_error_t mobilesync_client_start_service(idevice_t device, mobilesync_client_t* client, const char* label); + +/** + * Disconnects a mobilesync client from the device and frees up the + * mobilesync client data. + * + * @param client The mobilesync client to disconnect and free. + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if \a client is NULL. + */ mobilesync_error_t mobilesync_client_free(mobilesync_client_t client); + +/** + * Polls the device for mobilesync data. + * + * @param client The mobilesync client + * @param plist A pointer to the location where the plist should be stored + * + * @return an error code + */ mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t *plist); + +/** + * Sends mobilesync data to the device + * + * @note This function is low-level and should only be used if you need to send + * a new type of message. + * + * @param client The mobilesync client + * @param plist The location of the plist to send + * + * @return an error code + */ mobilesync_error_t mobilesync_send(mobilesync_client_t client, plist_t plist); + +/** + * Requests starting synchronization of a data class with the device + * + * @param client The mobilesync client + * @param data_class The data class identifier to sync + * @param anchors The anchors required to exchange with the device. The anchors + * allow the device to tell if the synchronization information on the computer + * and device are consistent to determine what sync type is required. + * @param computer_data_class_version The version of the data class storage on the computer + * @param sync_type A pointer to store the sync type reported by the device_anchor + * @param device_data_class_version The version of the data class storage on the device + * @param error_description A pointer to store an error message if reported by the device + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form + * @retval MOBILESYNC_E_SYNC_REFUSED if the device refused to sync + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * sync request + */ mobilesync_error_t mobilesync_start(mobilesync_client_t client, const char *data_class, mobilesync_anchors_t anchors, uint64_t computer_data_class_version, mobilesync_sync_type_t *sync_type, uint64_t *device_data_class_version, char** error_description); + +/** + * Cancels a running synchronization session with a device at any time. + * + * @param client The mobilesync client + * @param reason The reason to supply to the device for cancelling + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* reason); + +/** + * Finish a synchronization session of a data class on the device. + * A session must have previously been started using mobilesync_start(). + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid + * form + */ mobilesync_error_t mobilesync_finish(mobilesync_client_t client); + +/** + * Requests to receive all records of the currently set data class from the device. + * The actually changes are retrieved using mobilesync_receive_changes() after this + * request has been successful. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ mobilesync_error_t mobilesync_get_all_records_from_device(mobilesync_client_t client); + +/** + * Requests to receive only changed records of the currently set data class from the device. + * The actually changes are retrieved using mobilesync_receive_changes() after this + * request has been successful. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ mobilesync_error_t mobilesync_get_changes_from_device(mobilesync_client_t client); + +/** + * Requests the device to delete all records of the current data class + * + * @note The operation must be called after starting synchronization. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form + */ mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t client); + +/** + * Receives changed entitites of the currently set data class from the device + * + * @param client The mobilesync client + * @param entities A pointer to store the changed entity records as a PLIST_DICT + * @param is_last_record A pointer to store a flag indicating if this submission is the last one + * @param actions A pointer to additional flags the device is sending or NULL to ignore + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * session + */ mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_t *entities, uint8_t *is_last_record, plist_t *actions); + +/** + * Acknowledges to the device that the changes have been merged on the computer + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + */ mobilesync_error_t mobilesync_acknowledge_changes_from_device(mobilesync_client_t client); + +/** + * Verifies if the device is ready to receive changes from the computer. + * This call changes the synchronization direction so that mobilesync_send_changes() + * can be used to send changes to the device. + * + * @param client The mobilesync client + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid form + * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does + * not permit this call + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * session + * @retval MOBILESYNC_E_NOT_READY if the device is not ready to start + * receiving any changes + */ mobilesync_error_t mobilesync_ready_to_send_changes_from_computer(mobilesync_client_t client); + +/** + * Sends changed entities of the currently set data class to the device + * + * @param client The mobilesync client + * @param entities The changed entity records as a PLIST_DICT + * @param is_last_record A flag indicating if this submission is the last one + * @param actions Additional actions for the device created with mobilesync_actions_new() + * or NULL if no actions should be passed + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid, + * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does + * not permit this call + */ mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t entities, uint8_t is_last_record, plist_t actions); + +/** + * Receives any remapped identifiers reported after the device merged submitted changes. + * + * @param client The mobilesync client + * @param mapping A pointer to an array plist containing a dict of identifier remappings + * + * @retval MOBILESYNC_E_SUCCESS on success + * @retval MOBILESYNC_E_INVALID_ARG if one of the parameters is invalid + * @retval MOBILESYNC_E_PLIST_ERROR if the received plist is not of valid + * form + * @retval MOBILESYNC_E_WRONG_DIRECTION if the current sync direction does + * not permit this call + * @retval MOBILESYNC_E_CANCELLED if the device explicitly cancelled the + * session + */ mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plist_t *mapping); /* Helper */ + +/** + * Allocates memory for a new anchors struct initialized with the passed anchors. + * + * @param device_anchor An anchor the device reported the last time or NULL + * if none is known yet which for instance is true on first synchronization. + * @param computer_anchor An arbitrary string to use as anchor for the computer. + * + * @return A new #mobilesync_anchors_t struct. Must be freed using mobilesync_anchors_free(). + */ mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const char *computer_anchor); + +/** + * Free memory used by anchors. + * + * @param anchors The anchors to free. + */ void mobilesync_anchors_free(mobilesync_anchors_t anchors); + +/** + * Create a new actions plist to use in mobilesync_send_changes(). + * + * @return A new plist_t of type PLIST_DICT. + */ plist_t mobilesync_actions_new(); + +/** + * Add one or more new key:value pairs to the given actions plist. + * + * @param actions The actions to modify. + * @param ... KEY, VALUE, [KEY, VALUE], NULL + * + * @note The known keys so far are "SyncDeviceLinkEntityNamesKey" which expects + * an array of entity names, followed by a count paramter as well as + * "SyncDeviceLinkAllRecordsOfPulledEntityTypeSentKey" which expects an + * integer to use as a boolean value indicating that the device should + * link submitted changes and report remapped identifiers. + */ void mobilesync_actions_add(plist_t actions, ...); + +/** + * Free actions plist. + * + * @param actions The actions plist to free. Does nothing if NULL is passed. + */ void mobilesync_actions_free(plist_t actions); #ifdef __cplusplus diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h index 4f025ee..a66057b 100644 --- a/include/libimobiledevice/notification_proxy.h +++ b/include/libimobiledevice/notification_proxy.h @@ -93,13 +93,103 @@ typedef np_client_private *np_client_t; /**< The client handle. */ typedef void (*np_notify_cb_t) (const char *notification, void *user_data); /* Interface */ + +/** + * Connects to the notification_proxy on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated np_client_t + * upon successful return. + * + * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when device is NULL, + * or NP_E_CONN_FAILED when the connection to the device could not be + * established. + */ np_error_t np_client_new(idevice_t device, lockdownd_service_descriptor_t service, np_client_t *client); + +/** + * Starts a new notification proxy service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * np_client_t upon successful return. Must be freed using + * np_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return NP_E_SUCCESS on success, or an NP_E_* error + * code otherwise. + */ np_error_t np_client_start_service(idevice_t device, np_client_t* client, const char* label); + +/** + * Disconnects a notification_proxy client from the device and frees up the + * notification_proxy client data. + * + * @param client The notification_proxy client to disconnect and free. + * + * @return NP_E_SUCCESS on success, or NP_E_INVALID_ARG when client is NULL. + */ np_error_t np_client_free(np_client_t client); + +/** + * Sends a notification to the device's notification_proxy. + * + * @param client The client to send to + * @param notification The notification message to send + * + * @return NP_E_SUCCESS on success, or an error returned by np_plist_send + */ np_error_t np_post_notification(np_client_t client, const char *notification); + +/** + * Tells the device to send a notification on the specified event. + * + * @param client The client to send to + * @param notification The notifications that should be observed. + * + * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * notification are NULL, or an error returned by np_plist_send. + */ np_error_t np_observe_notification(np_client_t client, const char *notification); + +/** + * Tells the device to send a notification on specified events. + * + * @param client The client to send to + * @param notification_spec Specification of the notifications that should be + * observed. This is expected to be an array of const char* that MUST have a + * terminating NULL entry. + * + * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when client is null, + * or an error returned by np_observe_notification. + */ np_error_t np_observe_notifications(np_client_t client, const char **notification_spec); + +/** + * This function allows an application to define a callback function that will + * be called when a notification has been received. + * It will start a thread that polls for notifications and calls the callback + * function if a notification has been received. + * In case of an error condition when polling for notifications - e.g. device + * disconnect - the thread will call the callback function with an empty + * notification "" and terminate itself. + * + * @param client the NP client + * @param notify_cb pointer to a callback function or NULL to de-register a + * previously set callback function. + * @param user_data Pointer that will be passed to the callback function as + * user data. If notify_cb is NULL, this parameter is ignored. + * + * @note Only one callback function can be registered at the same time; + * any previously set callback function will be removed automatically. + * + * @return NP_E_SUCCESS when the callback was successfully registered, + * NP_E_INVALID_ARG when client is NULL, or NP_E_UNKNOWN_ERROR when + * the callback thread could no be created. + */ np_error_t np_set_notify_callback(np_client_t client, np_notify_cb_t notify_cb, void *userdata); #ifdef __cplusplus diff --git a/include/libimobiledevice/restore.h b/include/libimobiledevice/restore.h index 584adb4..f4e8822 100644 --- a/include/libimobiledevice/restore.h +++ b/include/libimobiledevice/restore.h @@ -51,20 +51,130 @@ typedef struct restored_client_private restored_client_private; typedef restored_client_private *restored_client_t; /**< The client handle. */ /* Interface */ + +/** + * Creates a new restored client for the device. + * + * @param device The device to create a restored client for + * @param client The pointer to the location of the new restored_client + * @param label The label to use for communication. Usually the program name. + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ restored_error_t restored_client_new(idevice_t device, restored_client_t *client, const char *label); + +/** + * Closes the restored client session if one is running and frees up the + * restored_client struct. + * + * @param client The restore client + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ restored_error_t restored_client_free(restored_client_t client); + +/** + * 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. + * + * @param client The restored client + * @param type The type returned by the service daemon. Pass NULL to ignore. + * @param version The restore protocol version. Pass NULL to ignore. + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client is NULL + */ restored_error_t restored_query_type(restored_client_t client, char **type, uint64_t *version); + +/** + * Queries a value from the device specified by a key. + * + * @param client An initialized restored client. + * @param key The key name to request + * @param value A plist node representing the result value node + * + * @return 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_query_value(restored_client_t client, const char *key, plist_t *value); + +/** + * Retrieves a value from information plist specified by a key. + * + * @param client An initialized restored client. + * @param key The key name to request or NULL to query for all keys + * @param value A plist node representing the result value node + * + * @return 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_get_value(restored_client_t client, const char *key, plist_t *value) ; + +/** + * 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. + * + * @param client The restored client + * @param plist The plist to send + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL + */ restored_error_t restored_send(restored_client_t client, plist_t plist); + +/** + * Receives a plist from restored. + * + * @param client The restored client + * @param plist The plist to store the received data + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG when client or + * plist is NULL + */ restored_error_t restored_receive(restored_client_t client, plist_t *plist); + +/** + * Sends the Goodbye request to restored signaling the end of communication. + * + * @param client The restore client + * + * @return 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 + */ restored_error_t restored_goodbye(restored_client_t client); + +/** + * Requests to start a restore and retrieve it's port on success. + * + * @param client The restored client + * @param options PLIST_DICT with options for the restore process or NULL + * @param version the restore protocol version, see restored_query_type() + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter + * is NULL, RESTORE_E_START_RESTORE_FAILED if the request fails + */ restored_error_t restored_start_restore(restored_client_t client, plist_t options, uint64_t version); + +/** + * Requests device to reboot. + * + * @param client The restored client + * + * @return RESTORE_E_SUCCESS on success, NP_E_INVALID_ARG if a parameter + * is NULL + */ restored_error_t restored_reboot(restored_client_t client); /* Helper */ + +/** + * Sets the label to send for requests to restored. + * + * @param client The restore client + * @param label The label to set or NULL to disable sending a label + * + */ void restored_client_set_label(restored_client_t client, const char *label); #ifdef __cplusplus diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h index f9d131b..f0bf2c4 100644 --- a/include/libimobiledevice/sbservices.h +++ b/include/libimobiledevice/sbservices.h @@ -60,14 +60,116 @@ typedef struct sbservices_client_private sbservices_client_private; typedef sbservices_client_private *sbservices_client_t; /**< The client handle. */ /* Interface */ + +/** + * Connects to the springboardservices service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * sbservices_client_t upon successful return. + * + * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when + * client is NULL, or an SBSERVICES_E_* error code otherwise. + */ sbservices_error_t sbservices_client_new(idevice_t device, lockdownd_service_descriptor_t service, sbservices_client_t *client); + +/** + * Starts a new sbservices service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * sbservices_client_t upon successful return. Must be freed using + * sbservices_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return SBSERVICES_E_SUCCESS on success, or an SBSERVICES_E_* error + * code otherwise. + */ sbservices_error_t sbservices_client_start_service(idevice_t device, sbservices_client_t* client, const char* label); + +/** + * Disconnects an sbservices client from the device and frees up the + * sbservices client data. + * + * @param client The sbservices client to disconnect and free. + * + * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when + * client is NULL, or an SBSERVICES_E_* error code otherwise. + */ sbservices_error_t sbservices_client_free(sbservices_client_t client); + +/** + * Gets the icon state of the connected device. + * + * @param client The connected sbservices client to use. + * @param state Pointer that will point to a newly allocated plist containing + * the current icon state. It is up to the caller to free the memory. + * @param format_version A string to be passed as formatVersion along with + * the request, or NULL if no formatVersion should be passed. This is only + * supported since iOS 4.0 so for older firmware versions this must be set + * to NULL. + * + * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when + * client or state is invalid, or an SBSERVICES_E_* error code otherwise. + */ sbservices_error_t sbservices_get_icon_state(sbservices_client_t client, plist_t *state, const char *format_version); + +/** + * Sets the icon state of the connected device. + * + * @param client The connected sbservices client to use. + * @param newstate A plist containing the new iconstate. + * + * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when + * client or newstate is NULL, or an SBSERVICES_E_* error code otherwise. + */ sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t newstate); + +/** + * Get the icon of the specified app as PNG data. + * + * @param client The connected sbservices client to use. + * @param bundleId The bundle identifier of the app to retrieve the icon for. + * @param pngdata Pointer that will point to a newly allocated buffer + * containing the PNG data upon successful return. It is up to the caller + * to free the memory. + * @param pngsize Pointer to a uint64_t that will be set to the size of the + * buffer pngdata points to upon successful return. + * + * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when + * client, bundleId, or pngdata are invalid, or an SBSERVICES_E_* error + * code otherwise. + */ sbservices_error_t sbservices_get_icon_pngdata(sbservices_client_t client, const char *bundleId, char **pngdata, uint64_t *pngsize); + +/** + * Gets the interface orientation of the device. + * + * @param client The connected sbservices client to use. + * @param interface_orientation The interface orientation upon successful return. + * + * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when + * client or state is invalid, or an SBSERVICES_E_* error code otherwise. + */ sbservices_error_t sbservices_get_interface_orientation(sbservices_client_t client, sbservices_interface_orientation_t* interface_orientation); + +/** + * Get the home screen wallpaper as PNG data. + * + * @param client The connected sbservices client to use. + * @param pngdata Pointer that will point to a newly allocated buffer + * containing the PNG data upon successful return. It is up to the caller + * to free the memory. + * @param pngsize Pointer to a uint64_t that will be set to the size of the + * buffer pngdata points to upon successful return. + * + * @return SBSERVICES_E_SUCCESS on success, SBSERVICES_E_INVALID_ARG when + * client or pngdata are invalid, or an SBSERVICES_E_* error + * code otherwise. + */ sbservices_error_t sbservices_get_home_screen_wallpaper_pngdata(sbservices_client_t client, char **pngdata, uint64_t *pngsize); #ifdef __cplusplus diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h index c8679a9..3601172 100644 --- a/include/libimobiledevice/screenshotr.h +++ b/include/libimobiledevice/screenshotr.h @@ -50,10 +50,65 @@ typedef int16_t screenshotr_error_t; typedef struct screenshotr_client_private screenshotr_client_private; typedef screenshotr_client_private *screenshotr_client_t; /**< The client handle. */ + +/** + * Connects to the screenshotr service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * screenshotr_client_t upon successful return. + * + * @note This service is only available if a developer disk image has been + * mounted. + * + * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID ARG if one + * or more parameters are invalid, or SCREENSHOTR_E_CONN_FAILED if the + * connection to the device could not be established. + */ screenshotr_error_t screenshotr_client_new(idevice_t device, lockdownd_service_descriptor_t service, screenshotr_client_t * client); + +/** + * Starts a new screenshotr service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * screenshotr_client_t upon successful return. Must be freed using + * screenshotr_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return SCREENSHOTR_E_SUCCESS on success, or an SCREENSHOTR_E_* error + * code otherwise. + */ screenshotr_error_t screenshotr_client_start_service(idevice_t device, screenshotr_client_t* client, const char* label); + +/** + * Disconnects a screenshotr client from the device and frees up the + * screenshotr client data. + * + * @param client The screenshotr client to disconnect and free. + * + * @return SCREENSHOTR_E_SUCCESS on success, or SCREENSHOTR_E_INVALID_ARG + * if client is NULL. + */ screenshotr_error_t screenshotr_client_free(screenshotr_client_t client); + +/** + * Get a screen shot from the connected device. + * + * @param client The connection screenshotr service client. + * @param imgdata Pointer that will point to a newly allocated buffer + * containing TIFF image data upon successful return. It is up to the + * caller to free the memory. + * @param imgsize Pointer to a uint64_t that will be set to the size of the + * buffer imgdata points to upon successful return. + * + * @return SCREENSHOTR_E_SUCCESS on success, SCREENSHOTR_E_INVALID_ARG if + * one or more parameters are invalid, or another error code if an + * error occured. + */ screenshotr_error_t screenshotr_take_screenshot(screenshotr_client_t client, char **imgdata, uint64_t *imgsize); #ifdef __cplusplus diff --git a/include/libimobiledevice/service.h b/include/libimobiledevice/service.h index 6585fe7..acf846b 100644 --- a/include/libimobiledevice/service.h +++ b/include/libimobiledevice/service.h @@ -49,15 +49,120 @@ typedef service_client_private* service_client_t; /**< The client handle. */ #define SERVICE_CONSTRUCTOR(x) (int16_t (*)(idevice_t, lockdownd_service_descriptor_t, void**))(x) /* Interface */ + +/** + * Creates a new service for the specified service descriptor. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will be set to a newly allocated + * service_client_t upon successful return. + * + * @return SERVICE_E_SUCCESS on success, + * SERVICE_E_INVALID_ARG when one of the arguments is invalid, + * or SERVICE_E_MUX_ERROR when connecting to the device failed. + */ service_error_t service_client_new(idevice_t device, lockdownd_service_descriptor_t service, service_client_t *client); + +/** + * Starts a new service on the specified device with given name and + * connects to it. + * + * @param device The device to connect to. + * @param service_name The name of the service to start. + * @param client Pointer that will point to a newly allocated service_client_t + * upon successful return. Must be freed using service_client_free() after + * use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return SERVICE_E_SUCCESS on success, or a SERVICE_E_* error code + * otherwise. + */ service_error_t service_client_factory_start_service(idevice_t device, const char* service_name, void **client, const char* label, int16_t (*constructor_func)(idevice_t, lockdownd_service_descriptor_t, void**), int16_t *error_code); + +/** + * Frees a service instance. + * + * @param client The service instance to free. + * + * @return SERVICE_E_SUCCESS on success, + * SERVICE_E_INVALID_ARG when client is invalid, or a + * SERVICE_E_UNKNOWN_ERROR when another error occured. + */ service_error_t service_client_free(service_client_t client); + +/** + * Sends data using the given service client. + * + * @param client The service client to use for sending. + * @param data Data to send + * @param size Size of the data to send + * @param sent Number of bytes sent (can be NULL to ignore) + * + * @return SERVICE_E_SUCCESS on success, + * SERVICE_E_INVALID_ARG when one or more parameters are + * invalid, or SERVICE_E_UNKNOWN_ERROR when an unspecified + * error occurs. + */ service_error_t service_send(service_client_t client, const char *data, uint32_t size, uint32_t *sent); + +/** + * Receives data using the given service client with specified timeout. + * + * @param client The service client to use for receiving + * @param data Buffer that will be filled with the data received + * @param size Number of bytes to receive + * @param received Number of bytes received (can be NULL to ignore) + * @param timeout Maximum time in milliseconds to wait for data. + * + * @return SERVICE_E_SUCCESS on success, + * SERVICE_E_INVALID_ARG when one or more parameters are + * invalid, SERVICE_E_MUX_ERROR when a communication error + * occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified + * error occurs. + */ service_error_t service_receive_with_timeout(service_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout); + +/** + * Receives data using the given service client. + * + * @param client The service client to use for receiving + * @param data Buffer that will be filled with the data received + * @param size Number of bytes to receive + * @param received Number of bytes received (can be NULL to ignore) + * + * @return SERVICE_E_SUCCESS on success, + * SERVICE_E_INVALID_ARG when one or more parameters are + * invalid, SERVICE_E_MUX_ERROR when a communication error + * occurs, or SERVICE_E_UNKNOWN_ERROR when an unspecified + * error occurs. + */ service_error_t service_receive(service_client_t client, char *data, uint32_t size, uint32_t *received); + +/** + * Enable SSL for the given service client. + * + * @param client The connected service client for that SSL should be enabled. + * + * @return SERVICE_E_SUCCESS on success, + * SERVICE_E_INVALID_ARG if client or client->connection is + * NULL, SERVICE_E_SSL_ERROR when SSL could not be enabled, + * or SERVICE_E_UNKNOWN_ERROR otherwise. + */ service_error_t service_enable_ssl(service_client_t client); + +/** + * Disable SSL for the given service client. + * + * @param client The connected service client for that SSL should be disabled. + * + * @return SERVICE_E_SUCCESS on success, + * SERVICE_E_INVALID_ARG if client or client->connection is + * NULL, or SERVICE_E_UNKNOWN_ERROR otherwise. + */ service_error_t service_disable_ssl(service_client_t client); #ifdef __cplusplus diff --git a/include/libimobiledevice/syslog_relay.h b/include/libimobiledevice/syslog_relay.h index 7ccfd74..952840e 100644 --- a/include/libimobiledevice/syslog_relay.h +++ b/include/libimobiledevice/syslog_relay.h @@ -51,15 +51,109 @@ typedef syslog_relay_client_private *syslog_relay_client_t; /**< The client hand typedef void (*syslog_relay_receive_cb_t)(char c, void *user_data); /* Interface */ + +/** + * Connects to the syslog_relay service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * syslog_relay_client_t upon successful return. Must be freed using + * syslog_relay_client_free() after use. + * + * @return SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when + * client is NULL, or an SYSLOG_RELAY_E_* error code otherwise. + */ syslog_relay_error_t syslog_relay_client_new(idevice_t device, lockdownd_service_descriptor_t service, syslog_relay_client_t * client); + +/** + * Starts a new syslog_relay service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * syslog_relay_client_t upon successful return. Must be freed using + * syslog_relay_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return SYSLOG_RELAY_E_SUCCESS on success, or an SYSLOG_RELAY_E_* error + * code otherwise. + */ syslog_relay_error_t syslog_relay_client_start_service(idevice_t device, syslog_relay_client_t * client, const char* label); + +/** + * Disconnects a syslog_relay client from the device and frees up the + * syslog_relay client data. + * + * @param client The syslog_relay client to disconnect and free. + * + * @return SYSLOG_RELAY_E_SUCCESS on success, SYSLOG_RELAY_E_INVALID_ARG when + * client is NULL, or an SYSLOG_RELAY_E_* error code otherwise. + */ syslog_relay_error_t syslog_relay_client_free(syslog_relay_client_t client); + +/** + * Starts capturing the syslog of the device using a callback. + * + * Use syslog_relay_stop_capture() to stop receiving the syslog. + * + * @param client The syslog_relay client to use + * @param callback Callback to receive each character from the syslog. + * @param user_data Custom pointer passed to the callback function. + * + * @return SYSLOG_RELAY_E_SUCCESS on success, + * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are + * invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified + * error occurs or a syslog capture has already been started. + */ syslog_relay_error_t syslog_relay_start_capture(syslog_relay_client_t client, syslog_relay_receive_cb_t callback, void* user_data); + +/** + * Stops capturing the syslog of the device. + * + * Use syslog_relay_start_capture() to start receiving the syslog. + * + * @param client The syslog_relay client to use + * + * @return SYSLOG_RELAY_E_SUCCESS on success, + * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are + * invalid or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified + * error occurs or a syslog capture has already been started. + */ syslog_relay_error_t syslog_relay_stop_capture(syslog_relay_client_t client); /* Receiving */ + +/** + * Receives data using the given syslog_relay client with specified timeout. + * + * @param client The syslog_relay client to use for receiving + * @param data Buffer that will be filled with the data received + * @param size Number of bytes to receive + * @param received Number of bytes received (can be NULL to ignore) + * @param timeout Maximum time in milliseconds to wait for data. + * + * @return SYSLOG_RELAY_E_SUCCESS on success, + * SYSLOG_RELAY_E_INVALID_ARG when one or more parameters are + * invalid, SYSLOG_RELAY_E_MUX_ERROR when a communication error + * occurs, or SYSLOG_RELAY_E_UNKNOWN_ERROR when an unspecified + * error occurs. + */ syslog_relay_error_t syslog_relay_receive_with_timeout(syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received, unsigned int timeout); + +/** + * Receives data from the service. + * + * @param client The syslog_relay client + * @param data Buffer that will be filled with the data received + * @param size Number of bytes to receive + * @param received Number of bytes received (can be NULL to ignore) + * @param timeout Maximum time in milliseconds to wait for data. + * + * @return SYSLOG_RELAY_E_SUCCESS on success, + * SYSLOG_RELAY_E_INVALID_ARG when client or plist is NULL + */ syslog_relay_error_t syslog_relay_receive(syslog_relay_client_t client, char *data, uint32_t size, uint32_t *received); #ifdef __cplusplus diff --git a/include/libimobiledevice/webinspector.h b/include/libimobiledevice/webinspector.h index dfd4dd2..499e7f0 100644 --- a/include/libimobiledevice/webinspector.h +++ b/include/libimobiledevice/webinspector.h @@ -48,12 +48,85 @@ typedef int16_t webinspector_error_t; typedef struct webinspector_client_private webinspector_client_private; typedef webinspector_client_private *webinspector_client_t; /**< The client handle. */ + +/** + * Connects to the webinspector service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * webinspector_client_t upon successful return. Must be freed using + * webinspector_client_free() after use. + * + * @return WEBINSPECTOR_E_SUCCESS on success, WEBINSPECTOR_E_INVALID_ARG when + * client is NULL, or an WEBINSPECTOR_E_* error code otherwise. + */ webinspector_error_t webinspector_client_new(idevice_t device, lockdownd_service_descriptor_t service, webinspector_client_t * client); + +/** + * Starts a new webinspector service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * webinspector_client_t upon successful return. Must be freed using + * webinspector_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return WEBINSPECTOR_E_SUCCESS on success, or an WEBINSPECTOR_E_* error + * code otherwise. + */ webinspector_error_t webinspector_client_start_service(idevice_t device, webinspector_client_t * client, const char* label); + +/** + * Disconnects a webinspector client from the device and frees up the + * webinspector client data. + * + * @param client The webinspector client to disconnect and free. + * + * @return WEBINSPECTOR_E_SUCCESS on success, WEBINSPECTOR_E_INVALID_ARG when + * client is NULL, or an WEBINSPECTOR_E_* error code otherwise. + */ webinspector_error_t webinspector_client_free(webinspector_client_t client); + +/** + * Sends a plist to the service. + * + * @param client The webinspector client + * @param plist The plist to send + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client or plist is NULL + */ webinspector_error_t webinspector_send(webinspector_client_t client, plist_t plist); + +/** + * Receives a plist from the service. + * + * @param client The webinspector client + * @param plist The plist to store the received data + * + * @return DIAGNOSTICS_RELAY_E_SUCCESS on success, + * DIAGNOSTICS_RELAY_E_INVALID_ARG when client or plist is NULL + */ webinspector_error_t webinspector_receive(webinspector_client_t client, plist_t * plist); + +/** + * Receives a plist using the given webinspector client. + * + * @param client The webinspector client to use for receiving + * @param plist pointer to a plist_t that will point to the received plist + * upon successful return + * @param timeout Maximum time in milliseconds to wait for data. + * + * @return WEBINSPECTOR_E_SUCCESS on success, + * WEBINSPECTOR_E_INVALID_ARG when client or *plist is NULL, + * WEBINSPECTOR_E_PLIST_ERROR when the received data cannot be + * converted to a plist, WEBINSPECTOR_E_MUX_ERROR when a + * communication error occurs, or WEBINSPECTOR_E_UNKNOWN_ERROR + * when an unspecified error occurs. + */ webinspector_error_t webinspector_receive_with_timeout(webinspector_client_t client, plist_t * plist, uint32_t timeout_ms); #ifdef __cplusplus |