libimobiledevice 1.1.1
Typedefs | Functions

libimobiledevice/notification_proxy.h File Reference

Observe and post notifications. More...

Typedefs

typedef int16_t np_error_t
 Represents an error code.
typedef np_client_privatenp_client_t
 The client handle.
typedef void(* np_notify_cb_t )(const char *notification, void *user_data)
 Reports which notification was received.

Functions

np_error_t np_client_new (idevice_t device, uint16_t port, np_client_t *client)
 Connects to the notification_proxy on the specified device.
np_error_t np_client_free (np_client_t client)
 Disconnects a notification_proxy client from the device and frees up the notification_proxy client data.
np_error_t np_post_notification (np_client_t client, const char *notification)
 Sends a notification to the device's notification_proxy.
np_error_t np_observe_notification (np_client_t client, const char *notification)
 Tells the device to send a notification on the specified event.
np_error_t np_observe_notifications (np_client_t client, const char **notification_spec)
 Tells the device to send a notification on specified events.
np_error_t np_set_notify_callback (np_client_t client, np_notify_cb_t notify_cb, void *userdata)
 This function allows an application to define a callback function that will be called when a notification has been received.

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

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"

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"
#define NP_PHONE_NUMBER_CHANGED   "com.apple.mobile.lockdown.phone_number_changed"
#define NP_DEVICE_NAME_CHANGED   "com.apple.mobile.lockdown.device_name_changed"
#define NP_TIMEZONE_CHANGED   "com.apple.mobile.lockdown.timezone_changed"
#define NP_TRUSTED_HOST_ATTACHED   "com.apple.mobile.lockdown.trusted_host_attached"
#define NP_HOST_DETACHED   "com.apple.mobile.lockdown.host_detached"
#define NP_HOST_ATTACHED   "com.apple.mobile.lockdown.host_attached"
#define NP_REGISTRATION_FAILED   "com.apple.mobile.lockdown.registration_failed"
#define NP_ACTIVATION_STATE   "com.apple.mobile.lockdown.activation_state"
#define NP_BRICK_STATE   "com.apple.mobile.lockdown.brick_state"
#define NP_DISK_USAGE_CHANGED   "com.apple.mobile.lockdown.disk_usage_changed"
 iOS 4.0+
#define NP_DS_DOMAIN_CHANGED   "com.apple.mobile.data_sync.domain_changed"
#define NP_BACKUP_DOMAIN_CHANGED   "com.apple.mobile.backup.domain_changed"
#define NP_APP_INSTALLED   "com.apple.mobile.application_installed"
#define NP_APP_UNINSTALLED   "com.apple.mobile.application_uninstalled"
#define NP_DEV_IMAGE_MOUNTED   "com.apple.mobile.developer_image_mounted"
#define NP_ATTEMPTACTIVATION   "com.apple.springboard.attemptactivation"
#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"

Detailed Description

Observe and post notifications.


Typedef Documentation

The client handle.

typedef int16_t np_error_t

Represents an error code.

typedef void(* np_notify_cb_t)(const char *notification, void *user_data)

Reports which notification was received.


Function Documentation

np_error_t np_client_free ( np_client_t  client)

Disconnects a notification_proxy client from the device and frees up the notification_proxy client data.

Parameters:
clientThe notification_proxy client to disconnect and free.
Returns:
NP_E_SUCCESS on success, or NP_E_INVALID_ARG when client is NULL.
np_error_t np_client_new ( idevice_t  device,
uint16_t  port,
np_client_t client 
)

Connects to the notification_proxy on the specified device.

Parameters:
deviceThe device to connect to.
portDestination port (usually given by lockdownd_start_service).
clientPointer that will be set to a newly allocated np_client_t upon successful return.
Returns:
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_observe_notification ( np_client_t  client,
const char *  notification 
)

Tells the device to send a notification on the specified event.

Parameters:
clientThe client to send to
notificationThe notifications that should be observed.
Returns:
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_notifications ( np_client_t  client,
const char **  notification_spec 
)

Tells the device to send a notification on specified events.

Parameters:
clientThe client to send to
notification_specSpecification of the notifications that should be observed. This is expected to be an array of const char* that MUST have a terminating NULL entry.
Returns:
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_post_notification ( np_client_t  client,
const char *  notification 
)

Sends a notification to the device's notification_proxy.

Parameters:
clientThe client to send to
notificationThe notification message to send
Returns:
NP_E_SUCCESS on success, or an error returned by np_plist_send
np_error_t np_set_notify_callback ( np_client_t  client,
np_notify_cb_t  notify_cb,
void *  user_data 
)

This function allows an application to define a callback function that will be called when a notification has been received.

It will start a thread that polls for notifications and calls the callback function if a notification has been received.

Parameters:
clientthe NP client
notify_cbpointer to a callback function or NULL to de-register a previously set callback function.
user_dataPointer that will be passed to the callback function as user data. If notify_cb is NULL, this parameter is ignored.
Note:
Only one callback function can be registered at the same time; any previously set callback function will be removed automatically.
Returns:
NP_E_SUCCESS when the callback was successfully registered, NP_E_INVALID_ARG when client is NULL, or NP_E_UNKNOWN_ERROR when the callback thread could no be created.