Messaging Server Specific Event Notification Service Information

13 Messaging Server Specific Event Notification Service Information

This chapter describes the Oracle Communications Messaging Server specific items that are necessary to use the Event Notification Service (ENS) APIs.

Event Notification Types and Options

For Messaging Server, there is only one event reference, which can be composed of several options. There are various types of event notifications. Table 13-1 lists the event types supported by Messaging Server and gives a description of each. Event notifications are also generated when a user creates, deletes, or renames a folder.

Event Types

Table 13-1 Event Types

Event Types	Description
AnnotateMsg	Shows when annotations or notes are added to a message or deleted from a message.
ChangeFlag	Shows change status as "1" add, "2" remove, or "3" replace.
Copy	Copies one or more messages from one mailbox to another mailbox. If the CopyMsg event is not set, UpdateMsgs event is triggered when messages are copied.
DeleteMsg	When a message is deleted by a user, IMAP client of the user flags this message with \Deleted. It means, IMAP has moved the message to the trash folder.
ExpungeMsg	Messages are deleted permanently from the mailbox which were flagged with \Deleted by using DeleteMsg event.
Login	User logged in from IMAP, HTTP, or POP.
Logout	User logged out from IMAP, HTTP, or POP.
MsgFlags	Shows when flags on a message are changed. For example, when a read message is flagged as unread.
NewMsg	New message was received by the system into the user's mailbox. Can have a payload of message headers and body.
OverQuota	Operation failed because the user's mailbox exceeded one of the quotas (diskquota, msgquota). The MTA channel holds the message until the quota changes or the user's mail box count goes below the quota. If the message expires while it is being held by the MTA, it will be expunged.
PurgeMsg	Message expunged (as a result of an expired date) from the mailbox by the server process imexpire. This is a server side expunge, whereas DeleteMsg is a client side expunge. This is not a purge in the true sense of the word.
ReadMsg	Message in the mailbox was read (in the IMAP protocol, the message was marked Seen).
TrashMsg	Message was marked for deletion by IMAP or HTTP. The user may still see the message in the folder, depending on the mail client's configuration. The messages are to be removed from the folder when an expunge is performed.
UnderQuota	Quota went back to normal from OverQuota state.
UpdateMsg	Message was appended to the mailbox (other than by NewMsg). for example, the user copied an email message to the mailbox. Can have a payload of message headers and body.

The following applies to the above supported event types:

For NewMsg and UpdateMsg, message pay load is turned off by default to prevent overloading ENS. See "Payload" for information on how to enable the payload. No other event types support a payload.
Event notifications can be generated for changes to the INBOX alone, or to the INBOX and all other folders. The following configuration variable allows for INBOX only (value = 0), or for both the INBOX and all other folders (value = 1):
```
local.store.notifyplugin.noneInbox.enable
```
The default setting is for INBOX only (value = 0).

Note:

There is no mechanism to select folders; all folders are included when the variable is enabled (value = 1).
The NewMsg notification is issued only after the message is deposited in the user mailbox (as opposed to "after it was accepted by the server and queued in the message queue").
Every notification carries several pieces of information (called options) depending on the event type, for example, NewMsg indicates the IMAP uid of the new message. See "Available Options for Each Event Type" for details on the options each event type takes
Events are not generated for POP3 client access.
All event types can be suppressed by issuing XNOTNOTIFY. For example, an IMAP script used for housekeeping only (the users are not meant to be notified) might issue it to suppress all events.

Options

iBiff uses the following format for the ENS event reference:

enp://127.0.0.1/store_?param_=_value&amp;param1_=_value1&amp;param2_=_value2_

The event key enp://127.0.0.1/store has no significance other than its uniqueness as a string. For example, the hostname portion of the event key has no significance as a hostname. It is simply a string that is part of the URI. However, the event key is user configurable. The list of iBiff event reference options is listed in tables "Mandatory Event Reference Options" and "Optional Event Reference Options" that follow.

The second part of the event reference consists of option-value pairs. This part of the event reference is separated from the event key by a question mark (?). The option and value are separated by an equals sign (=). The option-value pairs are separated by an ampersand (&). Note that there can be empty values, for which the value simply does not exist.

Mandatory Event Reference Options

Table 13-2 describes the mandatory event reference options that must be included in every notification.

Table 13-2 Mandatory Event Reference Options

