libimobiledevice  1.2.0
Macros | Typedefs | Enumerations | Functions
notification_proxy.h File Reference

Observe and post notifications. More...

Macros

#define NP_SERVICE_NAME   "com.apple.mobile.notification_proxy"
 

Typedefs

typedef struct np_client_private np_client_private
 
typedef np_client_private * np_client_t
 The client handle. More...
 
typedef void(* np_notify_cb_t )(const char *notification, void *user_data)
 Reports which notification was received. More...
 

Enumerations

enum  np_error_t {
  NP_E_SUCCESS = 0,
  NP_E_INVALID_ARG = -1,
  NP_E_PLIST_ERROR = -2,
  NP_E_CONN_FAILED = -3,
  NP_E_UNKNOWN_ERROR = -256
}
 Error Codes.
 

Functions

np_error_t np_client_new (idevice_t device, lockdownd_service_descriptor_t service, np_client_t *client)
 Connects to the notification_proxy on the specified device. More...
 
np_error_t np_client_start_service (idevice_t device, np_client_t *client, const char *label)
 Starts a new notification proxy service on the specified device and connects to it. More...
 
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. More...
 
np_error_t np_post_notification (np_client_t client, const char *notification)
 Sends a notification to the device's notification_proxy. More...
 
np_error_t np_observe_notification (np_client_t client, const char *notification)
 Tells the device to send a notification on the specified event. More...
 
np_error_t np_observe_notifications (np_client_t client, const char **notification_spec)
 Tells the device to send a notification on specified events. More...
 
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. More...
 

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

typedef np_client_private* np_client_t

The client handle.

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,
lockdownd_service_descriptor_t  service,
np_client_t client 
)

Connects to the notification_proxy on the specified device.

Parameters
deviceThe device to connect to.
serviceThe service descriptor returned 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_client_start_service ( idevice_t  device,
np_client_t client,
const char *  label 
)

Starts a new notification proxy service on the specified device and connects to it.

Parameters
deviceThe device to connect to.
clientPointer that will point to a newly allocated np_client_t upon successful return. Must be freed using np_client_free() after use.
labelThe label to use for communication. Usually the program name. Pass NULL to disable sending the label in requests to lockdownd.
Returns
NP_E_SUCCESS on success, or an NP_E_* error code otherwise.
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 *  userdata 
)

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. In case of an error condition when polling for notifications - e.g. device disconnect - the thread will call the callback function with an empty notification "" and terminate itself.

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.