diff options
40 files changed, 2703 insertions, 2478 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 @@ -95,18 +95,6 @@ afc_error_t afc_client_new_with_service_client(service_client_t service_client, return AFC_E_SUCCESS; } -/** - * 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) { if (!device || !service || service->port == 0) @@ -126,19 +114,6 @@ afc_error_t afc_client_new(idevice_t device, lockdownd_service_descriptor_t serv return err; } -/** - * 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) { afc_error_t err = AFC_E_UNKNOWN_ERROR; @@ -146,12 +121,6 @@ afc_error_t afc_client_start_service(idevice_t device, afc_client_t * client, co return err; } -/** - * 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) { if (!client || !client->afc_packet) @@ -432,16 +401,6 @@ static char **make_strings_list(char *tokens, uint32_t length) return list; } -/** - * 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) { uint32_t bytes = 0; @@ -478,17 +437,6 @@ afc_error_t afc_read_directory(afc_client_t client, const char *dir, char ***lis return ret; } -/** - * 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) { uint32_t bytes = 0; @@ -526,17 +474,6 @@ afc_error_t afc_get_device_info(afc_client_t client, char ***infos) return ret; } -/** - * 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 ret = AFC_E_INTERNAL_ERROR; @@ -564,14 +501,6 @@ afc_error_t afc_get_device_info_key(afc_client_t client, const char *key, char * return ret; } -/** - * 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) { uint32_t bytes = 0; @@ -600,15 +529,6 @@ afc_error_t afc_remove_path(afc_client_t client, const char *path) return ret; } -/** - * 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) { char *buffer = (char *) malloc(sizeof(char) * (strlen(from) + strlen(to) + 1 + sizeof(uint32_t))); @@ -638,15 +558,6 @@ afc_error_t afc_rename_path(afc_client_t client, const char *from, const char *t return ret; } -/** - * 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) { uint32_t bytes = 0; @@ -671,17 +582,6 @@ afc_error_t afc_make_directory(afc_client_t client, const char *dir) return ret; } -/** - * 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 *path, char ***infolist) { char *received = NULL; @@ -712,19 +612,6 @@ afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***inf return ret; } -/** - * 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. - */ idevice_error_t afc_file_open(afc_client_t client, const char *filename, afc_file_mode_t file_mode, uint64_t *handle) @@ -772,17 +659,6 @@ afc_file_open(afc_client_t client, const char *filename, return ret; } -/** - * 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. - */ idevice_error_t afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, uint32_t *bytes_read) { @@ -837,17 +713,6 @@ afc_file_read(afc_client_t client, uint64_t handle, char *data, uint32_t length, return ret; } -/** - * 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. - */ idevice_error_t afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t length, uint32_t *bytes_written) { @@ -881,12 +746,6 @@ afc_file_write(afc_client_t client, uint64_t handle, const char *data, uint32_t return ret; } -/** - * 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) { uint32_t bytes = 0; @@ -915,18 +774,6 @@ afc_error_t afc_file_close(afc_client_t client, uint64_t handle) return ret; } -/** - * 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) { uint32_t bytes = 0; @@ -961,16 +808,6 @@ afc_error_t afc_file_lock(afc_client_t client, uint64_t handle, afc_lock_op_t op return ret; } -/** - * 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) { uint32_t bytes = 0; @@ -1004,15 +841,6 @@ afc_error_t afc_file_seek(afc_client_t client, uint64_t handle, int64_t offset, return ret; } -/** - * 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) { char *buffer = (char *) malloc(sizeof(char) * 8); @@ -1047,18 +875,6 @@ afc_error_t afc_file_tell(afc_client_t client, uint64_t handle, uint64_t *positi return ret; } -/** - * 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) { uint32_t bytes = 0; @@ -1090,15 +906,6 @@ afc_error_t afc_file_truncate(afc_client_t client, uint64_t handle, uint64_t new return ret; } -/** - * 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) { char *buffer = (char *) malloc(sizeof(char) * (strlen(path) + 1 + 8)); @@ -1129,16 +936,6 @@ afc_error_t afc_truncate(afc_client_t client, const char *path, uint64_t newsize return ret; } -/** - * 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) { char *buffer = (char *) malloc(sizeof(char) * (strlen(target)+1 + strlen(linkname)+1 + 8)); @@ -1173,15 +970,6 @@ afc_error_t afc_make_link(afc_client_t client, afc_link_type_t linktype, const c return ret; } -/** - * 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) { char *buffer = (char *) malloc(sizeof(char) * (strlen(path) + 1 + 8)); diff --git a/src/diagnostics_relay.c b/src/diagnostics_relay.c index de3781c..cc9c645 100644 --- a/src/diagnostics_relay.c +++ b/src/diagnostics_relay.c @@ -69,18 +69,6 @@ static int diagnostics_relay_check_result(plist_t dict) return ret; } -/** - * 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) { if (!device || !service || service->port == 0 || !client || *client) { @@ -101,19 +89,6 @@ diagnostics_relay_error_t diagnostics_relay_client_new(idevice_t device, lockdow return DIAGNOSTICS_RELAY_E_SUCCESS; } -/** - * 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) { diagnostics_relay_error_t err = DIAGNOSTICS_RELAY_E_UNKNOWN_ERROR; @@ -121,17 +96,6 @@ diagnostics_relay_error_t diagnostics_relay_client_start_service(idevice_t devic return err; } -/** - * 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) { if (!client) @@ -198,16 +162,6 @@ static diagnostics_relay_error_t diagnostics_relay_send(diagnostics_relay_client return ret; } -/** - * 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) { if (!client) @@ -242,16 +196,6 @@ diagnostics_relay_error_t diagnostics_relay_goodbye(diagnostics_relay_client_t c return ret; } -/** - * 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) { if (!client) @@ -328,41 +272,11 @@ static diagnostics_relay_error_t internal_diagnostics_relay_action(diagnostics_r return ret; } -/** - * 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) { return internal_diagnostics_relay_action(client, "Restart", 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) { return internal_diagnostics_relay_action(client, "Shutdown", flags); diff --git a/src/file_relay.c b/src/file_relay.c index fb802a8..3d1eb12 100644 --- a/src/file_relay.c +++ b/src/file_relay.c @@ -24,18 +24,6 @@ #include "property_list_service.h" #include "common/debug.h" -/** - * 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) { if (!device || !service || service->port == 0 || !client || *client) { @@ -56,19 +44,6 @@ file_relay_error_t file_relay_client_new(idevice_t device, lockdownd_service_des return FILE_RELAY_E_SUCCESS; } -/** - * 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) { file_relay_error_t err = FILE_RELAY_E_UNKNOWN_ERROR; @@ -76,17 +51,6 @@ file_relay_error_t file_relay_client_start_service(idevice_t device, file_relay_ return err; } -/** - * 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) { if (!client) @@ -98,37 +62,6 @@ file_relay_error_t file_relay_client_free(file_relay_client_t client) return FILE_RELAY_E_SUCCESS; } -/** - * 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_timeout(file_relay_client_t client, const char **sources, idevice_connection_t *connection, unsigned int timeout) { if (!client || !client->parent || !sources || !sources[0]) { @@ -218,37 +151,6 @@ leave: return err; } -/** - * 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(file_relay_client_t client, const char **sources, idevice_connection_t *connection) { return file_relay_request_sources_timeout(client, sources, connection, 60000); diff --git a/src/heartbeat.c b/src/heartbeat.c index e03b44e..7654dd0 100644 --- a/src/heartbeat.c +++ b/src/heartbeat.c @@ -58,18 +58,6 @@ static heartbeat_error_t heartbeat_error(property_list_service_error_t err) return HEARTBEAT_E_UNKNOWN_ERROR; } -/** - * 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) { *client = NULL; @@ -97,19 +85,6 @@ heartbeat_error_t heartbeat_client_new(idevice_t device, lockdownd_service_descr return 0; } -/** - * 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) { heartbeat_error_t err = HEARTBEAT_E_UNKNOWN_ERROR; @@ -117,15 +92,6 @@ heartbeat_error_t heartbeat_client_start_service(idevice_t device, heartbeat_cli return err; } -/** - * 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) { if (!client) @@ -137,15 +103,6 @@ heartbeat_error_t heartbeat_client_free(heartbeat_client_t client) return err; } -/** - * 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) { heartbeat_error_t res = HEARTBEAT_E_UNKNOWN_ERROR; @@ -161,35 +118,11 @@ heartbeat_error_t heartbeat_send(heartbeat_client_t client, plist_t plist) return res; } -/** - * 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) { return heartbeat_receive_with_timeout(client, plist, 1000); } -/** - * 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) { heartbeat_error_t res = HEARTBEAT_E_UNKNOWN_ERROR; diff --git a/src/house_arrest.c b/src/house_arrest.c index 9aaad34..4158368 100644 --- a/src/house_arrest.c +++ b/src/house_arrest.c @@ -55,17 +55,6 @@ static house_arrest_error_t house_arrest_error(property_list_service_error_t err return HOUSE_ARREST_E_UNKNOWN_ERROR; } -/** - * 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) { property_list_service_client_t plistclient = NULL; @@ -82,19 +71,6 @@ house_arrest_error_t house_arrest_client_new(idevice_t device, lockdownd_service return HOUSE_ARREST_E_SUCCESS; } -/** - * 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) { house_arrest_error_t err = HOUSE_ARREST_E_UNKNOWN_ERROR; @@ -102,20 +78,6 @@ house_arrest_error_t house_arrest_client_start_service(idevice_t device, house_a return err; } -/** - * 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) { if (!client) @@ -131,23 +93,6 @@ house_arrest_error_t house_arrest_client_free(house_arrest_client_t client) return err; } -/** - * 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) { if (!client || !client->parent || !dict) @@ -164,25 +109,6 @@ house_arrest_error_t house_arrest_send_request(house_arrest_client_t client, pli return res; } -/** - * 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) { if (!client || !client->parent || !command || !appid) @@ -203,20 +129,6 @@ house_arrest_error_t house_arrest_send_command(house_arrest_client_t client, con return res; } -/** - * 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) { if (!client || !client->parent) @@ -235,25 +147,6 @@ house_arrest_error_t house_arrest_get_result(house_arrest_client_t client, plist return res; } -/** - * 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) { if (!client || !client->parent || (client->mode == HOUSE_ARREST_CLIENT_MODE_AFC)) { diff --git a/src/idevice.c b/src/idevice.c index 0577815..eed02fc 100644 --- a/src/idevice.c +++ b/src/idevice.c @@ -142,16 +142,6 @@ static void usbmux_event_cb(const usbmuxd_event_t *event, void *user_data) } } -/** - * 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) { event_cb = callback; @@ -164,12 +154,6 @@ idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_ return IDEVICE_E_SUCCESS; } -/** - * 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() { event_cb = NULL; @@ -181,15 +165,6 @@ idevice_error_t idevice_event_unsubscribe() return IDEVICE_E_SUCCESS; } -/** - * 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) { usbmuxd_device_info_t *dev_list; @@ -220,13 +195,6 @@ idevice_error_t idevice_get_device_list(char ***devices, int *count) return IDEVICE_E_SUCCESS; } -/** - * 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) { if (devices) { @@ -240,19 +208,6 @@ idevice_error_t idevice_device_list_free(char **devices) return IDEVICE_E_SUCCESS; } -/** - * 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) { usbmuxd_device_info_t muxdev; @@ -270,13 +225,6 @@ idevice_error_t idevice_new(idevice_t * device, const char *udid) return IDEVICE_E_NO_DEVICE; } -/** - * 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) { if (!device) @@ -297,16 +245,6 @@ idevice_error_t idevice_free(idevice_t device) return ret; } -/** - * 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) { if (!device) { @@ -333,13 +271,6 @@ idevice_error_t idevice_connect(idevice_t device, uint16_t port, idevice_connect return IDEVICE_E_UNKNOWN_ERROR; } -/** - * 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) { if (!connection) { @@ -390,17 +321,6 @@ static idevice_error_t internal_connection_send(idevice_connection_t connection, } -/** - * 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) { if (!connection || !data || (connection->ssl_data && !connection->ssl_data->session)) { @@ -447,21 +367,6 @@ static idevice_error_t internal_connection_receive_timeout(idevice_connection_t return IDEVICE_E_UNKNOWN_ERROR; } -/** - * 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) { if (!connection || (connection->ssl_data && !connection->ssl_data->session)) { @@ -516,19 +421,6 @@ static idevice_error_t internal_connection_receive(idevice_connection_t connecti return IDEVICE_E_UNKNOWN_ERROR; } -/** - * 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) { if (!connection || (connection->ssl_data && !connection->ssl_data->session)) { @@ -552,9 +444,6 @@ idevice_error_t idevice_connection_receive(idevice_connection_t connection, char return internal_connection_receive(connection, data, len, recv_bytes); } -/** - * Gets the handle of the device. Depends on the connection type. - */ idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle) { if (!device) @@ -569,9 +458,6 @@ idevice_error_t idevice_get_handle(idevice_t device, uint32_t *handle) return IDEVICE_E_UNKNOWN_ERROR; } -/** - * Gets the unique id for the device. - */ idevice_error_t idevice_get_udid(idevice_t device, char **udid) { if (!device || !udid) @@ -741,15 +627,6 @@ static int internal_cert_callback(gnutls_session_t session, const gnutls_datum_t } #endif -/** - * 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) { if (!connection || connection->ssl_data) @@ -888,15 +765,6 @@ idevice_error_t idevice_connection_enable_ssl(idevice_connection_t connection) return ret; } -/** - * 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) { if (!connection) diff --git a/src/installation_proxy.c b/src/installation_proxy.c index 109df10..e3a8103 100644 --- a/src/installation_proxy.c +++ b/src/installation_proxy.c @@ -86,17 +86,6 @@ static instproxy_error_t instproxy_error(property_list_service_error_t err) return INSTPROXY_E_UNKNOWN_ERROR; } -/** - * 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) { property_list_service_client_t plistclient = NULL; @@ -114,19 +103,6 @@ instproxy_error_t instproxy_client_new(idevice_t device, lockdownd_service_descr return INSTPROXY_E_SUCCESS; } -/** - * 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) { instproxy_error_t err = INSTPROXY_E_UNKNOWN_ERROR; @@ -134,15 +110,6 @@ instproxy_error_t instproxy_client_start_service(idevice_t device, instproxy_cli return err; } -/** - * 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) { if (!client) @@ -195,20 +162,6 @@ static instproxy_error_t instproxy_send_command(instproxy_client_t client, const return err; } -/** - * 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) { if (!client || !client->parent || !result) @@ -461,85 +414,16 @@ static instproxy_error_t instproxy_install_or_upgrade(instproxy_client_t client, return instproxy_create_status_updater(client, status_cb, command, user_data); } -/** - * 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) { return instproxy_install_or_upgrade(client, pkg_path, client_options, status_cb, "Install", 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) { return instproxy_install_or_upgrade(client, pkg_path, client_options, status_cb, "Upgrade", 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) { if (!client || !client->parent || !appid) { @@ -564,20 +448,6 @@ instproxy_error_t instproxy_uninstall(instproxy_client_t client, const char *app return instproxy_create_status_updater(client, status_cb, "Uninstall", 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) { if (!client || !client->parent || !result) @@ -604,30 +474,6 @@ leave_unlock: return res; } -/** - * 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) { if (!client || !client->parent || !appid) @@ -648,27 +494,6 @@ instproxy_error_t instproxy_archive(instproxy_client_t client, const char *appid return instproxy_create_status_updater(client, status_cb, "Archive", 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) { if (!client || !client->parent || !appid) @@ -689,27 +514,6 @@ instproxy_error_t instproxy_restore(instproxy_client_t client, const char *appid return instproxy_create_status_updater(client, status_cb, "Restore", 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) { if (!client || !client->parent || !appid) @@ -730,26 +534,11 @@ instproxy_error_t instproxy_remove_archive(instproxy_client_t client, const char return instproxy_create_status_updater(client, status_cb, "RemoveArchive", user_data); } -/** - * Create a new client_options plist. - * - * @return A new plist_t of type PLIST_DICT. - */ plist_t instproxy_client_options_new() { return plist_new_dict(); } -/** - * 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, ...) { if (!client_options) @@ -783,12 +572,6 @@ void instproxy_client_options_add(plist_t client_options, ...) va_end(args); } -/** - * 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) { if (client_options) { @@ -796,21 +579,6 @@ 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* appid, char** path) { if (!client || !client->parent || !appid) diff --git a/src/lockdown.c b/src/lockdown.c index 9b579e8..cf03e0f 100644 --- a/src/lockdown.c +++ b/src/lockdown.c @@ -154,16 +154,6 @@ static void plist_dict_add_label(plist_t plist, const char *label) } } -/** - * 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) { if (!client) @@ -247,14 +237,6 @@ static lockdownd_error_t lockdownd_client_free_simple(lockdownd_client_t client) return ret; } -/** - * 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) { if (!client) @@ -271,13 +253,6 @@ lockdownd_error_t lockdownd_client_free(lockdownd_client_t client) return ret; } -/** - * 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) { if (client) { @@ -288,15 +263,6 @@ void lockdownd_client_set_label(lockdownd_client_t client, const char *label) } } -/** - * 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) { if (!client || !plist || (plist && *plist)) @@ -315,18 +281,6 @@ lockdownd_error_t lockdownd_receive(lockdownd_client_t client, plist_t *plist) return ret; } -/** - * 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) { if (!client || !plist) @@ -342,15 +296,6 @@ lockdownd_error_t lockdownd_send(lockdownd_client_t client, plist_t plist) return ret; } -/** - * 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) { if (!client) @@ -396,16 +341,6 @@ lockdownd_error_t lockdownd_query_type(lockdownd_client_t client, char **type) return ret; } -/** - * 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) { if (!client) @@ -461,17 +396,6 @@ lockdownd_error_t lockdownd_get_value(lockdownd_client_t client, const char *dom return ret; } -/** - * 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) { if (!client || !value) @@ -520,17 +444,6 @@ lockdownd_error_t lockdownd_set_value(lockdownd_client_t client, const char *dom return ret; } -/** - * 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) { if (!client) @@ -578,15 +491,6 @@ lockdownd_error_t lockdownd_remove_value(lockdownd_client_t client, const char * return ret; } -/** - * 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 client, char **udid) { lockdownd_error_t ret = LOCKDOWN_E_UNKNOWN_ERROR; @@ -633,15 +537,6 @@ static lockdownd_error_t lockdownd_get_device_public_key_as_key_data(lockdownd_c return ret; } -/** - * 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) { lockdownd_error_t ret = LOCKDOWN_E_UNKNOWN_ERROR; @@ -659,21 +554,6 @@ lockdownd_error_t lockdownd_get_device_name(lockdownd_client_t client, char **de return ret; } -/** - * 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) { if (!client) @@ -707,23 +587,6 @@ lockdownd_error_t lockdownd_client_new(idevice_t device, lockdownd_client_t *cli return LOCKDOWN_E_SUCCESS; } -/** - * 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) { if (!client) @@ -1091,73 +954,21 @@ static lockdownd_error_t lockdownd_do_pair(lockdownd_client_t client, lockdownd_ return ret; } -/** - * 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) { return lockdownd_do_pair(client, pair_record, "Pair"); } -/** - * 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) { return lockdownd_do_pair(client, pair_record, "ValidatePair"); } -/** - * 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) { return lockdownd_do_pair(client, pair_record, "Unpair"); } -/** - * 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) { if (!client) @@ -1186,15 +997,6 @@ lockdownd_error_t lockdownd_enter_recovery(lockdownd_client_t client) return ret; } -/** - * 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) { if (!client) @@ -1228,19 +1030,6 @@ lockdownd_error_t lockdownd_goodbye(lockdownd_client_t client) return ret; } -/** - * 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) { lockdownd_error_t ret = LOCKDOWN_E_SUCCESS; @@ -1345,18 +1134,6 @@ lockdownd_error_t lockdownd_start_session(lockdownd_client_t client, const char return ret; } -/** - * 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) { if (!client || !identifier || !service) @@ -1442,24 +1219,7 @@ lockdownd_error_t lockdownd_start_service(lockdownd_client_t client, const char return ret; } -/** - * 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) +lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activation_record) { if (!client) return LOCKDOWN_E_INVALID_ARG; @@ -1510,16 +1270,6 @@ lockdownd_error_t lockdownd_activate(lockdownd_client_t client, plist_t activati return ret; } -/** - * 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) { if (!client) @@ -1567,19 +1317,6 @@ static void str_remove_spaces(char *source) *dest = 0; } -/** - * 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) { if (!client) @@ -1634,13 +1371,6 @@ lockdownd_error_t lockdownd_get_sync_data_classes(lockdownd_client_t client, cha } -/** - * 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) { if (classes) { @@ -1653,13 +1383,6 @@ lockdownd_error_t lockdownd_data_classes_free(char **classes) return LOCKDOWN_E_SUCCESS; } -/** - * 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) { if (service) diff --git a/src/misagent.c b/src/misagent.c index 6edbadd..96dddba 100644 --- a/src/misagent.c +++ b/src/misagent.c @@ -87,17 +87,6 @@ static misagent_error_t misagent_check_result(plist_t response, int* status_code } } -/** - * 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) { property_list_service_client_t plistclient = NULL; @@ -114,19 +103,6 @@ misagent_error_t misagent_client_new(idevice_t device, lockdownd_service_descrip return MISAGENT_E_SUCCESS; } -/** - * 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) { misagent_error_t err = MISAGENT_E_UNKNOWN_ERROR; @@ -134,15 +110,6 @@ misagent_error_t misagent_client_start_service(idevice_t device, misagent_client return err; } -/** - * 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) { if (!client) @@ -158,16 +125,6 @@ misagent_error_t misagent_client_free(misagent_client_t client) return err; } -/** - * 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) { if (!client || !client->parent || !profile || (plist_get_node_type(profile) != PLIST_DATA)) @@ -205,20 +162,6 @@ misagent_error_t misagent_install(misagent_client_t client, plist_t profile) return res; } -/** - * 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) { if (!client || !client->parent || !profiles) @@ -259,17 +202,6 @@ 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) { if (!client || !client->parent || !profileID) @@ -307,13 +239,6 @@ misagent_error_t misagent_remove(misagent_client_t client, const char* profileID return res; } -/** - * 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) { if (!client) { diff --git a/src/mobile_image_mounter.c b/src/mobile_image_mounter.c index 4b2818d..7133b8b 100644 --- a/src/mobile_image_mounter.c +++ b/src/mobile_image_mounter.c @@ -75,19 +75,6 @@ static mobile_image_mounter_error_t mobile_image_mounter_error(property_list_ser return MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR; } -/** - * 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) { property_list_service_client_t plistclient = NULL; @@ -105,19 +92,6 @@ mobile_image_mounter_error_t mobile_image_mounter_new(idevice_t device, lockdown return MOBILE_IMAGE_MOUNTER_E_SUCCESS; } -/** - * 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) { mobile_image_mounter_error_t err = MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR; @@ -125,15 +99,6 @@ mobile_image_mounter_error_t mobile_image_mounter_start_service(idevice_t device return err; } -/** - * 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) { if (!client) @@ -147,19 +112,6 @@ mobile_image_mounter_error_t mobile_image_mounter_free(mobile_image_mounter_clie return MOBILE_IMAGE_MOUNTER_E_SUCCESS; } -/** - * 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) { if (!client || !image_type || !result) { @@ -189,19 +141,6 @@ leave_unlock: return res; } -/** - * 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) { if (!client || !image_type || (image_size == 0) || !upload_cb) { @@ -311,27 +250,6 @@ leave_unlock: } -/** - * 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) { if (!client || !image_path || !image_signature || (signature_length == 0) || !image_type || !result) { @@ -363,17 +281,6 @@ leave_unlock: return res; } -/** - * 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) { if (!client) { diff --git a/src/mobilebackup.c b/src/mobilebackup.c index 66e590a..7107d12 100644 --- a/src/mobilebackup.c +++ b/src/mobilebackup.c @@ -60,18 +60,6 @@ static mobilebackup_error_t mobilebackup_error(device_link_service_error_t err) return MOBILEBACKUP_E_UNKNOWN_ERROR; } -/** - * 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) { if (!device || !service || service->port == 0 || !client || *client) @@ -99,19 +87,6 @@ mobilebackup_error_t mobilebackup_client_new(idevice_t device, lockdownd_service return ret; } -/** - * 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) { mobilebackup_error_t err = MOBILEBACKUP_E_UNKNOWN_ERROR; @@ -119,15 +94,6 @@ mobilebackup_error_t mobilebackup_client_start_service(idevice_t device, mobileb return err; } -/** - * 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) { if (!client) @@ -141,14 +107,6 @@ mobilebackup_error_t mobilebackup_client_free(mobilebackup_client_t client) return err; } -/** - * 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) { if (!client) @@ -157,17 +115,6 @@ mobilebackup_error_t mobilebackup_receive(mobilebackup_client_t client, plist_t return ret; } -/** - * 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) { if (!client || !plist) @@ -285,23 +232,6 @@ leave: return err; } -/** - * 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) { if (!client || !client->parent || !base_path || !proto_version) @@ -362,41 +292,11 @@ leave: return err; } -/** - * 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) { return mobilebackup_send_message(client, "kBackupMessageBackupFileReceived", NULL); } -/** - * 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) { if (!client || !client->parent || !backup_manifest || !proto_version) @@ -451,63 +351,16 @@ leave: return err; } -/** - * 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) { return mobilebackup_receive_message(client, "BackupMessageRestoreFileReceived", 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) { return mobilebackup_receive_message(client, "BackupMessageRestoreApplicationReceived", 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) { mobilebackup_error_t err = mobilebackup_send_message(client, "BackupMessageRestoreComplete", NULL); @@ -553,16 +406,6 @@ mobilebackup_error_t mobilebackup_send_restore_complete(mobilebackup_client_t cl return err; } -/** - * 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) { if (!client || !client->parent || !reason) diff --git a/src/mobilebackup2.c b/src/mobilebackup2.c index 09b156d..41fe5d3 100644 --- a/src/mobilebackup2.c +++ b/src/mobilebackup2.c @@ -61,18 +61,6 @@ static mobilebackup2_error_t mobilebackup2_error(device_link_service_error_t err return MOBILEBACKUP2_E_UNKNOWN_ERROR; } -/** - * 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) { @@ -101,19 +89,6 @@ mobilebackup2_error_t mobilebackup2_client_new(idevice_t device, lockdownd_servi return ret; } -/** - * 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) { mobilebackup2_error_t err = MOBILEBACKUP2_E_UNKNOWN_ERROR; @@ -121,15 +96,6 @@ mobilebackup2_error_t mobilebackup2_client_start_service(idevice_t device, mobil return err; } -/** - * 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) { if (!client) @@ -143,18 +109,6 @@ mobilebackup2_error_t mobilebackup2_client_free(mobilebackup2_client_t client) return err; } -/** - * 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) { if (!client || !client->parent || (!message && !options)) @@ -253,45 +207,11 @@ leave: return err; } -/** - * 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) { return mobilebackup2_error(device_link_service_receive_message(client->parent, msg_plist, 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) { if (!client || !client->parent || !data || (length == 0) || !bytes) @@ -318,24 +238,6 @@ mobilebackup2_error_t mobilebackup2_send_raw(mobilebackup2_client_t client, cons } } -/** - * 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) { if (!client || !client->parent || !data || (length == 0) || !bytes) @@ -363,17 +265,6 @@ mobilebackup2_error_t mobilebackup2_receive_raw(mobilebackup2_client_t client, c } } -/** - * 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) { int i; @@ -432,19 +323,6 @@ leave: return err; } -/** - * 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) { if (!client || !client->parent || !request || !target_identifier) @@ -476,18 +354,6 @@ mobilebackup2_error_t mobilebackup2_send_request(mobilebackup2_client_t client, return err; } -/** - * 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) { if (!client || !client->parent) diff --git a/src/mobilesync.c b/src/mobilesync.c index fd64e63..f0fc4b2 100644 --- a/src/mobilesync.c +++ b/src/mobilesync.c @@ -65,19 +65,6 @@ static mobilesync_error_t mobilesync_error(device_link_service_error_t err) return MOBILESYNC_E_UNKNOWN_ERROR; } -/** - * 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) { @@ -108,19 +95,6 @@ mobilesync_error_t mobilesync_client_new(idevice_t device, lockdownd_service_des return ret; } -/** - * 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) { mobilesync_error_t err = MOBILESYNC_E_UNKNOWN_ERROR; @@ -128,15 +102,6 @@ mobilesync_error_t mobilesync_client_start_service(idevice_t device, mobilesync_ return err; } -/** - * 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) { if (!client) @@ -147,14 +112,6 @@ mobilesync_error_t mobilesync_client_free(mobilesync_client_t client) return err; } -/** - * 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) { if (!client) @@ -163,17 +120,6 @@ mobilesync_error_t mobilesync_receive(mobilesync_client_t client, plist_t * plis return ret; } -/** - * 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) { if (!client || !plist) @@ -181,26 +127,6 @@ mobilesync_error_t mobilesync_send(mobilesync_client_t client, plist_t plist) return mobilesync_error(device_link_service_send(client->parent, 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) { if (!client || client->data_class || !data_class || @@ -327,17 +253,6 @@ mobilesync_error_t mobilesync_start(mobilesync_client_t client, const char *data return err; } -/** - * 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) { if (!client || !client->data_class) { @@ -423,49 +338,16 @@ static mobilesync_error_t mobilesync_get_records(mobilesync_client_t client, con return err; } -/** - * 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) { return mobilesync_get_records(client, "SDMessageGetAllRecordsFromDevice"); } -/** - * 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) { return mobilesync_get_records(client, "SDMessageGetChangesFromDevice"); } -/** - * 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) { if (!client || !client->data_class) { @@ -533,17 +415,6 @@ mobilesync_error_t mobilesync_receive_changes(mobilesync_client_t client, plist_ return err; } -/** - * 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) { if (!client || !client->data_class) { @@ -613,14 +484,6 @@ mobilesync_error_t mobilesync_clear_all_records_on_device(mobilesync_client_t cl return err; } -/** - * 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) { if (!client || !client->data_class) { @@ -655,23 +518,6 @@ static plist_t create_process_changes_message(const char *data_class, plist_t en return msg; } -/** - * 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) { if (!client || !client->data_class) { @@ -739,20 +585,6 @@ mobilesync_error_t mobilesync_ready_to_send_changes_from_computer(mobilesync_cli return err; } -/** - * 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) { if (!client || !client->data_class || !entities) { @@ -781,21 +613,6 @@ mobilesync_error_t mobilesync_send_changes(mobilesync_client_t client, plist_t e return err; } -/** - * 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) { if (!client || !client->data_class) { @@ -865,15 +682,6 @@ mobilesync_error_t mobilesync_remap_identifiers(mobilesync_client_t client, plis return err; } -/** - * 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) { if (!client || !client->data_class || !reason) { @@ -900,15 +708,6 @@ mobilesync_error_t mobilesync_cancel(mobilesync_client_t client, const char* rea return err; } -/** - * 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) { mobilesync_anchors_t anchors = (mobilesync_anchors_t) malloc(sizeof(mobilesync_anchors)); @@ -926,11 +725,6 @@ mobilesync_anchors_t mobilesync_anchors_new(const char *device_anchor, const cha return anchors; } -/** - * Free memory used by anchors. - * - * @param anchors The anchors to free. - */ void mobilesync_anchors_free(mobilesync_anchors_t anchors) { if (anchors->device_anchor != NULL) { @@ -945,28 +739,11 @@ void mobilesync_anchors_free(mobilesync_anchors_t anchors) anchors = NULL; } -/** - * 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() { return plist_new_dict(); } -/** - * 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, ...) { if (!actions) @@ -999,11 +776,6 @@ void mobilesync_actions_add(plist_t actions, ...) va_end(args); } -/** - * Free actions plist. - * - * @param actions The actions plist to free. Does nothing if NULL is passed. - */ void mobilesync_actions_free(plist_t actions) { if (actions) { diff --git a/src/notification_proxy.c b/src/notification_proxy.c index 1ccda6b..909ede4 100644 --- a/src/notification_proxy.c +++ b/src/notification_proxy.c @@ -86,18 +86,6 @@ static np_error_t np_error(property_list_service_error_t err) return NP_E_UNKNOWN_ERROR; } -/** - * 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) { property_list_service_client_t plistclient = NULL; @@ -116,19 +104,6 @@ np_error_t np_client_new(idevice_t device, lockdownd_service_descriptor_t servic return NP_E_SUCCESS; } -/** - * 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) { np_error_t err = NP_E_UNKNOWN_ERROR; @@ -136,14 +111,6 @@ np_error_t np_client_start_service(idevice_t device, np_client_t* client, const return err; } -/** - * 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) { if (!client) @@ -161,14 +128,6 @@ np_error_t np_client_free(np_client_t client) return NP_E_SUCCESS; } -/** - * 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) { if (!client || !notification) { @@ -220,15 +179,6 @@ np_error_t np_post_notification(np_client_t client, const char *notification) return res; } -/** - * 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 ) { if (!client || !notification) { @@ -250,17 +200,6 @@ np_error_t np_observe_notification( np_client_t client, const char *notification return res; } -/** - * 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) { int i = 0; @@ -390,28 +329,6 @@ void* np_notifier( void* arg ) return NULL; } -/** - * 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 *user_data ) { if (!client) diff --git a/src/restore.c b/src/restore.c index 6339270..2a025e8 100644 --- a/src/restore.c +++ b/src/restore.c @@ -89,14 +89,6 @@ static void plist_dict_add_label(plist_t plist, 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) { if (!client) @@ -127,13 +119,6 @@ restored_error_t restored_client_free(restored_client_t client) return ret; } -/** - * 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) { if (client) { @@ -144,15 +129,6 @@ void restored_client_set_label(restored_client_t client, const char *label) } } -/** - * 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) { if (!client || !plist || (plist && *plist)) @@ -172,18 +148,6 @@ restored_error_t restored_receive(restored_client_t client, plist_t *plist) return ret; } -/** - * 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) { if (!client || !plist) @@ -199,16 +163,6 @@ restored_error_t restored_send(restored_client_t client, plist_t plist) return ret; } -/** - * 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) { if (!client) @@ -268,15 +222,6 @@ restored_error_t restored_query_type(restored_client_t client, char **type, uint return ret; } -/** - * 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) { if (!client || !key) @@ -319,16 +264,7 @@ restored_error_t restored_query_value(restored_client_t client, const char *key, return ret; } -/** - * 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) +restored_error_t restored_get_value(restored_client_t client, const char *key, plist_t *value) { if (!client || !value || (value && *value)) return RESTORE_E_INVALID_ARG; @@ -355,15 +291,6 @@ restored_error_t restored_get_value(restored_client_t client, const char *key, p return ret; } -/** - * 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) { if (!client) @@ -405,14 +332,6 @@ restored_error_t restored_client_new(idevice_t device, restored_client_t *client return ret; } -/** - * 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) { if (!client) @@ -445,16 +364,6 @@ restored_error_t restored_goodbye(restored_client_t client) return ret; } -/** - * 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) { if (!client) @@ -479,14 +388,6 @@ restored_error_t restored_start_restore(restored_client_t client, plist_t option return ret; } -/** - * 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) { if (!client) diff --git a/src/sbservices.c b/src/sbservices.c index 1d043f1..ea12e35 100644 --- a/src/sbservices.c +++ b/src/sbservices.c @@ -76,17 +76,6 @@ static sbservices_error_t sbservices_error(property_list_service_error_t err) return SBSERVICES_E_UNKNOWN_ERROR; } -/** - * 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) { property_list_service_client_t plistclient = NULL; @@ -103,19 +92,6 @@ sbservices_error_t sbservices_client_new(idevice_t device, lockdownd_service_des return SBSERVICES_E_SUCCESS; } -/** - * 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) { sbservices_error_t err = SBSERVICES_E_UNKNOWN_ERROR; @@ -123,15 +99,6 @@ sbservices_error_t sbservices_client_start_service(idevice_t device, sbservices_ return err; } -/** - * 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) { if (!client) @@ -145,20 +112,6 @@ sbservices_error_t sbservices_client_free(sbservices_client_t client) return err; } -/** - * 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) { if (!client || !client->parent || !state) @@ -199,15 +152,6 @@ leave_unlock: return res; } -/** - * 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) { if (!client || !client->parent || !newstate) @@ -234,21 +178,6 @@ sbservices_error_t sbservices_set_icon_state(sbservices_client_t client, plist_t return res; } -/** - * 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) { if (!client || !client->parent || !bundleId || !pngdata) @@ -286,15 +215,6 @@ leave_unlock: return res; } -/** - * 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) { if (!client || !client->parent || !interface_orientation) @@ -333,20 +253,6 @@ leave_unlock: return res; } -/** - * 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) { if (!client || !client->parent || !pngdata) diff --git a/src/screenshotr.c b/src/screenshotr.c index a1b5759..e92fe9f 100644 --- a/src/screenshotr.c +++ b/src/screenshotr.c @@ -58,21 +58,6 @@ static screenshotr_error_t screenshotr_error(device_link_service_error_t err) return SCREENSHOTR_E_UNKNOWN_ERROR; } -/** - * 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) { @@ -101,19 +86,6 @@ screenshotr_error_t screenshotr_client_new(idevice_t device, lockdownd_service_d return ret; } -/** - * 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) { screenshotr_error_t err = SCREENSHOTR_E_UNKNOWN_ERROR; @@ -121,15 +93,6 @@ screenshotr_error_t screenshotr_client_start_service(idevice_t device, screensho return err; } -/** - * 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) { if (!client) @@ -140,20 +103,6 @@ screenshotr_error_t screenshotr_client_free(screenshotr_client_t client) return err; } -/** - * 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) { if (!client || !client->parent || !imgdata) diff --git a/src/service.c b/src/service.c index e8444b8..701c8b4 100644 --- a/src/service.c +++ b/src/service.c @@ -52,18 +52,6 @@ static service_error_t idevice_to_service_error(idevice_error_t err) return SERVICE_E_UNKNOWN_ERROR; } -/** - * 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) { if (!device || !service || service->port == 0 || !client || *client) @@ -88,21 +76,6 @@ service_error_t service_client_new(idevice_t device, lockdownd_service_descripto return SERVICE_E_SUCCESS; } -/** - * 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) { *client = NULL; @@ -142,15 +115,6 @@ service_error_t service_client_factory_start_service(idevice_t device, const cha return (ec == SERVICE_E_SUCCESS) ? SERVICE_E_SUCCESS : SERVICE_E_START_SERVICE_ERROR; } -/** - * 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) { if (!client) @@ -164,19 +128,6 @@ service_error_t service_client_free(service_client_t client) return err; } -/** - * 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) { service_error_t res = SERVICE_E_UNKNOWN_ERROR; @@ -198,21 +149,6 @@ service_error_t service_send(service_client_t client, const char* data, uint32_t return res; } -/** - * 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) { service_error_t res = SERVICE_E_UNKNOWN_ERROR; @@ -233,35 +169,11 @@ service_error_t service_receive_with_timeout(service_client_t client, char* data return res; } -/** - * 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) { return service_receive_with_timeout(client, data, size, received, 10000); } -/** - * 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) { if (!client || !client->connection) @@ -269,15 +181,6 @@ service_error_t service_enable_ssl(service_client_t client) return idevice_to_service_error(idevice_connection_enable_ssl(client->connection)); } -/** - * 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) { if (!client || !client->connection) diff --git a/src/syslog_relay.c b/src/syslog_relay.c index b908153..a636e6e 100644 --- a/src/syslog_relay.c +++ b/src/syslog_relay.c @@ -61,18 +61,6 @@ static syslog_relay_error_t syslog_relay_error(service_error_t err) return SYSLOG_RELAY_E_UNKNOWN_ERROR; } -/** - * 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) { *client = NULL; @@ -101,19 +89,6 @@ syslog_relay_error_t syslog_relay_client_new(idevice_t device, lockdownd_service return 0; } -/** - * 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) { syslog_relay_error_t err = SYSLOG_RELAY_E_UNKNOWN_ERROR; @@ -121,15 +96,6 @@ syslog_relay_error_t syslog_relay_client_start_service(idevice_t device, syslog_ return err; } -/** - * 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) { if (!client) @@ -146,38 +112,11 @@ syslog_relay_error_t syslog_relay_client_free(syslog_relay_client_t client) return err; } -/** - * 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) { return syslog_relay_receive_with_timeout(client, data, size, received, 1000); } -/** - * 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) { syslog_relay_error_t res = SYSLOG_RELAY_E_UNKNOWN_ERROR; @@ -232,20 +171,6 @@ void *syslog_relay_worker(void *arg) return NULL; } -/** - * 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) { if (!client || !callback) @@ -273,18 +198,6 @@ syslog_relay_error_t syslog_relay_start_capture(syslog_relay_client_t client, sy return res; } -/** - * 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) { if (client->worker) { diff --git a/src/webinspector.c b/src/webinspector.c index 14a8bd8..31c5b2c 100644 --- a/src/webinspector.c +++ b/src/webinspector.c @@ -58,18 +58,6 @@ static webinspector_error_t webinspector_error(property_list_service_error_t err return WEBINSPECTOR_E_UNKNOWN_ERROR; } -/** - * 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) { *client = NULL; @@ -97,19 +85,6 @@ webinspector_error_t webinspector_client_new(idevice_t device, lockdownd_service return 0; } -/** - * 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) { webinspector_error_t err = WEBINSPECTOR_E_UNKNOWN_ERROR; @@ -117,15 +92,6 @@ webinspector_error_t webinspector_client_start_service(idevice_t device, webinsp return err; } -/** - * 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) { if (!client) @@ -137,15 +103,6 @@ webinspector_error_t webinspector_client_free(webinspector_client_t client) return err; } -/** - * 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) { webinspector_error_t res = WEBINSPECTOR_E_UNKNOWN_ERROR; @@ -203,35 +160,11 @@ webinspector_error_t webinspector_send(webinspector_client_t client, plist_t pli return res; } -/** - * 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) { return webinspector_receive_with_timeout(client, plist, 5000); } -/** - * 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) { webinspector_error_t res = WEBINSPECTOR_E_UNKNOWN_ERROR; |