/*
 * CONFIDENTIAL AND PROPRIETARY SOURCE CODE OF NETSCAPE
 * COMMUNICATIONS CORPORATION
 *
 * Copyright (c) 1998 Netscape Communications Corporation. All Rights
 * Reserved.
 *
 * Use of this Source Code is subject to the terms of the applicable license
 * agreement from Netscape Communications Corporation.
 *
 * The copyright notice(s) in this Source Code does not indicate actual or
 * intended publication of this Source Code.
 *
 *  Filename
 *  --------
 *  msg4plugins.h
 *
 *  Description
 *  -----------
 *  PostSMTPAccept/PreSMTPDeliver plugin definitions
 *  for Messaging Server Plug-in API 4.1.
 *
 *  Author(s)
 *  ---------
 *  Sam Robertson
 *
 *  History
 *  -------
 *  Wed Sep 16 10:09:00 1998 - Created
 *
 */

#ifndef MSG4PLUGINS_H
#define MSG4PLUGINS_H


#ifdef __cplusplus
extern "C" {
#endif

/* Return values expected from plugin's main function
 */
#ifndef MSG_NOACTION
#define MSG_NOACTION   0x02
#endif
#ifndef MSG_CONTINUE
#define MSG_CONTINUE   0x04
#endif

/* a pblock is used to store name value pairs in a linked list.
 * The plugin configuration is passed into both functions
 * exported by the plugin through this structure.
 */
typedef struct p_block {
    char   *name;
    char   *value;
    struct p_block *next;
} pblock;

/* The following structures define the recipient
 * list, which is included within the message structure
 * defined below.  The Recipient list should be
 * changed only through the API; however, the plugin
 * can read the recipient list through these
 * structures.
 */
typedef char *N821Address;
typedef char *SmtpExt;
typedef struct addresstag {
    long        magic;
    N821Address Addr821;
    SmtpExt     Ext;
    int         flags;
} Address;

typedef struct addr_list {
    long              magic;
    void             *context;
    Address           Addr;
    struct addr_list *pNext;
} AddressList;

typedef AddressList RecipientList;
typedef Address     Recipient;
typedef Address     Sender;

/* The message structure is defined here and is
 * passed into the plugin through the main
 * pFunc function.
 */
typedef struct message {
    long           magic;       /* magic cookie for the message */
    char          *BaseMsgName; /* Base message file name without path */
    char          *MsgFileName; /* The message file name including the path */
    RecipientList *recipList;   /* list of recipients */
    Sender        *sender;      /* envelope sender */
    const char    *stage;       /* stage in processing */
    int            flags;
    void          *context;     /* internal context for things
                                 * like getNext routines  */
    void          *control;     /* Pointer to ControlFile which
                                 * is accessible through plugin API */
    char          *PostOfficePath;  /* Path to postoffice */
} Message;

/* The following two prototypes are the functions that MUST be exported
 * by the plugin.
 *
 * The pInitFunc is called at MTA startup and the configuration that is
 * defined in plugins.cfg (the optional parameters) are passed in through
 * Config pblock. A return value of 1 is considered successful, while a
 * return value of 0 is considered failure.
 *
 * The pFunc is called for each message that is accepted.  The configuration
 * is passed once again, through the Config pblock.  The incoming message
 * details are stored within the InMessage message.  If the plugin should
 * create an outgoing message, it should be set in the OutMessage message.
 * A return value of MS
 */
typedef int (*pInitFunc)(pblock *Config);

typedef int (*pFunc) (pblock *Config,
                      struct message **InMessage,
                      struct message ***OutMessage);

/* The following functions are availble to the plugin
 */

/* DupMessage allows the plugin to duplicate the message
 * passed in.
 */
Message *DupMessage(Message *pMessage);

/* FreeMessage should be used to free all resources allocated
 * to a message.
 */
void FreeMessage(Message *pMessage);

/* The following functions allow access to the recipient
 * list encapsulated in the Message structure.
 */
Recipient *GetFirstRecipient(Message *pMessage);
Recipient *GetNextRecipient(Message *pMessage);
int AddRecipient(Message *pMessage,
                 Recipient *pRecipient);
int RemoveRecipient(Message *pMessage,
                    Recipient *pRecipient);
char *GetRecipientAddress(Recipient *pRecipient);

/* The control data functions allow the plugin to
 * view the SMTP envelope and connection information
 * gathered during message reception.  The string
 * returned contains a name: value representation with
 * each element delimited by LF's.
 *
 * The plugin should call 'FreeControlData' to free the
 * char * after it is done reviewing it.  Keep in mind
 * that changes to recipients using the functions above
 * will change the values of the information retrieved
 * here; therefore, the plugin should not rely on this
 * information to be up to date.
 */
char *GetControlData(Message *pMessage);  /* Return new control data */
void FreeControlData(char *controldata);  /* Let us free our own allocations */

/* AddControlInfo and RemoveControlInfo are methods used to
 * add and remove name: value pairs to the control data
 * respectively.  All changes will be reflected in any
 * future call to 'GetControlData'.
 */
int AddControlInfo(Message *pMessage, const char *key, const char *data,
                   int delete_original); /* Add control item */
int RemoveControlInfo(Message *pMessage, char *key);

/* Helper function to retrieve the MsgFileName for
 * the message passed in pMessage
 */
char *GetMessageFile(Message *pMessage);

/* pblock_findval will return the value for the
 * name passed in.  This helper function essentially
 * walks the pblock linked list searching for the
 * key specified in name and returns the value
 * associated with it, otherwise NULL.
 */
char *pblock_findval(char *name, pblock *pb);

/* PluginGetPostOffice returns the path to the postoffice directory.
 * This directory is where the physical message lives.
 */

char *GetPostOfficePath(Message *pMessage);

#ifdef __cplusplus
}
#endif

#endif