libmapi/IMAPISupport.c File Reference

MAPI notifications functions. More...

#include <libmapi/libmapi.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)
enum MAPISTATUS ProcessNotification (struct mapi_notify_ctx *notify_ctx, struct mapi_response *mapi_response)
_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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction_null(), global_mapi_ctx, mapi_session::notify_ctx, OPENCHANGE_RETVAL_IF, and ProcessNotification().

_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 mapi_notify_continue_callback_data::callback, mapi_provider::ctx, mapi_notify_continue_callback_data::data, mapi_session::emsmdb, emsmdb_transaction_null(), mapi_notify_ctx::fd, global_mapi_ctx, mapi_session::notify_ctx, OPENCHANGE_RETVAL_IF, ProcessNotification(), and mapi_notify_continue_callback_data::tv.

_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 callabck 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 notifications::callback, mapi_provider::ctx, DLIST_ADD, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_id(), mapi_object_get_logon_id(), mapi_object_get_session(), mapi_object_init(), mapi_object_set_handle(), mapi_object_set_session(), notifications::NotificationFlags, mapi_notify_ctx::notifications, mapi_session::notify_ctx, notifications::obj_notif, OPENCHANGE_RETVAL_IF, notifications::parentID, notifications::private_data, and notifications::ulConnection.

_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 DLIST_REMOVE, global_mapi_ctx, notifications::next, mapi_notify_ctx::notifications, mapi_session::notify_ctx, notifications::obj_notif, OPENCHANGE_RETVAL_IF, Release(), and notifications::ulConnection.


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