MAPIClientLibraries 2.0 API Documentation

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

- File List
- Globals

Functions
IMAPISupport.c File Reference

MAPI notifications functions. More...

`#include "libmapi/libmapi.h"`
`#include "libmapi/libmapi_private.h"`

## Functions
_PUBLIC_ enum MAPISTATUS | DispatchNotifications (struct mapi_session *session)
_PUBLIC_ enum MAPISTATUS | MonitorNotification (struct mapi_session *session, void *private_data, struct mapi_notify_continue_callback_data *cb_data)
_PUBLIC_ enum MAPISTATUS | Subscribe (mapi_object_t *obj, uint32_t *connection, uint16_t NotificationFlags, bool WholeStore, mapi_notify_callback_t notify_callback, void *private_data)
_PUBLIC_ enum MAPISTATUS | Unsubscribe (struct mapi_session *session, uint32_t ulConnection)

## Detailed Description

MAPI notifications functions.

## Function Documentation

_PUBLIC_ enum MAPISTATUS DispatchNotifications | ( | struct mapi_session * | session | ) |

Force notification of pending events

This function force the server to send any pending notificaion and process them. These MAPI notifications are next compared to the registered ones and the callback specified in Subscribe() called if it matches.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  RegisterNotification, Subscribe, Unsubscribe, GetLastError

References emsmdb_transaction_null().

_PUBLIC_ enum MAPISTATUS MonitorNotification | ( | struct mapi_session * | session,
|  | void * | private_data,
|  | struct mapi_notify_continue_callback_data * | cb_data
| ) |  |

Wait for notifications and process them

This function waits for notifications on the UDP port and generates the traffic needed to receive MAPI notifications. These MAPI notifications are next compared to the registered ones and the callback specified in Subscribe() called if it matches.

The function takes a callback in cb_data to check if it should continue to process notifications. Timeval in cb_data can be used to control the behavior of select.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  RegisterNotification, Subscribe, Unsubscribe, GetLastError

Note
  This code is experimental. The current implementation is non-threaded, only supports fnevNewmail and fnevCreatedObject notifications and will block your process until you send a signal.

References emsmdb_transaction_null().

_PUBLIC_ enum MAPISTATUS Subscribe | ( | mapi_object_t * | obj,
|  | uint32_t * | connection,
|  | uint16_t | NotificationFlags,
|  | bool | WholeStore,
|  | mapi_notify_callback_t | notify_callback,
|  | void * | private_data
| ) |  |

Register an object to receive notifications

This function registers notifications on the Exchange server for an object. The function holds the notifications intended to be monitored in as a bitmask.

Parameters

  obj | the object to get notifications for
  connection | connection identifier for callback function
  NotificationFlags | mask for events to provide notifications for (see below)
  WholeStore | whether the scope for this notification is whole database
  notify_callback | notification callback function.
  private_data | the data to be passed at the callback function when invoked

The Notification Flags can take the following values:

- fnevCriticalError
- fnevNewMail
- fnevObjectCreated
- fnevObjectDeleted
- fnevObjectModified
- fnevObjectMoved
- fnevObjectCopied
- fnevSearchComplete
- fnevTableModified
- fnevStatusObjectModified
- fnevReservedForMapi
- fnevExtended

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  RegisterNotification, Unsubscribe, MonitorNotification, GetLastError

References mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_init(), mapi_object_set_handle(), and mapi_object_set_session().

_PUBLIC_ enum MAPISTATUS Unsubscribe | ( | struct mapi_session * | session,
|  | uint32_t | ulConnection
| ) |  |

Unregister notifications on a given object.

Cancel any notification registrations associated with the notify object. This function unregisters notifications on the Exchange server for the object specified with its connection number ulConnection. The function will releases the notification on the Exchange server and remove the entry from the internal notifications list.

The function takes a callback to execute when such notification occurs and returns the ulConnection identifier we can use in further management.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  RegisterNotification, Subscribe, MonitorNotification, GetLastError

References Release().

| This content is licensed under the Creative Commons Attribution ShareAlike License v. 3.0: http://creativecommons.org/licenses/by-sa/3.0/