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

mtaEnqueueStart()

Initiate a message submission.

Syntax


int mtaEnqueueStart(mta_nq_t   **nq,
                    const char *env_from,
                    size_t      env_from_len,
                    int         item_code, ...);

Arguments

Arguments  

Description  

nq_ctx

On a successful return, a pointer to an enqueue context created by mtaEnqueueStart(). This enqueue context represents the message enqueue operation initiated by the call.

env_from

Optional pointer to the address to use as the envelope From: address for the message being submitted. The address must be compliant with RFC 2822. When used as an envelope address, the MTA will reduce it to an RFC 2821 compliant transport address. The string must be NULL terminated if a value of zero is passed for env_from_len. The length of this string, not including any NULL terminator, may not exceed ALFA_SIZE bytes.

A value of NULL may be supplied for this argument. When that is done, the env_from_len argument is ignored and an empty envelope From: address is used for the message submission.

env_from_len

The length in bytes, not including any NULL terminator, of the envelope From: address supplied with env_from. If a value of zero is passed for this argument, then the envelope From: address string must be NULL terminated.

item_code

An optional list of item codes. See the description section that follows for a list of item codes. The list must be terminated with an integer argument with value 0.

Description

To submit a message to the MTA for delivery, an enqueue operation must be initiated. This is achieved by calling mtaEnqueueStart(). When the call is successful, an enqueue context representing the enqueue operation will be created and a pointer to the context returned via the nq_ctx call argument. This context must then be used to specify the message’s envelope recipient list and content, both header and body. Once the recipient list and content have been specified, the submission may be completed with mtaEnqueueFinish(). That same routine is also used to cancel an enqueue operation. For further information on message enqueue processing, see Basic Steps to Enqueue Messages.

Enqueue contexts are disposed of with mtaEnqueueFinish(), either as part of completing or cancelling a message enqueue operation.

When initiating an enqueue operation, the envelope From: address for the message should be specified with the env_from and env_from_len call arguments, or through use of a dequeue context with the MTA_DQ_CONTEXT item code. In either case, it is important to keep in mind the usage of the envelope From: address. MTAs transporting the message use it as a return path, that is, the address to which notifications about the message should be returned. Specifically, it is the address to which the message will be returned in the form of a non-delivery notification (NDN) should the message prove undeliverable. It is also the address to which any delivery status notifications (DSNs) will be sent. As such, the envelope From: address specified should be an address suitable for receiving such notifications.


Note –

Automatically generated messages such as NDNs and DSNs are required to have an empty envelope From: address, that is, a zero length address. These rules are mandated by Internet standards so as to prevent broad classes of looping messages. It is imperative that they be observed; failure to do so may result in exponentially growing mail loops that affect not only your own mail system but possibly mail systems of other sites with which you exchange mail.


When explicitly specifying the envelope From: address via the env_from and env_from_len call arguments, note the following points:

When using a dequeue context to supply the envelope From: address, simply supply a value of NULL and zero for, respectively, the env_from and env_from_len call arguments. Be sure to also supply the dequeue context with the MTA_DQ_CONTEXT item code. For example:

ires = mtaEnqueueStart(&nq, NULL, 0, MTA_DQ_CONTEXT, dq, 0);

If the submitted message lacks a From: header line, then the address supplied as the envelope From: address will also be used to generate a From: header line. This is the reason why mtaEnqueueStart() allows an RFC 2822 compliant address to be supplied for the envelope From: address. When placing the supplied address into the envelope, the MTA reduces it to an RFC 2821 compliant address (for example, removes any RFC 2822 phrases or comment fields).

When submitting a message, the MTA requires a source channel to associate with the enqueue operation. By default, the name of the source channel will be derived from the PMDF_CHANNEL environment variable. However, this may be overridden one of two ways: by supplying a dequeue context with the MTA_DQ_CONTEXT item code, or by explicitly specifying the channel name with the MTA_CHANNEL item code. Use of a dequeue context implicitly specifies the source channel name to be the name of the channel associated with the dequeue context.


Note –

An explicitly specified channel name will take precedence over a channel name specified with a dequeue context.


As part of initiating a message submission, item codes may be used to specify additional envelope information for the message as well as select non-default values for MTA parameters that influence message enqueue processing.

The following table lists the items codes for this routine, their additional arguments, and gives a description of each.

Item Codes  

Additional Arguments  

Description  

MTA_ALIAS_EXPAND

None 

When this item code is specified, each envelope recipient address is allowed to undergo alias expansion (for example, mailing list expansion). This is the default behavior. 

MTA_ALIAS_NOEXPAND

None 

Use of this item code inhibits alias expansion for the envelope recipient addresses. The default behavior is to permit alias expansion. 

MTA_ADR_NOSORT

None 

Inhibit sorting of the envelope recipient list in the message copies written to the MTA channel queues. By default, the envelope recipient address list is sorted. Use this option if it is imperative that the envelope recipients be processed in some specific order. Maintaining the order requires control of all MTA channels that the message will pass through. 

MTA_ADR_SORT

None 

Allow the envelope recipient list to be sorted in the message copies written to the MTA channel queues. This is the default behavior. 

MTA_CHANNEL

char *channel

size_t channel_len

