This information describes the Oracle Communications Messaging Server specific items you need to use the ENS APIs.
Topics:
For Messaging Server, there is only one event reference, which can be composed of several options. There are various types of event notifications. Table 19-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 | Description |
---|---|
ChangeFlag |
Shows change status as "1" add, "2" remove, or "3" replace. |
DeleteMsg |
Messages marked as "Deleted" are removed from the mailbox. This is the equivalent to IMAP expunge. |
Login |
User logged in from IMAP, HTTP, or POP. |
Logout |
User logged out from IMAP, HTTP, or POP. |
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. For information on how to enable the payload, see "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. For details on the options each event type takes, see "Available Options for Each Event Type."
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.
iBiff uses the following format for the ENS event reference:
enp://127.0.0.1/store_?param_=_value&param1_=_value1&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.
Table 19-2 describes the mandatory event reference options that need to be included in every notification.
Table 19-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). |
Table 19-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.")
Table 19-3 Optional Event Reference Options
Option | Data Type | Description |
---|---|---|
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. |
diskUsed |
signed 32-bit integer |
Specifies the amount of disk space used in kilobytes. |
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. |
lastUid |
unsigned 32-bit integer |
Specifies the last IMAP uid value that was used. |
numDel |
unsigned 32-bit integer |
Specifies the number of messages marked as deleted in the mailbox. |
numMsgs |
unsigned 32-bit integer |
Specifies the number of total messages in the mailbox. |
numMsgsMax |
signed 32-bit integer |
Specifies the quota for the maximum number of messages. The value is set to -1 to indicate no quotas. |
numSeen |
unsigned 32-bit integer |
Specifies the number of messages in the mailbox marked as seen (read). |
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.Table 19-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 19-4 Available Options for Each Event Type
Option | NewMsg, UpdateMsg | ReadMsg, TrashMsg | DeleteMsg,PurgeMsg | Login, Logout | OverQuota, UnderQuota |
---|---|---|---|---|---|
client |
No |
No |
No |
Yes |
No |
diskQuota |
No |
No |
No |
No |
Yes |
diskUsed |
No |
No |
No |
No |
Yes |
hdrLen |
Yes |
No |
No |
No |
No |
imapUid |
Yes |
No |
Yes |
No |
No |
lastUid |
No |
No |
Yes |
No |
No |
numDel |
No |
Yes |
No |
No |
No |
numMsgs |
Yes |
Yes |
Yes |
No |
Yes |
numMsgsMax |
No |
No |
No |
No |
Yes |
numSeen |
No |
Yes |
No |
No |
No |
size |
Yes |
No |
No |
No |
No |
uidValidity |
Yes |
Yes |
Yes |
No |
No |
userid |
No |
No |
No |
Yes |
No |
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."
Table 19-5 describes the payload configuration options.
Table 19-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 |
Note that both options are set to zero as the default so that no header or body data is sent with ENS notifications.
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×tamp=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×tamp=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×tamp=1047488477000& hostname=eman&process=imapd&pid=419&mailboxName=testuser& uidValidity=1046993605&numSeen=11&numDel=9&numMsgs=16
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 the Messaging Server Security Guide. These options replace the functionality of the ENS_ACCESS environment variable that was included in the legacy ENS server.