msg4plugins.h header file. You can see this file in Table 3.1 Messaging Server Plug-in API Functions
| Function | Description |
Structure
|
|
|
|
|
|
|
|
|
|
|
| Passes the configuration when the plug-in function is called at MTA startup.
|
|
|
| |
#include <msg4plugins.h>
int AddControlInfo(Message*pMessage,
const char *key,
const char *data,
int delete_original);
Flag indicating whether to delete the original message when adding control data. Values: |
GetControlData.
The control data accessed by the Messaging Server Plug-in API is specific to Netscape Messaging Server. Some of the data in the control data is gathered during the accept sequence of Messaging Server; some is gathered from the SMTP protocol. Control data includes the SMTP envelope.
For information about using this function, see "Add the control data."
GetControlData, FreeControlData, RemoveControlInfo, Message
[Top] [Functions]
#include <msg4plugins.h>
int AddRecipient (Message *pMessage, Recipient *pRecipient);
pMessage | |
pRecipient |
Message structure. You also use this function to create a new recipient. AddRecipient succeeds if both input parameters are valid and no memory errors occur.
To add a recipient, you must define the magic value 0xdeadbeef. For an example that shows how to define this value, see "Add and remove recipients." To see how AddRecipient is used in a sample plug-in DLL, see Chapter 4, "Messaging Server Sample Plug-in."
To delete recipients from the recipient list, use RemoveRecipient.
GetFirstRecipient, GetNextRecipient, GetRecipientAddress, RemoveRecipient, Recipient, Message
[Top] [Functions]
#include <msg4plugins.h>Message*DupMessage (Message *pMessage);
pMessage |
null.
pMessage parameter.
DupMessage in the OutMessage output parameter of the plug-in function (the function based on the function prototype, pFunc). If the plug-in decides not to return the message it created after calling DupMessage, it should call FreeMessage for that pointer. For information about the plug-in function, see "How Messaging Server Plug-ins Work."
For more information, see "Duplicate the message."
FreeMessage, Message, pFunc
[Top] [Functions]
#include <msg4plugins.h>
void FreeControlData(char *controldata);
controldata |
GetControlData. Any call to GetControlData should be followed by a call to FreeControlData.
The control data accessed by the Messaging Server Plug-in API is specific to Netscape Messaging Server. Some of the data in the control data is gathered during the accept sequence of Messaging Server; some is gathered from the SMTP protocol. Control data includes the SMTP envelope.
For information about using this function, see "Free the control data."
GetControlData, AddControlInfo, RemoveControlInfo, Message
[Top] [Functions]
#include <msg4plugins.h>
void FreeMessage (Message *pMessage);
pMessage |
Message structure indicated in the pMessage parameter. It operates only on the in-memory copy of a message, and does not touch anything on the disk.
If a plug-in decides not to return a message it created after calling DupMessage, it should call FreeMessage for that message. For more information, see "Free the message."
DupMessage, Message
[Top] [Functions]
#include <msg4plugins.h>
char *GetControlData(Message*pMessage);
pMessage |
FreeControlData.
The control data is returned in the form of a character string that contains the full path name to the control data for the message. The character string contains name:value pairs with the elements separated by LFs.
The control data accessed by the Messaging Server Plug-in API is specific to Netscape Messaging Server. Some of the data in the control data is gathered during the accept sequence of Messaging Server; some is gathered from the SMTP protocol. Control data includes the SMTP envelope.
For information about using this function, see "Get the control data."
FreeControlData, AddControlInfo, RemoveControlInfo, Message
[Top] [Functions]
#include <msg4plugins.h>
Recipient *GetFirstRecipient (Message *pMessage);
pMessage |
null.
Message structure. Any subsequent call to GetFirstRecipient resets the retrieval of recipients so that calls to GetNextRecipient return the second, third, and all subsequent recipients.
To traverse the recipient list of the input message, use the GetFirstRecipient and GetNextRecipient pair. The functions do not allocate any storage; both return null if the message is empty or malformed.
For more information, see "Get message recipients." To see how this function is used in a sample plug-in DLL, see Chapter 4, "Messaging Server Sample Plug-in."
AddRecipient, GetNextRecipient, GetRecipientAddress, RemoveRecipient, Message
[Top] [Functions]
#include <msg4plugins.h>
char *GetMsgFile (Message *pMessage);
pMessage |
Message parameter. In the 4.0 API, the message, including the header and
body files, are maintained in the same file.
The GetMsgFile function, new in Messaging Server 4.0, combines the two 3.0
functions, GetHeaderFile and GetBodyFile. These two functions are
retained in the API to provide backward compatibility.
For more information, see "Get the message file." To see how this function is used in a sample plug-in DLL, see Chapter 4, "Messaging Server Sample Plug-in."
Message
[Top] [Functions]
#include <msg4plugins.h>
Recipient *GetNextRecipient (Message *pMessage);
pMessage |
null.
GetFirstRecipient to return the second, third, and all subsequent recipients in the recipient list encapsulated in the Message structure.
To traverse the recipient list of the input message, use the GetFirstRecipient and GetNextRecipient pair. These functions do not allocate any storage; both return null if the message is empty or malformed.
For more information, see "Get message recipients."
AddRecipient, GetFirstRecipient, GetRecipientAddress, RemoveRecipient, Message
[Top] [Functions]
#include <msg4plugins.h>
char *GetRecipientAddress (Recipient *pRecipient);
pRecipient |
null.
Message structure.
This function returns the RFC 821 address string contained in the Recipient structure pointed to by pRecipient, for example, <foo@somewhere.org>.
For more information, see "Get the recipient's address." To see how this function is used in a sample plug-in DLL, see Chapter 4, "Messaging Server Sample Plug-in." For the address definition, see RFC 821: "Simple Mail Transfer Protocol."
AddRecipient, GetFirstRecipient, GetNextRecipient, RemoveRecipient, Recipient
[Top] [Functions]
#include <msg4plugins.h>
char *pblock_findval(char *name, pblock *pb);
name | |
pb |
Pointer to the |
value portion of the entry with the given name.
null.
pb parameter, searching for the key specified in the name parameter, and returns the value associated with it. The parameter block, or pblock structure, is a linked list of name:value pairs that contains the configuration information for the plug-in.
You can use this function to find the value of the name=value parameter in the plug-in entry point code described in "How Messaging Server Plug-ins Work." This parameter represents name:value pairs that are passed to the function.
For more information, see "Find a Messaging Server entry" and "The Parameter Block Structure."
pblock
[Top] [Functions]
#include <msg4plugins.h>
typedef int (*pFunc) (pblock *Config,
struct Message **InMessage,
struct Message ***OutMessage);
Config parameter block. The details of the incoming message are stored in the InMessage message. If the plug-in creates an outgoing message, it should be set in the OutMessage message.
For more information, see "Writing the Plug-in Function." To see how this function is used in a sample plug-in DLL, see Chapter 4, "Messaging Server Sample Plug-in."
pInitFunc, pblock, Message, pblock_findval
[Top] [Functions]
#include <msg4plugins.h>
typedef int (*pInitFunc)(pblock *Config);
Pointer to the |
plugins.cfg (the optional parameters) is passed in through the Config parameter block, a pblock structure that contains plug-in control information.
For more information, see "Writing an Initialization Function." To see how this function is used in a sample plug-in DLL, see Chapter 4, "Messaging Server Sample Plug-in."
pFunc, pblock, pblock_findval
[Top] [Functions]
#include <msg4plugins.h>
int RemoveControlInfo (Message*pMessage, char *key;
GetControlData.
The control data accessed by the Messaging Server Plug-in API is specific to Netscape Messaging Server. Some of the data in the control data is gathered during the accept sequence of Messaging Server; some is gathered from the SMTP protocol. Control data includes the SMTP envelope.
For information about using this function, see "Remove the control data."
GetControlData, FreeControlData, AddControlInfo, Message
[Top] [Functions]
#include <msg4plugins.h>
int RemoveRecipient (Message *pMessage,
Recipient *pRecipient);
| |
|
Message structure.
The AddRecipient and RemoveRecipient functions are used to add and delete recipients in the recipient list. RemoveRecipient always succeeds. For more information, see "Add and remove recipients."
AddRecipient, GetFirstRecipient, GetNextRecipient, GetRecipientAddress, Recipient, Message
[Top] [Functions]
null on error. Functions that return an integer return 0 on success and a negative value on error.
All input parameters are validity checked for memory corruption and return an appropriate error if necessary.
[Top] [Functions]
Table 3.2 Messaging Server Plug-in Data Structures
| Structure |
Description
Address
| AddressList
| Message
| pblock
| |
WARNING: The type definitions are described in this section for informational purposes only. Although your plug-in should be able to reference the members of these structures, it should make all changes through the API, to accommodate future API changes. §[Top]
#include <msg4plugins.h>
typedef struct address
long magic;
N821Address Addr821;
SMTPExt Ext;
int flags;
) Address;
magic |
Magic value required by AddRecipient. Value: |
Addr821 | |
Ext | |
flags |
Address structure provides the type definition of the Recipient and Sender parameters that are part of the Message structure.
To access this structure, you use the functions that manipulate the Message structure. You should make changes to the Recipient list only through the API. The plug-in can read the recipient list through plug-in API structures. For more information, see "The Message Recipient and the Address Structure."
Message, AddressList, N821Address, SMTPExt, Sender, Recipient
[Top] [Data Structures]
#include <msg4plugins.h>
typedef struct addr_list
long magic;
void *context;
Address Addr;
struct addr_list *pNext;
) AddressList;
magic |
Magic value required by AddRecipient. Value: |
context | |
Addr | |
pNext |
AddressList structure is a linked list of addresses. This structure provides the type definition of the RecipientList parameter that is part of the Message structure.
To access this structure, you use the functions that manipulate the Message structure. You should only make changes to the recipient list through the API. The plug-in can read the recipient list through plug-in API structures. For more information, see "The Message RecipientList and the AddressList Structure."
Message, Address, RecipientList
[Top] [Data Structures]
#include <msg4plugins.h>
typedef struct message {
long magic;
char *BaseMsgName;
char *MsgFileName;
RecipientList *recipList;
Sender *sender;
const char *stage;
int flags;
void *context;
void *control;
} Message;
Message structure stores all attributes that define a single message. This includes both header and body information. Most of the other structures and type definitions of the API provide the parameters that make up the Message structure.
The header of the message is made up of fields in name:value pair format that include all header or envelope information, such as sender, recipients, sender and per-recipient extensions, and so on. The body of the message refers to the lines of text that make up the content of the message.
Control information is made up of the SMTP envelope, combined with data gathered during the accept sequence of Messaging Server.
The Message structure is passed into the plug-in through the main pFunc function.
To set or access message attributes, use the functions that operate on the Message structure, which are listed in "See Also."
For more information, see "Using Messaging Server Plug-in Data Structures" and "The Message Structure." For details about message definition, see RFC 822: "Standard for the Format of ARPA Internet Text Messages."
AddRecipient, DupMessage, FreeMessage, GetFirstRecipient, GetMessageFile, GetNextRecipient, RemoveRecipient, pFunc, AddControlInfo, GetControlData, FreeControlData, RemoveControlInfo, Sender, Recipient, RecipientList, AddressList, Address
[Top] [Data Structures]
#include <msg4plugins.h>
typedef struct p_block
char *name;
char *value;
struct p_block *next;
) pblock;
name | |
value | |
next | Pointer to the next entry in the linked list of name:value pairs. |
pblock structure is an array of name:value pairs in a linked list that you can use to set and retrieve control information for a message.
Both of the functions exported by the plug-in, pInitFunc and pFunc, use this structure to pass the plug-in configuration data in the plug-in.cfg file to the plug-in.
To access the fields in the pblock structure, use the pblock_findval function.
For more information, see "The Parameter Block Structure."
pblock_findval, pInitFunc, pFunc
[Top] [Data Structures]
Table 3.3 Messaging Server Plug-in Definitions
Table 3.4 Plug-in Result Codes
| Code |
Description
MSG_CONTINUE
| MSG_NOACTION The plug-in did not do anything. Continue to process the message. |
Last Updated: 11/19/98 10:23:59
[an error occurred while processing this directive]