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

Chapter 8 mtaSend() Routine Specification

This chapter contains the functional specification of the mtaSend() routine. It includes the following sections:

List of Item Codes

MTA_ADR_NOSTATUS

MTA_ADR_STATUS

MTA_BCC

MTA_BLANK

MTA_CC

MTA_CHANNEL

MTA_CFILENAME

MTA_CFILENAME_NONE

MTA_CTYPE

MTA_ENC_BASE64

MTA_ENC_BASE85

MTA_ENC_BINHEX

MTA_ENC_BTOA

MTA_ENC_COMPRESSED_BASE64

MTA_ENC_COMPRESSED_BINARY

MTA_ENC_COMPRESSED_UUENCODE

MTA_ENC_HEXADECIMAL

MTA_ENC_NONE

MTA_ENC_PATHWORKS

MTA_ENC_QUOTED_PRINTABLE

MTA_ENC_UNKNOWN

MTA_ENC_UUENCODE

MTA_END_LIST

MTA_ENV_FROM

MTA_FRAGMENT_BLOCKS

MTA_FRAGMENT_LINES

MTA_ENV_TO

MTA_FROM

MTA_HDR_ADRS

MTA_HDR_BCC

MTA_HDR_CC

MTA_HDR_FILE

MTA_HDR_LINE

MTA_HDR_NOADRS

MTA_HDR_NORESENT

MTA_HDR_PROC

MTA_HDR_RESENT

MTA_HDR_TO

MTA_HDRMSG_FILE

MTA_HDRMSG_PROC

MTA_IGNORE_ERRORS

MTA_INTERACTIVE

MTA_ITEM_LIST

MTA_MAX_TO

MTA_MODE_BINARY

MTA_MODE_TEXT

MTA_MSG_FILE

MTA_MSG_PROC

MTA_NOBLANK

MTA_NOIGNORE_ERRORS

MTA_PRIV_DISABLE_PROC

MTA_PRIV_ENABLE_PROC

MTA_SUBADDRESS

MTA_SUBJECT

MTA_TO

MTA_USER

mtaSend() Syntax

Syntax

int mtaSend(mta_item_list_t *item_list)

Arguments

item_list

The mtaSend() routine takes only one argument, item_list, which is a pointer to an array of item descriptors. Each item descriptor specifies an action to be taken, and provides the information needed to perform that action.

The list of item descriptors is terminated with an entry containing the MTA_END_LIST (0) item code.

Each item descriptor has the following C-style structure declaration:


struct {
  int         item_code;
  const void *item_address;
  int         item_length;
  int         item_status;
  const char *item_smessage;
} mta_item_list_t;

Item Descriptor Fields

item_code

Integer item code specifying an action to be taken by mtaSend(). The include file described in Chapter 1, MTA SDK Concepts and Overview defines these codes. Each item code is described later in this chapter, starting at Item Codes.

item_address

The caller-supplied address of data to be used in conjunction with the action specified by the item_code field. Not all actions require that an item_address be supplied.

item_length

When the item code has an associated string value, this field optionally provides the length in bytes of the string, not including any NULL terminator. If a value of zero (0) is supplied, then the string pointed to by item_address must be NULL terminated, so that mtaSend() can automatically determine the string’s length.

When the item code has an associated integer value, this field supplies that value.

item_status

When the item code MTA_ADR_STATUS is specified, this field will contain processing status for the associated envelope recipient address.

item_smessage

When the item code MTA_ADR_STATUS is specified, this field will contain the rewritten form of the envelope recipient address when the returned value of item_status is zero, or a textual error message when the returned value of item_status is non-zero.

Description

Use mtaSend() to send a message. The routine performs the processing carried out to address the message, generate the message’s header and body, and enqueue the message as specified with the item_list argument. For instructions on how to use mtaSend(), see Chapter 7, Using Callable Send mtaSend().

Item Codes

MTA_ADR_NOSTATUS