Explicitly specify the name of the channel under which to enqueue this message. That is, explicitly specify the name of the source channel to use for this message submission. The name specified will override any name implicitly specified with the MTA_DQ_CONTEXT item code.

This item code must be followed by two additional call arguments: 

  1. The address of the string containing the channel name.

  2. The length in bytes of that channel name. If a value of zero is specified for the length, then the channel name string must be NULL terminated.

MTA_DELIVERY_FLAGS

size_t dflags

Specify additional envelope delivery flags to set for this message. The logical OR of any existing setting and the value here supplied will be used for the message’s delivery flag setting. In general, the delivery flag setting associated with a message will be the logical OR of the values set by each channel a message has travelled through. Note that channels also can set this value with the deliveryflags channel keyword. When this item code is not used, the delivery flags inherited from a supplied dequeue context will be used. If no dequeue context is supplied, then the value of the delivery flags will be set to zero.

This item code should be followed by an additional call argument: the value to combine with any existing setting. 

MTA_DELIVERY_FLAGS_ABS

size_t dflags

Ignore any previous envelope delivery flag setting for the message and replace the setting with the value specified with this item code. 

This item code should be followed by an additional call argument: the delivery flag setting to effect. 

MTA_DQ_CONTEXT

mta_dq_t *dq_ctx

When a dequeue context is supplied with this item code, the message submission will take all of its envelope fields, except for the recipient list, from the envelope of the queued message represented by the dequeue context, including the envelope From: field. These assumed settings can then be overridden on an individual basis through the use of other item codes, and the env_from and env_from_len call arguments.

Use of this item code changes the defaults for the envelope fields from the MTA defaults to the values used in the dequeue context. 

Intermediate processing channels are strongly encouraged to use this item code. Use of this feature allows envelope information to be automatically copied from the queued message being processed to the new message that will be enqueued as a result. 

This item code must be followed by one additional argument: the pointer to the dequeue context to use. 

MTA_ENV_ID

const char *env_id

size_t env_id_len

Explicitly specify an envelope ID string for the message. The supplied value must conform to the syntax of an xtext object in RFC 1891 and may not have a length exceeding 100 bytes. The value specified with this item code will override any value implicitly specified with the MTA_DQ_CONTEXT item code. If no value is supplied either explicitly or implicitly, then the MTA will generate a unique envelope ID for the message.

This item code must be followed by two additional call arguments: 

  1. The address of the envelope ID string.

  2. The length in bytes of that string. If a value of zero is supplied for the length, then the string must be NULL terminated.

MTA_EXPAND_LIMIT

size_t limit

If the message has more envelope recipients than the specified limit, then processing of the recipient list (that is, alias expansion) will be deferred. This deferral is performed by enqueuing the message to the reprocess channel. At a later time, and running in a separate process, the reprocess channel will complete the processing of the envelope recipient list. 

This item code must be followed by one additional argument: the limit to impose. By default, no limit is imposed. 

MTA_FRAGMENT_BLOCKS

size_t blocks

A large enqueued message may automatically be fragmented into several, smaller messages using MIME’s message/partial content type. At the destination MTA system, these smaller messages may automatically be re-assembled back into one single message. The MTA_FRAGMENT_BLOCKS item code allows specification of a size threshold for which messages larger than the threshold will automatically be fragmented. The limit specified is measured in units of blocks. (By default, a block is 1024 bytes.) However, sites may change that size with the MTA BLOCK_SIZE option. Consequently, code using this option should use the mtaBlockSize() option should they need to convert some other unit to blocks.

This item code must be followed by one additional argument: the block size threshold to impose. By default, no threshold is imposed. 

MTA_FRAGMENT_LINES

size_t lines

A large enqueued message can be automatically fragmented into several, smaller messages using the MIME content type message/partial. At the destination MTA system, these smaller messages can be automatically re-assembled back into one single message. The MTA_FRAGMENT_LINES item code allows specification of a line count threshold for which messages exceeding the threshold will automatically be fragmented.

This item code must be followed by one additional argument: the line count threshold to impose. By default, no threshold is imposed. 

MTA_NOTIFY_FLAGS

size_t nflags

Specify the delivery status notification flags to be set for the entire message. The specified value is a bit map constructed using the MTA_NOTIFY_ constants defined in mtasdk.h. If no setting is made, then the value from a supplied dequeue context will be used. If no dequeue context is supplied, then the MTA default value is used. The default value is:

MTA_NOTIFY_DELAY | MTA_NOTIFY_FAILURE | MTA_NOTIFY_CONTENT_FULL

Flags for individual recipient address may be specified when mtaEnqueueTo() is called.

This item code must be followed by one additional call argument: the address of an integer to receive the setting of the delivery status notification flags. 

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.

  3. A required argument to an item code was NULL.

MTA_NO

Unable to determine the channel name from the PMDF_CHANNEL environment variable,

MTA_NOMEM

Insufficient virtual memory. 

MTA_NOSUCHCHAN

Specified channel name does not exist in the MTA configuration. 

MTA_NOSUCHITEM

An invalid item code was specified. 

MTA_STRTRUERR

The supplied envelope From: address is too long; it may not exceed a length of ALFA_SIZE bytes. Or the supplied channel name has a length exceeding CHANLENGTH bytes.

Example

This routine is used as part of Example 5–2.