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:
-
The length of the address may not exceed 256 bytes. This is the length
limit imposed by RFCs 2821 and 2822. It is also the size denoted by the ALFA_SIZE constant.
-
Older MTAs may not support envelope addresses of lengths exceeding
129 bytes. This is the length limit imposed by RFC 821.
-
To specify an empty envelope From: address, supply
an empty string for env_from and a length of zero for env_from_len, or supply a value of NULL for env_from and
any value for env_from_len.
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:
-
The address of the string containing the channel name.
-
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:
-
The address of the envelope ID string.
-
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:
-
A NULL value was supplied for the nq_ctx call argument.
-
An invalid enqueue context was supplied for nq_ctx.
-
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.