Do not return status messages for To:, Cc:, and Bcc: addresses. This is the default setting.

The item_address and item_length fields are ignored for this item code.

MTA_ADR_STATUS

Return textual status messages for each envelope recipient address (that is, an active transport address) specified with any of these item codes: MTA_TO, MTA_CC, MTA_BCC, MTA_HDR_TO, MTA_HDR_CC, or MTA_HDR_BCC. When a recipient address is successfully processed, the value of the associated item_status field will be zero and item_smessage will be a pointer to a NULL terminated string containing the rewritten form of the address. When a recipient address fails to be processed successfully, the value of the associated item_status field will be non-zero and item_smessage will be a pointer to a NULL terminated error message string.

After calling mtaSend() with MTA_ADR_STATUS, call the mtaSendDispose() function to dispose of any dynamic memory allocated by mtaSend().

The item_address and item_length fields are ignored for this item code.

MTA_BCC

Specify a blind carbon copy (Bcc:) address. The item_address and item_length fields specify the address and length of a string containing a Bcc: address. The length of the address may not exceed ALFA_SIZE bytes.

MTA_BCC is used to specify a Bcc: address that should appear in both the message’s header and envelope.

MTA_BLANK

When processing multiple input sources, insert a blank line between the input from each source. Ordinarily, the input files are appended one after the other with no delimiters or separators. This is the action selected with the MTA_NOBLANK item code. By specifying the MTA_BLANK action, mtaSend() inserts a blank line between each input file. This is especially useful when the first input file is to be treated as a source of header information and the second as the message body or part thereof. This produces the requisite blank line between the message header and body.

The item_address and item_length fields are ignored for this item code.

MTA_CC

Specify a carbon copy (Cc:) address. The item_address and item_length fields specify the address and length of a string containing a Cc: address. The length of the address may not exceed ALFA_SIZE bytes.

MTA_CC is used to specify a Cc: address that should appear in both the message’s header and envelope.

MTA_CHANNEL

Specify the channel to act as, when enqueuing the message. If not specified, then mail will be enqueued as though sent from the local, l, channel. The item_address and item_length fields specify the address and length of a text string containing the name of the channel to act as. The length of the string may not exceed CHANLENGTH bytes.

MTA_CFILENAME

When MTA_CFILENAME is specified, the name of the message input file will be included as a parameter in the MIME Content-type: header line. This action, when specified, will hold for all subsequent input files until an MTA_CFILENAME_NONE action is seen in the same item list.

MTA_FILENAME_NONE is the default.

MTA_CFILENAME_NONE

The default action for including or not including the name of the message input file as a parameter in the MIME Content-type: header line. This item code specifies that no input file is to be included.

When MTA_CFILENAME has been specified, it will hold for all subsequent input files until an MTA_CFILENAME_NONE action is seen in the same item list.

The item_address and item_length fields are ignored for this item code.

MTA_CTYPE

Specify the body of a Content-type: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Content-type: header line. The length of the string may not exceed ALFA_SIZE bytes. Only one Content-type: body may be specified.

MTA_ENC_BASE64

Encode data from all subsequent input sources using MIME’s BASE64 encoding. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_BASE85

Encode data from all subsequent input sources using Adobe’s ASCII85 encoding (BASE85). This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_BINHEX

Encode data from all subsequent input sources using the BINHEX encoding. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_BTOA

Encode data from all subsequent input sources using the UNIX® binary-to-ASCII (BTOA) encoding. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_COMPRESSED_BASE64

Encodes data from all subsequent input sources using MIME’s BASE64 encoding after first compressing it using Gnu zip. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_COMPRESSED_BINARY

Compress the data with Gnu zip. No other encoding of the data will be done. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_COMPRESSED_UUENCODE

Encode data from all subsequent input sources using UUENCODE, after first compressing the data with Gnu zip. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_HEXADECIMAL

Encode data from all subsequent input sources using a hexadecimal encoding. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_NONE

