Chapter 5
iPlanet Messaging Server Specific Information
This chapter describes the iPlanet Messaging Server specific items you need to use the ENS APIs.
This chapter contains these sections:
iPlanet Messaging Server Events and Parameters
For iPlanet Messaging Server, there is only one event reference, which can be composed of several parameters. Each parameter has a value and a payload.
iPlanet Messaging Server supports the following types of events:
NewMsg - New message was received by the system into the user's mailbox.
DeleteMsg - User deleted a message (in the IMAP protocol, expunged) from the mailbox.
UpdateMsg - Message was appended to the mailbox (other than by NewMsg). for example, the user copied an email message to the mailbox.
ReadMsg - Message in the mailbox was read (in the IMAP protocol, the message was marked Seen).
PurgeMsg - Message was purged (in the IMAP protocol, expunged) from the mailbox by the system.
The following applies to the above supported events:
All events relate only to the INBOX.
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").
Both the DeleteMsg and the PurgeMsg events correspond to when a message is deleted from the user's mailbox (in the IMAP protocol, the message is expunged). It is not when a message is marked for deletion in the IMAP protocol. The only difference between the two events is who deleted the message. DeleteMsg indicates that the user deleted the message, while PurgeMsg indicates that iPlanet Messaging Server deleted the message (for example, if the message has expired).
The notification will carry several pieces of information depending on the event type, for example, NewMsg indicates the IMAP uid of the new message.
Events are not generated for POP3 client access.
Parameters
iBiff will use the following format for the ENS event reference:
enp://127.0.0.1/store?param=value¶m1=value1¶m2=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 configuration parameters is listed in a separate section below.
The second part of the event reference consists of parameter/value pairs. This part of the event reference is separated from the event key by a question mark (?). The parameter and value are separated by an equals sign (=). The parameter/value pairs are separated by an ampersand (&). Note that there can be empty values, for which the value simply does not exist.
Table 5-1 describes the mandatory configuration parameters that need to be included in every notification.
Table 5-1 Mandatory Configuration Parameters
|
Parameter
|
Data Type
|
Description
|
|
evtType
|
string
|
Specifies the event type. One of NewMsg, UpdateMsg, ReadMsg, DeleteMsg, or PurgeMsg.
|
|
mailboxName
|
string
|
Specifies the mailbox name in the message store. The mailboxName has the format uid@domain, where uid is the userid, 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).
|
|
timestamp
|
64-bit integer
|
Specifies the number of milliseconds since the epoch (midnight GMT, January 1, 1970).
|
|
process
|
string
|
Specifies the name of the process that generated the event. If the process name is unknown, the process id will be used (an integer).
|
|
hostname
|
string
|
The hostname of the machine that generated the event.
|
Table 5-2 describes the optional configuration parameters, depending on the event type.
Table 5-2 Optional Configuration Parameters
|
Parameter
|
Data Type
|
Description
|
|
numMsgs
|
unsigned 32-bit integer
|
Specifies the number of existing messages.
|
|
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 parameter.
|
|
imapUid
|
unsigned 32-bit integer
|
Specifies the IMAP uid parameter.
|
|
uidSeqSeen
|
string
|
Specifies the list of uids that are marked seen in IMAP syntax, such as "1:6."
|
|
lastUid
|
unsigned 32-bit integer
|
Specifies the last IMAP uid value that was used.
|
|
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.
|
|
qUsed
|
signed 32-bit integer
|
Specifies the disk space used in quota in kilobytes.
|
|
qMax
|
signed 32-bit integer
|
Specifies the disk space quota in kilobytes. The value is set to -1 to indicate no quotas.
|
|
qMsgUsed
|
signed 32-bit integer
|
Specifies the number of messages used in quota. Should be the same value as numMsgs.
|
|
qMsgMax
|
signed 32-bit integer
|
Specifies the quota for max number of messages. The value is set to -1 to indicate no quotas.
|
|
Note
|
Subscribers should allow for undocumented parameters when parsing the event reference. This allows for future compatibility when new parameters are added.
|
Payload
Depending on the event, there may be the following data in the payload portion of the ENS notification:
The headers of the message - (string) - The length will be limited to a certain (configurable) size. See configuration parameters in a separate section below.
The first few bytes of the body of the message - (string). The actual number of bytes will be configurable. See configuration parameters in a separate section below.
Table 5-3 shows the parameters that are available for each event type.
Table 5-3 Available Parameters for Each Event Type
|
Field Name
|
NewMsg, UpdateMsg
|
ReadMsg
|
DeleteMsg, PurgeMsg
|
|
numMsgs
|
Yes
|
No
|
Yes
|
|
size
|
Yes
|
No
|
No
|
|
uidValidity
|
Yes
|
Yes
|
Yes
|
|
imapUid
|
Yes
|
No
|
Yes
|
|
uidSeqSeen
|
No
|
Yes
|
No
|
|
uidSeqDel
|
No
|
Yes
|
No
|
|
lastUid
|
No
|
No
|
Yes
|
|
hdrLen
|
Yes
|
No
|
No
|
|
qUsed
|
Yes
|
No
|
Yes
|
|
qMax
|
Yes
|
No
|
Yes
|
|
qMsgUsed
|
Yes
|
No
|
Yes
|
|
qMsgMax
|
Yes
|
No
|
Yes
|
|
payload (headers/body)
|
Yes
|
No
|
No
|
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&mailboxName=ketu310×tamp=972423964000
&process=16233&hostname=ketu&numMsgs=1&size=3339&uidValidity=972423964&
imapUid=1&hdrLen=810
|
|
This is the associated payload, note that the body portion has been truncated:
|
Return-path: <>
Received: from process-daemon.ketu.siroe.com by ketu.siroe.com
(iPlanet Messaging Server 5.0 (built Oct 17 2000))
id <0G2Y00C01F4SIY@ketu.siroe.com> for ketu310@ims-ms-daemon
(ORCPT ketu310@siroe.com); Tue, 24 Oct 2000 14:46:04 -0700 (PDT)
Received: from ketu.siroe.com
(iPlanet Messaging Server 5.0 (built Oct 17 2000))
id <0G2Y00C01F4RIX@ketu.siroe.com>; Tue, 24 Oct 2000 14:46:04 -0700 (PDT)
Date: Tue, 24 Oct 2000 14:46:04 -0700 (PDT)
From: Internet Mail Delivery
Subject: Delivery Notification: Delivery has failed
To: ketu310@siroe.com
Message-id: <0G2Y00C05F4SIX@ketu.siroe.com>
MIME-version: 1.0
Content-type: multipart/report; report-type=delivery-status;
boundary="Boundary_(ID_VlTrnuIgC5ferJnL2SCzhQ)"
--Boundary_(ID_VlTrnuIgC5ferJnL2SCzhQ)
ontent-type: text/plain; charset=us-ascii
Content-langua
|
|
This is another example, this time for the DeleteMsg event (again it is a single line that is broken up for readability). Note that this example shows a mailboxName for the userid blim in the hosted domain symult.com.
|
enp://127.0.0.1/store?evtType=DeleteMsg&mailboxName=blim@symult.com&
timestamp=972423953000&process=15354&hostname=ketu&numMsgs=0&
uidValidity=972423928&imapUid=2&lastUid=2
|
|
And a third example showing a ReadMsg event (again the line is broken up for readability). Note that this example shows an empty value for the uidSeqSeen parameter. It also shares the same userid as the previous example, however this corresponds to a different user, a user in the default domain.
|
enp://127.0.0.1/store?evtType=ReadMsg&mailboxName=blim×tamp=972423952000&
process=15354&hostname=ketu&uidValidity=972423928&uidSeqSeen=&uidSeqDel=1
|
|
iPlanet Messaging Server Sample Code
iPlanet Messaging Server ships with a complete ENS implementation but by default it is not enabled. To enable ENS in iPlanet Messaging Server, see Appendix C in the iPlanet Messaging Server 5.2 Administrator's Guide.
The following two code samples illustrate how to use the ENS API. The sample code is provided with the product in the following directory:
server-root/bin/msg/enssdk/examples
Sample Publisher
This sample code provides a simple interactive asynchronous publisher.
/*
* Copyright 2000 by Sun Microsystems, Inc.
* All rights reserved
*/
/*
*
* apub
* --
* a simple interactive asynchronous publisher
* --
*
* This simplistic program publishes events using the hard-coded
* event reference
* enp://127.0.0.1/store
* and the data entered at the prompt as notification payload.
* Enter "." to end the program.
*
* If you happen to run the corresponding subscriber, asub, on the
* same notification server, you will notice the sent data printed
* out in the asub window.
*
* Syntax:
* $ apub <host> <port>
* where
* <host> is the notification server hostname
* <port> is the notification server IP port number
*/
#include <stdlib.h>
#include <stdio.h>
#include "pasdisp.h"
#include "publisher.h"
static pas_dispatcher_t *disp = NULL;
static publisher_t *_publisher = NULL;
static int _shutdown = 0;
static void _read_stdin();
static void _exit_usage()
{
printf("\nUsage:\n apub host port\n");
exit(5);
}
static void _exit_error(const char *msg)
{
printf("%s\n", msg);
exit(1);
}
static void _call_shutdown()
{
_shutdown = 1;
pas_shutdown(disp);
}
static void _open_ack(void *arg, int rc, void *enc)
{
_publisher = (publisher_t *)enc;
(void *)arg;
if (!_publisher) {
printf("Failed to create publisher with status %d\n", rc);
_call_shutdown();
return;
}
_read_stdin();
return;
}
static void _publish_ack(void *arg, int rc, void *ignored)
{
(void *)ignored;
free(arg);
if (rc != 0) {
printf("Publish failed with status %d\n", rc);
_call_shutdown();
return;
}
_read_stdin();
return;
}
static void _read_stdin()
{
static char input[1024];
printf("apub> ");
fflush(stdout);
while (!_shutdown) {
if ( !fgets(input, sizeof(input), stdin) ) {
continue;
} else {
char *message;
unsigned int message_len;
input[strlen(input) - 1] = 0; /* Strip off the \n */
if (*input == '.' && input[1] == 0) {
publisher_delete(_publisher);
_call_shutdown();
break;
}
message = strdup(input);
message_len = strlen(message);
publish(_publisher, "enp://127.0.0.1/store",
message, message_len,
_publish_ack, NULL, (void *)message, 0);
return;
}
}
return;
}
main(int argc, char **argv)
{
unsigned short port = 7997;
char host[256];
if (argc < 2) _exit_usage();
if (*(argv[1]) == '0') {
strcpy(host, "127.0.0.1");
} else {
strcpy(host, argv[1]);
}
if (argc > 2) {
port = (unsigned short)atoi(argv[2]);
}
disp = pas_dispatcher_new(NULL);
if (disp == NULL) _exit_error("Can't create publisher");
publisher_new_a(disp, NULL, host, port, _open_ack, disp);
pas_dispatch(disp);
_shutdown = 1;
pas_dispatcher_delete(disp);
exit(0);
}
Sample Subscriber
This sample code provides a simple subscriber.
/*
* Copyright 1997 by Sun Microsystems, Inc.
* All rights reserved
*
*/
/*
*
* asub
* --
* a simple subscriber
* --
*
* This simplistic program subscribes to events matching the
* hard-coded event reference:
* enp://127.0.0.1/store
* It subsequently received messages emitted by the apub processes
* if any are being used, and prints the payload of each received
* notification to stdout.
*
* Syntax:
* $ asub <host> <port>
* where
* <host> is the notification server hostname
* <port> is the notification server IP port number
*/
#include <stdlib.h>
#include <stdio.h>
#include "pasdisp.h"
#include "subscriber.h"
static pas_dispatcher_t *disp = NULL;
static subscriber_t *_subscriber = NULL;
static subscription_t *_subscription = NULL;
static renl_t *_renl = NULL;
static void _exit_usage()
{
printf("\nUsage:\n asub host port\n");
exit(5);
}
static void _exit_error(const char *msg)
{
printf("%s\n", msg);
exit(1);
}
static void _subscribe_ack(void *arg, int rc, void *subscription)
{
(void)arg;
if (!rc) {
_subscription = subscription;
printf("Subscription successful\n");
subscriber_keepalive(_subscriber, 30000);
} else {
printf("Subscription failed - status %d\n", rc);
pas_shutdown(disp);
}
}
static void _unsubscribe_ack(void *arg, int rc, void *ignored)
{
(void *)ignored;
(void *)arg;
if (rc != 0) {
printf("Unsubscribe failed - status %d\n", rc);
}
subscriber_delete(_subscriber);
pas_shutdown(disp);
}
static int _handle_notify(void *arg, char *url, char *str, int len)
{
(void *)arg;
printf("[%s] %.*s\n", url, len, (str) ? str : "(null)");
return 0;
}
static void _open_ack(void *arg, int rc, void *enc)
{
_subscriber = (subscriber_t *)enc;
(void *)arg;
if (rc) {
printf("Failed to create subscriber with status %d\n", rc);
pas_shutdown(disp);
return;
}
subscribe(_subscriber, "enp://127.0.0.1/store",
_handle_notify, NULL,
_subscribe_ack, NULL);
return;
}
static void _unsubscribe(int sig)
{
(int)sig;
unsubscribe(_subscriber, _subscription, _unsubscribe_ack, NULL);
}
main(int argc, char **argv)
{
unsigned short port = 7997;
char host[256];
if (argc < 2) _exit_usage();
if (*(argv[1]) == '0') {
strcpy(host, "127.0.0.1");
} else {
strcpy(host, argv[1]);
}
if (argc > 2) {
port = (unsigned short)atoi(argv[2]);
}
disp = pas_dispatcher_new(NULL);
if (disp == NULL) _exit_error("Can't create publisher");
subscriber_new_a(disp, NULL, host, port, _open_ack, NULL);
pas_dispatch(disp);
pas_dispatcher_delete(disp);
exit(0);
}
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.