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

mtaOptionString()

Return an option’s value as a string.

Syntax


int mtaOptionString(mta_opt_t  *opt_ctx,
                    const char *name,
                    size_t      len,
                    const char *str,
                    size_t     *str_len,
                    size_t      str_len_max);

Arguments

Arguments  

Description  

opt_ctx

An option context created by mtaOptionStart(). A NULL value is permitted for this argument. When a NULL is passed, then no option value is returned.

name

Name of the option to obtain the value for. The length of this string should not exceed ALFA_SIZE bytes. This string must be NULL terminated if a value of zero is passed for len.

len

Length in bytes, not including any NULL terminator, of the option name supplied with name. If a value of zero is supplied, then the option name string must be NULL terminated. 

str

A pointer to a buffer to receive the NULL terminated value of the specified option. The MTA allows channel options to have a maximum length of BIGALFA_SIZE bytes. As a result, this buffer should in general have a length of at least BIGALFA_SIZE+1 bytes. If the option was not specified in the option file, then the contents of the buffer is left untouched.

str_len

An optional pointer to a size_t to receive the length in bytes of the returned option value string, str. A value of NULL may be passed for this call argument.

str_len_max

The maximum size in bytes of the buffer pointed at by str.

Description

Use mtaOptionString() to retrieve the string representation of an option’s value. If the option is specified in the option file, then its value and length will be returned via the str and str_len call arguments. If the option is not specified then no value is returned and the memory pointed at by str and str_len are left unchanged. This routine can be called with a NULL value for the opt_ctx argument. When this is done, mtaOptionString() immediately returns with a status code of zero and no option value is returned.

Return Values

Return Values  

Description  

0

Normal, successful completion. 

MTA_STRTRU

Supplied buffer pointed at by buf is too small. The returned value has been truncated to fit. Truncated value is NULL terminated. The buffer should have a length of at least BIGALFA_SIZE+1 bytes.

MTA_STRTRUERR

The supplied option name is too long. Its length must not exceed ALFA_SIZE bytes.

Example

In the code example that follows, the value of an option named mail_url is retrieved. Before calling mtaOptionString(), a default value is set for the variable to receive the value of the option. If the option was not specified, then the variable will retain that default setting. If the option was specified, then the variable will assume the value set by that specification.


char url[1024];

strcpy(url, "mail_to:webmaster@siroe.com");
mtaOptionString(opt, "mail_url", 0, url, NULL, sizeof(url));