Data from all subsequent input sources is left unencoded (that is, not encoded). This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_PATHWORKS

Encodes multipart and binary message contents using the OpenVMS Pathworks format. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_QUOTED_PRINTABLE

Encode data from all subsequent input sources using MIME’s quoted printable encoding. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_UNKNOWN

Data from all subsequent input sources is left unencoded (that is, not encoded). This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_ENC_UUENCODE

Encode data from all subsequent input sources using UUENCODE. This setting may be changed with any of the other MTA_ENC_ item codes. The default encoding is MTA_ENC_UNKNOWN. The item_address and item_length fields are ignored for this item code.

MTA_END_LIST

Terminate an item list. This item code, when encountered, signals the end of the item list. The item_address and item_length fields are ignored for this item code.

MTA_ENV_FROM

Specify the envelope From: address to associate with a message. The item_address and item_length fields specify the address and length of a text string containing the envelope From: address to use for the message submission. The length of the string may not exceed ALFA_SIZE bytes. Only one envelope From: address may be specified.

The MTA_ENV_FROM action should be used when the envelope From: address is not a local address. When the address is a local address, then only the user name should be specified using the MTA_USER action.

If this action and the MTA_USER actions are not specified, then the user name associated with the current process will be used.

Do not use this item code in conjunction with the MTA_USER or MTA_SUB_USER item codes.

MTA_ENV_TO

Specify an envelope-only To: address (that is, an active recipient), which should not appear in the message’s header. The item_address and item_length fields specify the address and length of a string containing a To: address. The length of the address may not exceed ALFA_SIZE bytes.

MTA_FRAGMENT_BLOCKS

Specify the maximum number of blocks per message. If, when the message is enqueued, the message size exceeds this limit, then the message will be fragmented into smaller messages, each fragment no larger than the specified block size. The individual fragments are MIME compliant messages that use MIME’s message/partial content type. MIME compliant mailers or user agents that receive the fragments may automatically reassemble the fragmented message. (MTA channels must be marked with the defragment keyword in order for automatic message reassembly to occur.)

The size of a block may vary from site to site. Sites can change this value from its default value of 1,024 bytes. Use the MTA SDK routine mtaBLOCK_SIZE to determine the size in bytes of a block.

The item_length field specifies the maximum block size per message or message fragment. By default, no limit is imposed.

MTA_FRAGMENT_LINES

Specify the maximum number of message lines per message. If, when the message is enqueued, the number of message lines exceeds this limit, then the message will be fragmented into smaller messages, each fragment with no more than the specified number of lines. The individual fragments are MIME compliant messages that use MIME’s message/partial content type. MIME compliant mailers or user agents that receive the fragments may automatically reassemble the fragmented message. (MTA channels must be marked with the defragment keyword in order for automatic message reassembly to occur.)

The item_length field specifies the maximum number of message lines per message or message fragment. By default, no limit is imposed.

MTA_FROM

Specify the address to use in the message header’s From: header line. The item_address and item_length fields specify the address and length of a text string containing the From: address. The length of the string may not exceed ALFA_SIZE bytes. Only one From: address may be specified.

If this action is not used, then the From: header line will be derived from the envelope From: address.

MTA_HDR_ADRS

Specify MTA_HDR_ADRS to request that the message also be sent to recipient addresses found in any input header files. The item_address and item_length fields are ignored for this item code.

MTA_HDR_BCC

Specify a header-only Bcc: address (that is, an inactive recipient), which should only appear in the message’s header. The item_address and item_length fields specify the address and length of a string containing a Bcc: address. The length of the address may not exceed ALFA_SIZE bytes.

MTA_HDR_CC

Specify a header-only carbon copy (Cc:) address (that is, an inactive recipient), which should only appear in the message’s header. The item_address and item_length fields specify the address and length of a string containing a Cc: address. The length of the address may not exceed ALFA_SIZE bytes.

MTA_HDR_FILE

