msg4plugins.h header file. You can see this file in Table 3.1 Messaging Server SMTP plug-in API functions
| Function | Description |
Structure
|
|
|
|
|
|
|
|
|
| Gets the path to the post office directory where the message resides.
|
|
| Passes the configuration when the plug-in function is called at MTA start-up.
|
|
|
| |
|---|
#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: |
name:value pairs to the control data for a message. This change is reflected in any future call to 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);
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 SMTP plug-in DLL, see Chapter 4, "Sample SMTP 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);
null.
pMessage parameter.
DupMessage in the OutMessage output parameter of the plug-in function (the function based on the function prototype, pFunc). If the SMTP 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 SMTP Plug-ins Work."
For more information, see "Duplicate the message."
FreeMessage, Message, pFunc
[Top] [Functions]
#include <msg4plugins.h>
void FreeControlData(char *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);
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 SMTP 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);
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);
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 SMTP plug-in DLL, see Chapter 4, "Sample SMTP Plug-in."
AddRecipient, GetNextRecipient, GetRecipientAddress, RemoveRecipient, Message
[Top] [Functions]
#include <msg4plugins.h>
char *GetMessageFile(Message *pMessage);
Message parameter. In the 4.0 API, the message, including the header and
body files, are maintained in the same file.
The GetMessageFile 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 SMTP plug-in DLL, see Chapter 4, "Sample SMTP Plug-in."
Message
[Top] [Functions]
#include <msg4plugins.h>
Recipient *GetNextRecipient (Message *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 *GetPostOfficePath(Message *pMessage);
null.
Message
[Top] [Functions]
#include <msg4plugins.h>
char *GetRecipientAddress (Recipient *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 SMTP plug-in DLL, see Chapter 4, "Sample SMTP Plug-in." For the address definition, see RFC 821: "Simple Mail Transfer Protocol."
AddRecipient, GetFirstRecipient, GetNextRecipient, RemoveRecipient, Recipient
[Top] [Functions]
name:value pair with the given name.
#include <msg4plugins.h>
char *pblock_findval(char *name, pblock *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 SMTP plug-in.
You can use this function to find the value of the name=value parameter in the SMTP plug-in entry point code described in "How SMTP 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 SMTP 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 SMTP plug-in DLL, see Chapter 4, "Sample SMTP 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 SMTP plug-in control information.
For more information, see "Writing the Initialization Function." To see how this function is used in a sample SMTP plug-in DLL, see Chapter 4, "Sample SMTP Plug-in."
pFunc, pblock, pblock_findval
[Top] [Functions]
#include <msg4plugins.h>
int RemoveControlInfo (Message*pMessage, char *key;
name:value pairs from the control data. This change is reflected in any future call to 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 SMTP plug-in data structures
| Structure |
Description
|
|
|
|
| |
|---|
WARNING: The type definitions are described in this section for informational purposes only. Although your SMTP 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 addresstag
long magic;
N821Address Addr821;
SMTPExt Ext;
int flags;
) Address;
Magic value required by AddRecipient. Value: | |
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 SMTP plug-in can read the recipient list through plug-in API structures. For more information, see "The Message Recipient and the Address Structure."
WARNING: This type definition is 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. §
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 value required by AddRecipient. Value: | |
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 SMTP plug-in can read the recipient list through plug-in API structures. For more information, see "The Message RecipientList and the AddressList Structure."
WARNING: This type definition is 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. §
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;
char *PostOfficePath;
} 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. For more information, see "Accessing Control Data."
The Message structure is passed into the SMTP 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."
WARNING: This type definition is 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. §
AddRecipient, DupMessage, FreeMessage, GetFirstRecipient, GetMessageFile, GetNextRecipient, RemoveRecipient, pFunc, AddControlInfo, GetControlData, FreeControlData, RemoveControlInfo, GetPostOfficePath, Sender, Recipient, RecipientList, AddressList, Address
[Top] [Data Structures]
#include <msg4plugins.h>
typedef struct p_block
char *name;
char *value;
struct p_block *next;
) pblock;
Pointer to the next entry in the linked list of |
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 SMTP plug-in, pInitFunc and pFunc, use this structure to pass the plug-in configuration data in the plugins.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 SMTP plug-in definitions
Table 3.4 SMTP plug-in result codes
| Code |
Description
|
| The SMTP plug-in did not do anything. Continue to process the message. |
|---|
Last Updated: 05/13/99 11:41:54