summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatar Nikias Bassen2009-12-09 20:27:09 +0100
committerGravatar Matt Colyer2009-12-11 08:58:07 -0800
commit4c00fb43042a1e8d1a4e2d29827d00ed3144575f (patch)
treeeb2adf1571f9eb177181fcb510cd631761a18509
parent318cc4f7b336109819c7b4c6a1a9f2e8d37d9bed (diff)
downloadlibimobiledevice-4c00fb43042a1e8d1a4e2d29827d00ed3144575f.tar.gz
libimobiledevice-4c00fb43042a1e8d1a4e2d29827d00ed3144575f.tar.bz2
Documentation cleanup and a new error code
[#96 state:resolved] Signed-off-by: Matt Colyer <matt@colyer.name>
-rw-r--r--include/libiphone/notification_proxy.h1
-rw-r--r--src/NotificationProxy.c39
2 files changed, 30 insertions, 10 deletions
diff --git a/include/libiphone/notification_proxy.h b/include/libiphone/notification_proxy.h
index 66b7a80..96af5fd 100644
--- a/include/libiphone/notification_proxy.h
+++ b/include/libiphone/notification_proxy.h
@@ -33,6 +33,7 @@ extern "C" {
#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
diff --git a/src/NotificationProxy.c b/src/NotificationProxy.c
index 884be5f..160ac4a 100644
--- a/src/NotificationProxy.c
+++ b/src/NotificationProxy.c
@@ -62,7 +62,9 @@ static void np_unlock(np_client_t client)
* @param client NP to send data to
* @param dict plist to send
*
- * @return NP_E_SUCCESS or an error code.
+ * @return NP_E_SUCCESS on success, NP_E_INVALID_ARG when client or dict
+ * are NULL, NP_E_PLIST_ERROR when dict is not a valid plist,
+ * or NP_E_UNKNOWN_ERROR when an unspecified error occurs.
*/
static np_error_t np_plist_send(np_client_t client, plist_t dict)
{
@@ -105,11 +107,14 @@ static np_error_t np_plist_send(np_client_t client, plist_t dict)
/** Makes a connection to the NP service on the phone.
*
- * @param phone The iPhone to connect on.
- * @param s_port The source port.
- * @param d_port The destination port.
+ * @param device The device to connect to.
+ * @param dst_port Destination port (usually given by lockdownd_start_service).
+ * @param client Pointer that will be set to a newly allocated np_client_t
+ * upon successful return.
*
- * @return A handle to the newly-connected client or NULL upon error.
+ * @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(iphone_device_t device, int dst_port, np_client_t *client)
{
@@ -123,7 +128,7 @@ np_error_t np_client_new(iphone_device_t device, int dst_port, np_client_t *clie
/* Attempt connection */
iphone_connection_t connection = NULL;
if (iphone_device_connect(device, dst_port, &connection) != IPHONE_E_SUCCESS) {
- return NP_E_UNKNOWN_ERROR;
+ return NP_E_CONN_FAILED;
}
np_client_t client_loc = (np_client_t) malloc(sizeof(struct np_client_int));
@@ -137,9 +142,11 @@ np_error_t np_client_new(iphone_device_t device, int dst_port, np_client_t *clie
return NP_E_SUCCESS;
}
-/** Disconnects an NP client from the phone.
+/** Disconnects an NP client from the device.
*
* @param client The client to disconnect.
+ *
+ * @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)
{
@@ -168,6 +175,8 @@ np_error_t np_client_free(np_client_t client)
*
* @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)
{
@@ -201,6 +210,9 @@ np_error_t np_post_notification(np_client_t client, const char *notification)
*
* @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 )
{
@@ -241,6 +253,9 @@ np_error_t np_observe_notification( np_client_t client, const char *notification
* observed. This is expected to be an array of const char* that MUST have a
* terminating NULL entry. However this parameter can be NULL; in this case,
* the default set of notifications will be used.
+ *
+ * @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)
{
@@ -275,7 +290,7 @@ np_error_t np_observe_notifications(np_client_t client, const char **notificatio
* with the notification that has been received.
*
* @return 0 if a notification has been received or nothing has been received,
- * or an error value if an error occured.
+ * or a negative value if an error occured.
*
* @note You probably want to check out np_set_notify_callback
* @see np_set_notify_callback
@@ -401,10 +416,14 @@ gpointer np_notifier( gpointer arg )
*
* @param client the NP client
* @param notify_cb pointer to a callback function or NULL to de-register a
- * previously set callback function
+ * previously set callback function.
+ *
+ * @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,
- * or an error value when an error occured.
+ * 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 )
{