Specify the name of an input file containing message header lines. The first input file may be a file containing a message header. In this case, it should be specified using this item code rather than MTA_MSG_FILE. This will ensure that the input file receives the proper processing (such as, is not encoded, accessed using text mode access). The mtaSend() routine uses the header lines from the input file to form an initial message header. This initial header is then modified as necessary. This functionality is useful when forwarding mail.

Note that any recipient addresses in the header file will be ignored unless MTA_HDR_ADRS is also specified.

The item_address and item_length fields specify the address and length of a text string containing the input file’s name. The length of the string may not exceed ALFA_SIZE bytes.

MTA_HDR_LINE

Specify an additional header line to include in the message header. The item_address and item_length fields specify the address and length of the header line (field name and body) to place in the message header. The length of the string may not exceed ALFA_SIZE bytes. Any number of header lines may be added. Use one item list entry per header line.

MTA_HDR_NOADRS

Recipient addresses must be explicitly specified and any addresses in an input header file will be ignored (but will still appear in the message header). The item_address and item_length fields are ignored for this item code.

This is the default action for recipient addresses found in input header files.

MTA_HDR_NORESENT

Specify MTA_HDR_NORESENT to cause additional addresses to be added to existing header lines rather than through the introduction of Resent- header lines.

The item_address and item_length fields are ignored for this item code.

MTA_HDR_PROC

Specify the address of a procedure that will return, one line at a time, header lines for the message header. The item_address field specifies the address of the procedure to invoke. The item_length field is ignored.

The calling format that must be used by the procedure is given in Message Headers and Content.

MTA_HDR_RESENT

The MTA_HDR_RESENT action selects the default behavior whereby Resent- header lines are added as necessary to the message header when the associated header line appears in any input header files. For instance, a Resent-to: header line will be added if a To: header line already appears. The item_address and item_length fields are ignored for this item code.

MTA_HDR_TO

Specify a header-only To: address (that is, an inactive recipient), which should only appear in the message’s header. The item_address and item_length fields specify the address and length of a string containing a To: address. The length of the address may not exceed ALFA_SIZE bytes.

MTA_HDRMSG_FILE

Specify the name of an input file containing both the message header and message body. The content of the file represents an RFC 2822 formatted message with at least one blank line separating the RFC 2822 header from the message body. The mtaSend() routine uses the header lines from the input file to form an initial message header. This initial header is then modified as necessary.

The item_address and item_length fields specify the address and length of a text string containing the input file’s name. The length of the string may not exceed ALFA_SIZE bytes.

MTA_HDRMSG_PROC

Specify the address of a procedure that will return, one line at a time, each line of an RFC 822 formatted message. The RFC 822 header must come first, followed by at least one blank line, followed by the message body. The item_address field specifies the address of the procedure to invoke. The calling format that must be used by the procedure is given in Message Headers and Content.

MTA_IGNORE_ERRORS

Send the message as long as at least one To: address was okay and at least one input source was okay. By default, the message will not be sent if any of the To: addresses are illegal (such as, bad syntax, restricted, unknown host), or if any of the input sources proved to be bad (such as, could not open an input file). The item_address and item_length fields are ignored for this item code.

MTA_INTERACTIVE

Do not ignore user-to-channel access checks when enqueuing mail. This should, in general, be used by programs such as user agents that enqueue mail for users.

The item_address and item_length fields are ignored for this item code.

MTA_ITEM_LIST

The mtaSend() routine immediately begins processing the list of item descriptors pointed at by item_address. This new list will be used immediately; any remaining items in the current list will be ignored.

The item_length field is ignored for this item code.

MTA_MAX_TO

Specify the maximum number of envelope To: addresses per message copy. If, when the message is enqueued, the number of envelope To: addresses for the message exceeds this limit, then the message will be broken into multiple copies, each copy with no more than the specified number of envelope To: addresses.

The item_length field specifies the maximum number of envelope To: addresses per message copy. By default, no limit is imposed.

MTA_MODE_BINARY

