From 08d2af5d611319748afba2aaba5e6c8a99f1b396 Mon Sep 17 00:00:00 2001 From: Martin Szulecki Date: Tue, 16 Mar 2010 03:13:38 +0100 Subject: 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. --- include/libimobiledevice/afc.h | 27 +++++++++++++++---------- include/libimobiledevice/file_relay.h | 5 ++++- include/libimobiledevice/installation_proxy.h | 6 +++++- include/libimobiledevice/libimobiledevice.h | 23 ++++++++++++--------- include/libimobiledevice/lockdown.h | 16 +++++++++------ include/libimobiledevice/mobile_image_mounter.h | 5 ++++- include/libimobiledevice/mobilebackup.h | 5 ++++- include/libimobiledevice/mobilesync.h | 5 ++++- include/libimobiledevice/notification_proxy.h | 20 +++++++++++++++--- include/libimobiledevice/sbservices.h | 5 ++++- include/libimobiledevice/screenshotr.h | 5 ++++- 11 files changed, 86 insertions(+), 36 deletions(-) (limited to 'include') 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 -/* 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 -/* 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 #include -/* 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 #include -/* 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 -/* 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 -/* 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 -/* 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 -/* 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 -/* 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 -/* 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 -/* 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; -- cgit v1.1-32-gdbae