From ca931097ff93286d65ecab3ab07156601c2e252f Mon Sep 17 00:00:00 2001
From: Nikias Bassen
Date: Mon, 10 Jan 2011 16:12:02 +0100
Subject: mobilebackup2: Add missing function documentation

---
 src/mobilebackup2.c | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file 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)
-- 
cgit v1.1-32-gdbae