libimobiledevice: libimobiledevice/notification_proxy.h File Reference

libimobiledevice 1.3.0

Macros | Enumerations
notification_proxy.h File Reference

Observe and post notifications. More...

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

## 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.

## 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"
typedef struct np_client_private | np_client_private
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.
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...

## Detailed Description

Observe and post notifications.

## Function Documentation

## ◆ np_client_free()

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

  client | The notification_proxy client to disconnect and free.

Returns
  NP_E_SUCCESS on success, or NP_E_INVALID_ARG when client is NULL.

## ◆ np_client_new()

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

  device | The device to connect to.
  service | The service descriptor returned by lockdownd_start_service.
  client | Pointer 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_client_start_service()

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

  device | The device to connect to.
  client | Pointer that will point to a newly allocated np_client_t upon successful return. Must be freed using np_client_free() after use.
  label | The 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_observe_notification()

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

  client | The client to send to
  notification | The 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_observe_notifications()

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

  client | The client to send to
  notification_spec | Specification 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_post_notification()

np_error_t np_post_notification | ( | np_client_t | client,
|  | const char * | notification
| ) |  |

Sends a notification to the device's notification_proxy.

Parameters

  client | The client to send to
  notification | The notification message to send

Returns
  NP_E_SUCCESS on success, or an error returned by np_plist_send

## ◆ np_set_notify_callback()

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

  client | the NP client
  notify_cb | pointer to a callback function or NULL to de-register a previously set callback function.
  user_data | Pointer 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.