[Contents] [Previous] [Next] [Index]
AddRecipient |
GetHeaderFile |
DupMessage |
GetNextRecipient |
FreeMessage |
GetRecipientAddress |
GetBodyFile |
pblock_findval |
GetFirstRecipient |
RemoveRecipient |
Message |
pblock |
Recipient |
This chapter is a reference to Messaging Server functions, structures, and result codes.
For Messaging Server program definitions, see the plugin.h header file. You can find this file at http://help/netscape.com/products/server/messaging/3x/info/apiheader.html.
[Top]
The Messaging Server API includes the following functions. This table lists the functions and the data structure on which it operates.
In general, all the Message structure functions that return pointers to structures return null on error. All functions that return an integer return 0 on success and a negative value on error. All input parameters are sanity checked for memory corruption, and return an appropriate error if necessary.
Adds the specified recipient to a message.
#include <plugin.h> int AddRecipient (Message *pMessage, Recipient *pRecipient);
The function has the following parameters:
pMessage |
Pointer to the name of the Message structure. |
pRecipient |
Pointer to the address of the Recipient structure. |
The function returns one of the following values:
This function adds recipients to the recipient list of the message structure. AddRecipient succeeds if both input parameters are valid and no memory errors occur.
To delete recipients from the recipient list, use RemoveRecipient.
This function operates on the Message structure.
GetFirstRecipient, GetNextRecipient, GetRecipientAddress, RemoveRecipient [Top] [Functions]
Duplicates the specified message.
#include <plugin.h> int DupMessage (Message *pMessage);
The function has the following parameter:
pMessage |
Pointer to the name of the Message structure. |
The function returns one of the following values:
This function duplicates an existing message structure. Upon return from this function, a separate instance of an identical message is created in the Mail Server. Mail Server automatically does the following:
If the pointer returned by DupMessage is returned in the OutMessage output parameter for the plug-in function, the Mail Server frees it. 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 "Plug-in Function Format and Result Codes."
If memory failures occur or if the input parameter does not point to a valid Message structure, the function returns null.
This function operates on the Message structure.
Frees the resources associated with a message.
#include <plugin.h> void FreeMessage (message *pMessage);
The function has the following parameter:
pMessage |
Pointer to the Message structure with which the resources are associated. |
This function frees the resources associated with the Message structure pointed to by the pMessage parameter.
If the pointer returned by DupMessage is returned in the OutMessage output parameter for the plug-in function, the Mail Server frees it. For more information about the plug-in function, see "Plug-in Function Format and Result Codes."
If the plug-in decides not to return the message it created after calling DupMessage, it should call FreeMessage for that pointer.
This function operates on the Message structure.
Gets the name of the body file associated with the specified message.
#include <plugin.h> char *GetBodyFile (Message *pMessage);
The function has the following parameter:
pMessage |
Pointer to the name of the Message structure. |
The function returns one of the following values:
This function returns the name of the body file associated with the Message structure represented by the pMessage parameter.
GetBodyFile returns a character string that contains the full path name to the file that contains the RFC-822 body portion of the message. The third-party API can use these names to open and rewrite or encode the content part of the message. This is always successful when the Message structure is valid.
This function operates on the Message structure.
Gets a pointer to the first recipient in the message structure.
#include <plugin.h> Recipient *GetFirstRecipient (Message *pMessage);
The function has the following parameter:
pMessage |
Pointer to the name of the Message structure. |
The function returns one of the following values:
This function returns a pointer to the first recipient in the message represented by the pMessage parameter. Any subsequent call to GetFirstRecipient resets the retrieval of recipients so that calls to GetNextRecipient return the second, third, and all subsequent recipients.
A GetFirstRecipient and GetNextRecipient pair is used to traverse the recipient list of the input message. The functions do not allocate any storage; both return null if the message is empty or malformed.
This function operates on the Message structure.
AddRecipient, GetNextRecipient, GetRecipientAddress, RemoveRecipient [Top] [Functions]
Gets the name of the header file associated with the specified message.
#include <plugin.h> char *GetHeaderFile (Message *pMessage);
The function has the following parameter:
pMessage |
Pointer to the name of the Message structure. |
The function returns one of the following values:
This function returns the name of the header file associated with the message structure pointed to by the pMessage parameter.
GetHeaderFile returns a character string that contains the full path name to the file that contains the RFC-822 header portion of the message. The third-party API can use these names to open and rewrite or encode the content part of the message. This is always successful when the Message structure is valid.
This function operates on the Message structure.
Gets the second, third, and all subsequent recipients in the message.
#include <plugin.h> Recipient *GetNextRecipient (RecipientList *pRecipientList);
The function has the following parameter:
pRecipientList |
Pointer to the list of recipients in the Message structure. |
The function returns one of the following values:
This function returns the second, third, and all subsequent recipients.
GetFirstRecipient and GetNextRecipient pair is used to traverse the recipient list of the input message. The functions do not allocate any storage; both return null if the message is empty or malformed.
This function operates on the Message structure.
AddRecipient, GetFirstRecipient, GetRecipientAddress, RemoveRecipient [Top] [Functions]
Gets the address of the specified recipient.
#include <plugin.h> char *GetRecipientAddress (Recipient *pRecipient);
The function has the following parameter:
pRecipient |
Pointer to the address of the Recipient structure. |
The function returns one of the following values:
This function returns the RFC-821 address string contained in the Recipient structure pointed to by pRecipient, for example, <foo@somewhere.org>.
This function operates on the Message structure.
AddRecipient, GetFirstRecipient, GetNextRecipient, RemoveRecipient [Top] [Functions]
Finds the name-value entry with the given name in the specified parameter block.
#include <plugin.h> char *pblock_findval(char *name, pblock *pb);
The function has the following parameters:
name |
Name of the entry to find. |
pb |
Hash table used to search for the specified entry. |
The function returns one of the following values:
This function finds the name-value entry with the given name in pblock pb, and returns the value portion. Otherwise, it returns null.
This function operates on the pblock, or parameter block, structure. pblock is a hash table keyed on the name string, which maps these name strings onto their value character strings.
Deletes recipients from the message.
#include <plugin.h> int RemoveRecipient (Message *pMessage, Recipient *pRecipient);
The function has the following parameters:
pMessage |
Pointer to the name of the Message structure. |
pRecipient |
Pointer to the address of the Recipient structure. |
The function returns one of the following values:
This function deletes recipients from the Z structure pointed to by pMessage.
The AddRecipient and RemoveRecipient pair is used to add and delete recipients in the recipient list. RemoveRecipient always succeeds.
This function operates on the Message structure.
AddRecipient, GetFirstRecipient, GetNextRecipient, GetRecipientAddress [Top] [Functions]
Structure |
Description |
Message |
Represents a message. |
pblock |
Represents a hash table. |
Recipient |
Represents the address of the recipient of a message. |
WARNING: The type definitions in this section are for informational purposes only. They do not reproduce the actual definitions of the structures. All types mentioned in this document are opaque, and members of the type defined structures are not exposed in the header files. The only access to the members is through the Messaging Server API. §
[Top]
#include <plugin.h> struct Message;
This structure stores all attributes that define a single message. This includes all envelope information, such as envelope sender, envelope recipients, sender and per-recipient extensions, and so on, as well as RFC-822 attributes such as pointers to the RFC-822 headers and RFC-822 body.
To set or access these attributes, use the functions associated with the Message type.
For more information, see "Data Structures" and "Message Structure."
AddRecipient, DupMessage, FreeMessage, GetBodyFile, GetFirstRecipient, GetHeaderFile, GetNextRecipient, RemoveRecipient
[Top] [Structures]
Represents the address of the recipient of a message.
#include <plugin.h> typedef struct Address; typedef Address Recipient;
The Recipient structure is a type of Address that represents the address of the recipient of a message. An address can be an RFC-821-compliant address or a newsgroup name string, for example: "devgroup@startup.com" or "alt.server.ideateam."
To set or access this structure, use the functions associated with the Message type.
For more information, see "Find a Messaging Server entry"
[Top] [Structures]
#include <plugin.h> struct pblock;
The parameter block represents a hash table that is keyed on the name string, which maps the name strings to their value character strings. The hash table contains hash table entry structures.
The hash function is subject to change and is therefore not made known to application functions.
To access this structure, use the pblock_findval function.
For more information, see "Parameter Block."
[Top] [Structures]
The plug-in should return one of these codes to the Messaging Server.
[Top]
Last Updated: 10/01/97 15:03:59
Copyright © 1997 Netscape Communications Corporation