Sun Java System Messaging Server 6 2005Q4 MTA Developer's Reference

mtaEnqueueWrite()

Write message data to the message being submitted.

Syntax


int mtaEnqueueWrite(mta_nq_t    *nq_ctx,
                    const char  *str1,
                    size_t       len1,
                    const char  *str2, ...);

Zero or more string pointer-length pairs can be supplied to this routine. The list of pairs must be terminated by a NULL call argument.

Arguments

Arguments  

Description  

nq_ctx

Pointer to an enqueue context created with mtaEnqueueStart().

str1

Pointer to a string of text to write to the message. The string must be NULL terminated if a value of zero is passed for len1.

len1

The length in bytes, not including any NULL terminator, of the string str1. If a value of zero is passed for this argument, then the string str1 must be NULL terminated.

str2

Pointer to a second string of text to write to the message. The string must be NULL terminated if a value of zero is passed for len2. If only supplying a single string, then pass a NULL value for this argument.

Description

After a message’s list of envelope recipient addresses has been supplied with mtaEnqueueTo(), the message itself must be supplied. This is done by repeatedly calling mtaEnqueueWrite(). First the message’s header should be supplied, followed by a blank line, followed by any message content. Each line of message data must be terminated by a US-ASCII line-feed character (0x0A). Each call to mtaEnqueueWrite() can supply one or more bytes of the message’s data. Unlike mtaEnqueueWriteLine(), a single call to mtaEnqueueWrite() does not necessarily correspond to a single, complete line of message data; it could correspond to a partial line, a complete line, multiple lines, or even one or more complete lines plus a partial line. This flexibility with mtaEnqueueWrite() exists because it is up to the caller to supply the message line terminators. Calling either mtaEnqueueWrite() or mtaEnqueueWriteLine() terminates the message’s envelope recipient list. Once either of these routines have been called, mtaEnqueueTo() can no longer be called for the same enqueue context.

Return Values

Return Values  

Description  

0

Normal, successful completion. 

MTA_BADARGS

This value is returned for one of the following reasons: 

  1. A NULL value was supplied for the nq_ctx call argument.

  2. An invalid enqueue context was supplied for nq_ctx, or a required argument to an item code was NULL.

MTA_FCREATE

Unable to create a disk file. 

MTA_FIO

Error writing to a disk. 

MTA_ORDER

Call made out of order. No envelope recipient addresses have been supplied. 

MTA_THREAD

Simultaneous use of the enqueue context by two different threads was detected. 

Example

The code fragment that follows shows two ways to produce the same results. They both write two header lines to the message:


mtaEnqueueWrite(nq, "From: sue@siroe.com\n", 0, NULL);
mtaEnqueueWrite(nq, "Subject: test\n", 0, NULL);


mtaEnqueueWrite(nq, "From: sue@siroe.com\nSubject: test\n", 0,
                NULL);

The following code fragment shows the two header lines output by each code fragment in the preceding code example.


 From: sue@siroe.com
Subject: test

This code fragment demonstrates how to terminate the message header by writing a blank line.

mtaEnqueueWrite(nq, "\n", 0, NULL);

The following code fragment shows a single call to mtaEnqueueWrite()that writes out an entire header, including the terminating blank line.


mtaEnqueueWrite(nq, "Date: today\nFrom: sue@siroe.com\n"
                    "To: bob@siroe.com\nSubject: test\n\n", 0,
                    NULL);

The following code example shows an alternate way of writing the routine call, but with one pair per line.


mtaEnqueueWrite(nq, "Date: today\n", 0,
                    "From: sue@siroe.com\n", 0,
                    "To: bob@siroe.com\n", 0,
                    "Subject: test\n", 0,
                    "\n", 0,
                    NULL);