Read subsequent input files as raw binary files. This setting may be changed with the MTA_MODE_TEXT item code. The default access mode is MTA_MODE_TEXT.

The item_address and item_length fields are ignored for this item code.

MTA_MODE_TEXT

Read subsequent input files as record-oriented text files. This setting may be changed with the MTA_MODE_BINARY item code. The default access mode is MTA_MODE_TEXT.

The item_address and item_length fields are ignored for this item code.

MTA_MSG_FILE

Specify an input file to read and include in the message body. The file will be read using the current access mode and encoded using the current encoding as specified by MTA_MODE_ and MTA_ENC_ item codes.

The item_address and item_length fields specify the address and length of a text string containing the name of the input file. The length of the string may not exceed ALFA_SIZE bytes.

MTA_MSG_PROC

Specify the address of a procedure that will return, one line at a time, data for the message body. Each line of input obtained from the procedure will be treated using the current access mode and encoded using the current encoding as specified by MTA_MODE_ and MTA_ENC_ item codes. Note, however, that the block access mode will not be applied to input procedures.

The item_address field specifies the address of the procedure to invoke. The item_length field is ignored.

The calling format that must be used by the procedure is given in Message Headers and Content.

MTA_NOBLANK

When processing multiple input source, do not insert a blank line between the input from one source and the next. This is the default behavior. The input from each input source is appended one after the other with no delimiters or separators marking the transition between sources.

The item_address and item_length fields are ignored for this item code.

MTA_NOIGNORE_ERRORS

Send the message only if all To: addresses are okay and all input sources are okay. This is the default.

The item_address and item_length fields are ignored for this item code.

MTA_PRIV_DISABLE_PROC

The address of a procedure to invoke immediately after enqueuing a message so as to disable process privileges. See the description of MTA_PRIV_ENABLE_PROC for details on the use of this item code.

This item code must be used in conjunction with MTA_PRIV_ENABLE_PROC item.

The item_length field is ignored for this item code.

MTA_PRIV_ENABLE_PROC

The address of a procedure to invoke immediately before enqueuing a message so as to enable process privileges.

Privileges are required to enqueue messages. It is possible to provide mtaSend() with the address of two procedures to call. One procedure is called immediately prior to enqueuing a message thereby allowing process privileges to be enabled. The second procedure is then called immediately after the message has been enqueued thereby allowing process privileges to be disabled.

For further details on the use of this item code, see Required Privileges for mtaSend().

This item code must be used in conjunction with MTA_PRIV_DISABLE_PROC.

The item_length field is ignored for this item code.

MTA_SUBADDRESS

Specify a subaddress to use when generating a return address from a user name specified with the MTA_USER item code. The item_address and item_length fields specify the address and length of a text string containing the subaddress. The length of the string may not exceed ALFA_SIZE bytes. Only one subaddress may be specified per message.

The MTA_USER action must be used in conjunction with this item code.

MTA_SUBJECT

Specify the body of a Subject: header line. The item_address and item_length fields specify the address and length of a text string to place in the body of a Subject: header line. The length of the string may not exceed ALFA_SIZE bytes. Only one Subject: body may be specified.

MTA_TO

Specify a To: address that should appear in both the message’s header and envelope. The item_address and item_length fields specify the address and length of a string containing a To: address. The length of the address may not exceed ALFA_SIZE bytes.

MTA_USER

Specify the user name to use for the envelope From: and header line From: addresses. The item_address and item_length fields specify the address and length of a text string containing the user name.

Use this item code when the envelope From: address is a local address.

If the envelope From: address is not a local address, then the MTA_ENV_FROM action should be used.

If this action and the MTA_ENV_FROM actions are not specified, then the user name associated with the current process will be used.

On UNIX, the process must have the same (real) UID as the root or mta account. If the process lacks sufficient privileges, the MTA_ACCESS error will be returned.

Do not use this item code in conjunction with the MTA_ENV_FROM item code.