Option	Data Type	Description
evtType	string	Specifies the event type.
hostname	string	The hostname of the machine that generated the event.
mailboxName	string	Specifies the mailbox name in the message store. The mailboxName has the format uid@domain, where uid is the user's unique identifier, and domain is the domain the user belongs to. The @domain portion is added only when the user does not belong to the default domain (i.e. the user is in a hosted domain).
pid	integer	ID of the process that generated the event.
process	string	Specifies the name of the process that generated the event.
timestamp	64-bit integer	Specifies the number of milliseconds since the epoch (midnight GMT, January 1, 1970).

Optional Event Reference Options

Table 13-3 describes optional event reference options, which might be seen in the event depending on the event type (see "Available Options for Each Event Type" for more information.)

Table 13-3 Optional Event Reference Options

Option	Data Type	Description
attrn	string	Specifies an attribute of the nth annotation. This attribute can be either value.shared or value.priv.
authid	string	Specifies the original user name passed by a client.
ctx	integer	Specifies the context within a process which generates an event.
client	IP address	The IP address of the client logging in or out.
diskquota	signed 32-bit integer	Specifies the disk space quota in kilobytes. The value is set to -1 to indicate no quotas.
diskquotaused	signed 64-bit integer	Specifies the volume of disk space in kilobytes that is being used by a user associated with the event.
entryn	string	Specifies the entry of the nth annotation. For example, /comment.
frommailboxName	string	Specifies the name of the mailbox from which messages were copied.
fromUidList	string	Specifies the list of UIDs as a comma separated list. This list shows messages that were copied from the original mailbox.
fromuidValidity	unsigned 32-bit integer	Specifies uidValidty from the original mailbox.
hdrLen	unsigned 32-bit integer	Specifies the size of the message header. Note that this might not be the size of the header in the payload, because it might have been truncated.
imapUid	unsigned 32-bit integer	Specifies the IMAP uid option.
identifier	string	Specifies the identifier in the Set ACL command for setting rights to access mailboxes.
internaldate	64-bit integer	Specifies the date when a message arrives at the store. Note: The time is in milliseconds since the epoch. For example, midnight GMT, January 1, 1970.
mechanism	string	Specifies the authorization type or action performed depending on the event occurred that is Login or Logout.
modseq_sec	long integer	Specifies internal variables associated with the event.
modseq_usec	long unsigned integer	Specifies internal variables associated with the event.
msgflags	string	Specifies changed flags on messages.
msgquota	unsigned 32-bit integer	Specifies the message quota of a user.
newflags	string	Sets a new flag after the following operations: A: answered flag F: flagged flag D: deleted flag S: seen flag R: draft flag
NewName	string	Specifies the name of a mailbox after the rename event.
numDeleted	signed 32-bit integer	Specifies the number of messages in a mailbox with the /deleted flag set.
numDeletedn	signed 32-bit integer	Specifies the number of messages that are belonged to type n in a mailbox with the /deleted flag set.
numMsgs	unsigned 32-bit integer	Specifies the number of total messages in a mailbox.
numMsgsn	signed 32-bit integer	Specifies the number of messages that are belonged to type n in a mailbox presently.
numSeen	unsigned 32-bit integer	Specifies the number of messages in a mailbox which are marked as seen or read.
numSeenn	signed 32-bit integer	Specifies the total number of messages in a mailbox which are marked as seen or read for each message type.
numSeenDeleted	signed 32-bit integer	Specifies the number of message in a mailbox which are marked as seen or read and deleted.
numSeenDeletedn	signed 32-bit integer	Specifies the total number of message in a mailbox which are marked as seen (read) and deleted for each message type.
oldflags	string	Specifies flags are set for messages before an operation.
operation	integer	Specifies the following flag operations: add flags remove flags replace flags
owner	string	Sets the value to True if the userid associated with the flag change event is the owner of the mailbox.
peruser_flags	signed 32-bit integer	Specifies an internal representation of the peruser_flags attribute.
quotaRoot	string	Specifies a user name, folder name, or a type.
rights	string	Sets ACL rights to access mailboxes.
system_flags	signed 32-bit integer	Specifies internal representation of system flags.
toUidList	string	Specifies the list of UIDs as a comma separated list. The list displays UID messages which are provided in the destination mailbox.
uidList	string	Specifies the UID sequence in the IMAP format. It lists messages of interest.
unchangedsince	64-bit integer	Specifies internal variables associated with an event.
userid	string	Specifies the Userid associated with an event.
lastUid	unsigned 32-bit integer	Specifies the last IMAP uid value that was used.
size	unsigned 32-bit integer	Specifies the size of the message. Note that this may not be the size of payload, since the payload is typically a truncated version of the message.
uidValidity	unsigned 32-bit integer	Specifies the IMAP uid validity option.

