summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authorGravatar Martin Szulecki2010-03-16 03:13:38 +0100
committerGravatar Martin Szulecki2010-03-16 03:13:38 +0100
commit08d2af5d611319748afba2aaba5e6c8a99f1b396 (patch)
tree8bf4a3533f2acf11368dc37a9c653689ace99b77 /include
parent3e0c5021100c879ff7d0776d4c7bb4f0ec88e0d7 (diff)
downloadlibimobiledevice-08d2af5d611319748afba2aaba5e6c8a99f1b396.tar.gz
libimobiledevice-08d2af5d611319748afba2aaba5e6c8a99f1b396.tar.bz2
Complete documentation of public interface and fix a lot of bogus comments
This change unifies the documentation comment syntax, fixes a few bad documentation comments and completes documentation where it was missing.
Diffstat (limited to 'include')
-rw-r--r--include/libimobiledevice/afc.h27
-rw-r--r--include/libimobiledevice/file_relay.h5
-rw-r--r--include/libimobiledevice/installation_proxy.h6
-rw-r--r--include/libimobiledevice/libimobiledevice.h23
-rw-r--r--include/libimobiledevice/lockdown.h16
-rw-r--r--include/libimobiledevice/mobile_image_mounter.h5
-rw-r--r--include/libimobiledevice/mobilebackup.h5
-rw-r--r--include/libimobiledevice/mobilesync.h5
-rw-r--r--include/libimobiledevice/notification_proxy.h20
-rw-r--r--include/libimobiledevice/sbservices.h5
-rw-r--r--include/libimobiledevice/screenshotr.h5
11 files changed, 86 insertions, 36 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h
index d800d19..c060eb7 100644
--- a/include/libimobiledevice/afc.h
+++ b/include/libimobiledevice/afc.h
@@ -29,7 +29,8 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define AFC_E_SUCCESS 0
#define AFC_E_UNKNOWN_ERROR 1
#define AFC_E_OP_HEADER_INVALID 2
@@ -59,28 +60,32 @@ extern "C" {
#define AFC_E_NO_MEM 31
#define AFC_E_NOT_ENOUGH_DATA 32
#define AFC_E_DIR_NOT_EMPTY 33
+/*@}*/
+/** Represents an error code. */
typedef int16_t afc_error_t;
-/* Flags */
+/** Flags for afc_file_open */
typedef enum {
- AFC_FOPEN_RDONLY = 0x00000001, // r O_RDONLY
- AFC_FOPEN_RW = 0x00000002, // r+ O_RDWR | O_CREAT
- AFC_FOPEN_WRONLY = 0x00000003, // w O_WRONLY | O_CREAT | O_TRUNC
- AFC_FOPEN_WR = 0x00000004, // w+ O_RDWR | O_CREAT | O_TRUNC
- AFC_FOPEN_APPEND = 0x00000005, // a O_WRONLY | O_APPEND | O_CREAT
- AFC_FOPEN_RDAPPEND = 0x00000006 // a+ O_RDWR | O_APPEND | O_CREAT
+ AFC_FOPEN_RDONLY = 0x00000001, /**< r O_RDONLY */
+ AFC_FOPEN_RW = 0x00000002, /**< r+ O_RDWR | O_CREAT */
+ AFC_FOPEN_WRONLY = 0x00000003, /**< w O_WRONLY | O_CREAT | O_TRUNC */
+ AFC_FOPEN_WR = 0x00000004, /**< w+ O_RDWR | O_CREAT | O_TRUNC */
+ AFC_FOPEN_APPEND = 0x00000005, /**< a O_WRONLY | O_APPEND | O_CREAT */
+ AFC_FOPEN_RDAPPEND = 0x00000006 /**< a+ O_RDWR | O_APPEND | O_CREAT */
} afc_file_mode_t;
+/** Type of link for afc_make_link() calls */
typedef enum {
AFC_HARDLINK = 1,
AFC_SYMLINK = 2
} afc_link_type_t;
+/** Lock operation flags */
typedef enum {
- AFC_LOCK_SH = 1 | 4, // shared lock
- AFC_LOCK_EX = 2 | 4, // exclusive lock
- AFC_LOCK_UN = 8 | 4 // unlock
+ AFC_LOCK_SH = 1 | 4, /**< shared lock */
+ AFC_LOCK_EX = 2 | 4, /**< exclusive lock */
+ AFC_LOCK_UN = 8 | 4 /**< unlock */
} afc_lock_op_t;
typedef struct afc_client_private afc_client_private;
diff --git a/include/libimobiledevice/file_relay.h b/include/libimobiledevice/file_relay.h
index dd65b38..b3900db 100644
--- a/include/libimobiledevice/file_relay.h
+++ b/include/libimobiledevice/file_relay.h
@@ -29,7 +29,8 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define FILE_RELAY_E_SUCCESS 0
#define FILE_RELAY_E_INVALID_ARG -1
#define FILE_RELAY_E_PLIST_ERROR -2
@@ -38,7 +39,9 @@ extern "C" {
#define FILE_RELAY_E_STAGING_EMPTY -5
#define FILE_RELAY_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t file_relay_error_t;
typedef struct file_relay_client_private file_relay_client_private;
diff --git a/include/libimobiledevice/installation_proxy.h b/include/libimobiledevice/installation_proxy.h
index 8a7cfb9..2bf738d 100644
--- a/include/libimobiledevice/installation_proxy.h
+++ b/include/libimobiledevice/installation_proxy.h
@@ -30,7 +30,8 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
#include <glib.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define INSTPROXY_E_SUCCESS 0
#define INSTPROXY_E_INVALID_ARG -1
#define INSTPROXY_E_PLIST_ERROR -2
@@ -39,12 +40,15 @@ extern "C" {
#define INSTPROXY_E_OP_FAILED -5
#define INSTPROXY_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t instproxy_error_t;
typedef struct instproxy_client_private instproxy_client_private;
typedef instproxy_client_private *instproxy_client_t; /**< The client handle. */
+/** Reports the status of the given operation */
typedef void (*instproxy_status_cb_t) (const char *operation, plist_t status);
/* Interface */
diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h
index 73e82fe..0c6a08f 100644
--- a/include/libimobiledevice/libimobiledevice.h
+++ b/include/libimobiledevice/libimobiledevice.h
@@ -1,6 +1,6 @@
/**
* @file libimobiledevice/libimobiledevice.h
- * @brief Common code and device handling
+ * @brief Device/Connection handling and communication
* \internal
*
* Copyright (c) 2008 Jonathan Beck All Rights Reserved.
@@ -32,7 +32,8 @@ extern "C" {
#include <sys/stat.h>
#include <plist/plist.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define IDEVICE_E_SUCCESS 0
#define IDEVICE_E_INVALID_ARG -1
#define IDEVICE_E_UNKNOWN_ERROR -2
@@ -40,7 +41,9 @@ extern "C" {
#define IDEVICE_E_NOT_ENOUGH_DATA -4
#define IDEVICE_E_BAD_HEADER -5
#define IDEVICE_E_SSL_ERROR -6
+/*@}*/
+/** Represents an error code. */
typedef int16_t idevice_error_t;
typedef struct idevice_private idevice_private;
@@ -53,23 +56,25 @@ typedef idevice_connection_private *idevice_connection_t; /**< The connection ha
void idevice_set_debug_level(int level);
/* discovery (events/asynchronous) */
-// event type
+/** The event type for device add or removal */
enum idevice_event_type {
IDEVICE_DEVICE_ADD = 1,
IDEVICE_DEVICE_REMOVE
};
-// event data structure
+/* event data structure */
+/** Provides information about the occoured event. */
typedef struct {
- enum idevice_event_type event;
- const char *uuid;
- int conn_type;
+ enum idevice_event_type event; /**< The event type. */
+ const char *uuid; /**< The device unique id. */
+ int conn_type; /**< The connection type. Currently only 1 for usbmuxd. */
} idevice_event_t;
-// event callback function prototype
+/* event callback function prototype */
+/** Callback to notifiy if a device was added or removed. */
typedef void (*idevice_event_cb_t) (const idevice_event_t *event, void *user_data);
-// functions
+/* functions */
idevice_error_t idevice_event_subscribe(idevice_event_cb_t callback, void *user_data);
idevice_error_t idevice_event_unsubscribe();
diff --git a/include/libimobiledevice/lockdown.h b/include/libimobiledevice/lockdown.h
index 6abf6d6..4504ef1 100644
--- a/include/libimobiledevice/lockdown.h
+++ b/include/libimobiledevice/lockdown.h
@@ -1,6 +1,6 @@
/**
* @file libimobiledevice/lockdown.h
- * @brief Communcation with the lockdown device daemon
+ * @brief Implementation to communicate with the lockdown device daemon
* \internal
*
* Copyright (c) 2008 Zach C. All Rights Reserved.
@@ -30,7 +30,8 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define LOCKDOWN_E_SUCCESS 0
#define LOCKDOWN_E_INVALID_ARG -1
#define LOCKDOWN_E_INVALID_CONF -2
@@ -52,18 +53,21 @@ extern "C" {
#define LOCKDOWN_E_INVALID_ACTIVATION_RECORD -18
#define LOCKDOWN_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t lockdownd_error_t;
typedef struct lockdownd_client_private lockdownd_client_private;
typedef lockdownd_client_private *lockdownd_client_t; /**< The client handle. */
struct lockdownd_pair_record {
- char *device_certificate;
- char *host_certificate;
- char *host_id;
- char *root_certificate;
+ char *device_certificate; /**< The device certificate */
+ char *host_certificate; /**< The host certificate */
+ char *host_id; /**< A unique HostID for the host computer */
+ char *root_certificate; /**< The root certificate */
};
+/** A pair record holding device, host and root certificates along the host_id */
typedef struct lockdownd_pair_record *lockdownd_pair_record_t;
/* Interface */
diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h
index 5681d8b..26a3666 100644
--- a/include/libimobiledevice/mobile_image_mounter.h
+++ b/include/libimobiledevice/mobile_image_mounter.h
@@ -29,14 +29,17 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define MOBILE_IMAGE_MOUNTER_E_SUCCESS 0
#define MOBILE_IMAGE_MOUNTER_E_INVALID_ARG -1
#define MOBILE_IMAGE_MOUNTER_E_PLIST_ERROR -2
#define MOBILE_IMAGE_MOUNTER_E_CONN_FAILED -3
#define MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t mobile_image_mounter_error_t;
typedef struct mobile_image_mounter_client_private mobile_image_mounter_client_private;
diff --git a/include/libimobiledevice/mobilebackup.h b/include/libimobiledevice/mobilebackup.h
index d6f9013..6f37a14 100644
--- a/include/libimobiledevice/mobilebackup.h
+++ b/include/libimobiledevice/mobilebackup.h
@@ -29,7 +29,8 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define MOBILEBACKUP_E_SUCCESS 0
#define MOBILEBACKUP_E_INVALID_ARG -1
#define MOBILEBACKUP_E_PLIST_ERROR -2
@@ -38,7 +39,9 @@ extern "C" {
#define MOBILEBACKUP_E_REPLY_NOT_OK -5
#define MOBILEBACKUP_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t mobilebackup_error_t;
typedef struct mobilebackup_client_private mobilebackup_client_private;
diff --git a/include/libimobiledevice/mobilesync.h b/include/libimobiledevice/mobilesync.h
index 2e330ee..7af3aef 100644
--- a/include/libimobiledevice/mobilesync.h
+++ b/include/libimobiledevice/mobilesync.h
@@ -29,7 +29,8 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define MOBILESYNC_E_SUCCESS 0
#define MOBILESYNC_E_INVALID_ARG -1
#define MOBILESYNC_E_PLIST_ERROR -2
@@ -37,7 +38,9 @@ extern "C" {
#define MOBILESYNC_E_BAD_VERSION -4
#define MOBILESYNC_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t mobilesync_error_t;
typedef struct mobilesync_client_private mobilesync_client_private;
diff --git a/include/libimobiledevice/notification_proxy.h b/include/libimobiledevice/notification_proxy.h
index 74b6b37..d85f56c 100644
--- a/include/libimobiledevice/notification_proxy.h
+++ b/include/libimobiledevice/notification_proxy.h
@@ -29,23 +29,36 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define NP_E_SUCCESS 0
#define NP_E_INVALID_ARG -1
#define NP_E_PLIST_ERROR -2
#define NP_E_CONN_FAILED -3
#define NP_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t np_error_t;
-/* Notification IDs for use with post_notification (client --> device) */
+/**
+ * @name Notifications that can be send
+ *
+ * For use with np_post_notification() (client --> device)
+ */
#define NP_SYNC_WILL_START "com.apple.itunes-mobdev.syncWillStart"
#define NP_SYNC_DID_START "com.apple.itunes-mobdev.syncDidStart"
#define NP_SYNC_DID_FINISH "com.apple.itunes-mobdev.syncDidFinish"
#define NP_SYNC_LOCK_REQUEST "com.apple.itunes-mobdev.syncLockRequest"
+/*@}*/
-/* Notification IDs for use with observe_notification (device --> client) */
+/**
+ * @name Notifications that can be received
+ *
+ * For use with np_observe_notification() (device --> client)
+ */
+/*@{*/
#define NP_SYNC_CANCEL_REQUEST "com.apple.itunes-client.syncCancelRequest"
#define NP_SYNC_SUSPEND_REQUEST "com.apple.itunes-client.syncSuspendRequest"
#define NP_SYNC_RESUME_REQUEST "com.apple.itunes-client.syncResumeRequest"
@@ -67,6 +80,7 @@ typedef int16_t np_error_t;
#define NP_ITDBPREP_DID_END "com.apple.itdbprep.notification.didEnd"
#define NP_LANGUAGE_CHANGED "com.apple.language.changed"
#define NP_ADDRESS_BOOK_PREF_CHANGED "com.apple.AddressBook.PreferenceChanged"
+/*@}*/
typedef struct np_client_private np_client_private;
typedef np_client_private *np_client_t; /**< The client handle. */
diff --git a/include/libimobiledevice/sbservices.h b/include/libimobiledevice/sbservices.h
index 0fcec86..71e951e 100644
--- a/include/libimobiledevice/sbservices.h
+++ b/include/libimobiledevice/sbservices.h
@@ -29,14 +29,17 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define SBSERVICES_E_SUCCESS 0
#define SBSERVICES_E_INVALID_ARG -1
#define SBSERVICES_E_PLIST_ERROR -2
#define SBSERVICES_E_CONN_FAILED -3
#define SBSERVICES_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t sbservices_error_t;
typedef struct sbservices_client_private sbservices_client_private;
diff --git a/include/libimobiledevice/screenshotr.h b/include/libimobiledevice/screenshotr.h
index d9a3ffd..7e5c8a7 100644
--- a/include/libimobiledevice/screenshotr.h
+++ b/include/libimobiledevice/screenshotr.h
@@ -29,7 +29,8 @@ extern "C" {
#include <libimobiledevice/libimobiledevice.h>
-/* Error Codes */
+/** @name Error Codes */
+/*@{*/
#define SCREENSHOTR_E_SUCCESS 0
#define SCREENSHOTR_E_INVALID_ARG -1
#define SCREENSHOTR_E_PLIST_ERROR -2
@@ -37,7 +38,9 @@ extern "C" {
#define SCREENSHOTR_E_BAD_VERSION -4
#define SCREENSHOTR_E_UNKNOWN_ERROR -256
+/*@}*/
+/** Represents an error code. */
typedef int16_t screenshotr_error_t;
typedef struct screenshotr_client_private screenshotr_client_private;