summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatar Nikias Bassen2011-01-10 16:12:02 +0100
committerGravatar Martin Szulecki2011-04-11 19:42:19 +0200
commitca931097ff93286d65ecab3ab07156601c2e252f (patch)
tree10b21bbc1c5b1b801f20fa94863d82ba9b0aa339
parent850df2c4188541109b2d08a6b8ae2c627da21d78 (diff)
downloadlibimobiledevice-ca931097ff93286d65ecab3ab07156601c2e252f.tar.gz
libimobiledevice-ca931097ff93286d65ecab3ab07156601c2e252f.tar.bz2
mobilebackup2: Add missing function documentation
-rw-r--r--src/mobilebackup2.c74
1 files changed, 70 insertions, 4 deletions
diff --git a/src/mobilebackup2.c b/src/mobilebackup2.c
index 2fbadd2..ae7ac03 100644
--- a/src/mobilebackup2.c
+++ b/src/mobilebackup2.c
@@ -234,16 +234,47 @@ leave:
}
/**
- * TODO
+ * 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)
+ if (!client || !client->parent || !data || (length == 0) || !bytes)
return MOBILEBACKUP2_E_INVALID_ARG;
*bytes = 0;
@@ -267,9 +298,27 @@ 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)
+ if (!client || !client->parent || !data || (length == 0) || !bytes)
return MOBILEBACKUP2_E_INVALID_ARG;
idevice_connection_t conn = client->parent->parent->connection;
@@ -295,7 +344,12 @@ mobilebackup2_error_t mobilebackup2_receive_raw(mobilebackup2_client_t client, c
}
/**
- * TODO
+ * Performs the mobilebackup2 protocol version exchange.
+ *
+ * @param The MobileBackup client to use.
+ *
+ * @return MOBILEBACKUP2_E_SUCCESS on success, or a MOBILEBACKUP2_E_* error
+ * code otherwise.
*/
mobilebackup2_error_t mobilebackup2_version_exchange(mobilebackup2_client_t client)
{
@@ -386,6 +440,18 @@ 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)