Note:

Subscribers should allow for undocumented options when parsing the event reference. This allows for future compatibility when new options are added.

Available Options for Each Event Type

Table 13-4 shows the options that are available for each event type. For example, to see which options apply to a TrashMsg event, look in the column header for ReadMsg, TrashMsg and then note that these events can use numDel, numMsgs, numSeen, and userValidity.

Note:

Oracle reserves the right to change no to yes at any time needed.

Table 13-4 Available Options for Each Event Type

Option	NewMsg,UpdateMsg	ReadMsg, TrashMsg	DeleteMsg,PurgeMsg	MsgFlags	ChangeFlag	Login, Logout	OverQuota, UnderQuota	ExpungeMsg	SetAcl	Create	Delete	Rename	AnnotateMsg	Copy
attrn	No	No	No	No	No	No	No	No	No	No	No	No	Yes	No
authid	No	No	No	No	No	Yes	No	No	No	No	No	No	No	No
ctx	Yes	Yes	Yes	No	Yes	Yes	No	Yes	No	Yes	Yes	Yes	Yes	Yes
diskquota	Yes	No	Yes	No	No	No	Yes	No	No	No	Yes	No	No	No
diskquotaused	Yes	No	Yes	No	No	No	Yes	No	No	No	Yes	No	No	No
entryn	No	No	No	No	No	No	No	No	No	No	No	No	Yes	No
frommailboxName	No	No	No	No	No	No	No	No	No	No	No	No	No	Yes
fromUidList	No	No	No	No	No	No	No	No	No	No	No	No	No	Yes
fromuidValidity	No	No	No	No	No	No	No	No	No	No	No	No	No	Yes
fromuidValidity64	No	No	No	No	No	No	No	No	No	No	No	Yes	No	No
identifier	No	No	No	No	No	No	No	No	Yes	No	No	No	No	No
internaldate	Yes	No	No	No	No	No	No	No	No	No	No	No	No	Yes
mechanism	No	No	No	No	No	Yes	No	No	No	No	No	No	No	No
modseq_sec	Yes	No	No	No	No	No	No	Yes	No	No	No	No	Yes	Yes
modseq_usec	Yes	No	No	No	No	No	No	Yes	No	No	No	No	Yes	Yes
msgflags	Yes	No	No	No	Yes	No	No	No	No	No	No	No	No	No
msgquota	No	No	No	No	No	No	Yes	No	No	No	Yes	No	No	No
newflags	No	No	No	Yes	No	No	No	No	No	No	No	No	No	No
NewName	No	No	No	No	No	No	No	No	No	No	No	Yes	No	No
numDeleted	Yes	Yes	Yes	No	No	No	No	No	No	No	No	No	No	Yes
numDeletedn	Yes	Yes	Yes	No	No	No	No	No	No	No	No	No	No	Yes
numMsgs	Yes	Yes	Yes	No	No	No	Yes	Yes	No	No	No	No	No	Yes
numMsgsn	Yes	Yes	Yes	No	No	No	No	No	No	No	No	No	No	Yes
numSeen	Yes	Yes	Yes	No	No	No	No	No	No	No	No	No	No	Yes
numSeenn	Yes	Yes	Yes	No	No	No	No	No	No	No	No	No	No	Yes
numSeenDeleted	Yes	Yes	Yes	No	No	No	No	No	No	No	No	No	No	Yes
numSeenDeletedn	Yes	Yes	Yes	No	No	No	No	No	No	No	No	No	No	Yes
oldflags	No	No	No	Yes	No	No	No	No	No	No	No	No	No	No
operation	No	No	No	No	Yes	No	No	No	No	No	No	No	No	No
owner	No	Yes	No	No	No	No	No	No	No	No	No	No	No	No
peruser_flags	No	No	No	No	Yes	No	No	No	No	No	No	No	No	No
quotaRoot	No	No	No	No	No	No	Yes	No	No	No	No	No	No	No
rights	No	No	No	No	No	No	No	No	Yes	No	No	No	No	No
system_flags	No	No	No	No	Yes	No	No	No	No	No	No	No	No	No
toUidList	No	No	No	No	No	No	No	No	No	No	No	No	No	Yes
uidList	No	No	No	No	Yes	No	No	Yes	No	No	No	No	No	No
unchangedsince	No	No	No	No	Yes	No	No	No	No	No	No	No	No	No
userid	No	Yes	No	Yes	Yes	Yes	No	No	No	No	No	No	Yes	No
client	No	No	No	No	No	Yes	No	No	No	No	No	No	No	No
diskQuota	Yes	No	Yes	No	No	No	Yes	No	No	No	Yes	No	No	No
hdrLen	Yes	No	Yes	Yes	No	No	No	No	No	No	No	No	No	No
imapUid	Yes	No	Yes	Yes	No	No	No	No	No	No	No	No	Yes	No
lastUid	No	No	Yes	No	No	No	No	Yes	No	No	No	No	No	No
size	Yes	No	No	No	No	No	No	No	No	No	No	No	No	No
uidValidity	Yes	Yes	Yes	Yes	Yes	No	No	Yes	No	Yes	Yes	Yes	No	Yes
userid	No	Yes	No	Yes	Yes	Yes	No	No	No	No	No	No	Yes	No

Payload

ENS allows a payload for two event types: NewMsg, and UpdateMsg; the other event types do not carry a payload. The payload portion of these two notifications can contain any of the following data:

No header or body data (default setting)
Message header data only
Message body data only
Both message header and body data

The amount and type of data sent as the payload of the ENS event is determined by the configuration options found in "Payload Configuration Options".

Payload Configuration Options

Table 13-5 describes the payload configuration options.

Table 13-5 Payload Configuration Options

Configuration Options	Description
local.store.notifyplugin.*.maxbodysize	Specifies the maximum size (in bytes) of the body that will be transmitted with the notification. Syntax: uint32 Default: 0
local.store.notifyplugin.*.maxheadersize	Specifies the maximum size (in bytes) of the header that will be transmitted with the notification. Syntax: uint32 Default: 0

Configuration Options

Description

local.store.notifyplugin.*.maxbodysize

Specifies the maximum size (in bytes) of the body that will be transmitted with the notification.

Syntax: uint32

Default: 0

local.store.notifyplugin.*.maxheadersize

Specifies the maximum size (in bytes) of the header that will be transmitted with the notification.

Syntax: uint32

Default: 0

Note that both options are set to zero as the default so that no header or body data is sent with ENS notifications.

Examples

The following example shows a NewMsg event reference (it is actually a single line that is broken up to several lines for readability):

enp://127.0.0.1/store?evtType=NewMsg&timestamp=1047488403000&
hostname=eman&process=imta&pid=476&mailboxName=testuser&numMsgs=16
&uidValidity=1046993605&imapUid=62&size=877&hdrLen=814

In this example, for the DeleteMsg event. Messages marked as deleted by IMAP or HTTP were expunged. The user would not see the message in the folder any more.

enp://127.0.0.1/store?evtType=DeleteMsg&timestamp=1047488588000&
hostname=eman&process=imapd&pid=419&mailboxName=testuser&
numMsgs=6&uidValidity=1046993605&imapUid=61&lastUid=62

And a third example shows a ReadMsg event. Message was marked as Seen by IMAP or HTTP.

enp://127.0.0.1/store?evtType=ReadMsg&timestamp=1047488477000&
hostname=eman&process=imapd&pid=419&mailboxName=testuser&
uidValidity=1046993605&numSeen=11&numDel=9&numMsgs=16

Implementation Notes

The current implementation does not provide security on events that can be subscribed to. Thus, a user could register for all events, and portions of all other users' mail. Because of this it is strongly recommended that the ENS subscriber be on the "safe" side of the firewall at the very least.

The ENS server supports two options to control TCP access to the ENS server (service.ens.domainallowed and service.ens.domainnotallowed). These options work the same way as the equivalent options for POP, IMAP, and HTTP. See the discussion on configuring client access to POP, IMAP, and HTTP services in Messaging Server Security Guide. These options replace the functionality of the ENS_ACCESS environment variable that was included in the legacy ENS server.