NAME
imadr_parse_list, imadr_get, imadr_get_property, imadr_free
- rfc822 address parsing routines
SYNOPSIS
#include <rfc822.h>
int imadr_parse_one(char *result, imadr_prop_t property,
const char *address);
int imadr_parse_list(imadr_t *adr, char *line);
int imadr_get(imadr_t *adr, int index, char **address);
int imadr_get_property(imadr_t *adr, int index,
imadr_prop_t property, char **result);
void imadr_free(imadr_t *adr);
DESCRIPTION
imadr_parse_one() may be used to parse a single address
referenced by address and return the desired property, in
the caller-allocated buffer result, whose size must be at
least IMADR_PROPER_LEN bytes long. Moreover, it can be used
to see if an address is syntactically legal and to clean up
addresses with minor syntax problems. The former is accom-
plished by requesting the IMADR_PROPER property.
Upon succes the requested property is copied in this buffer,
and the length of the property is returned. See below the
allowed values for property.
imadr_parse_list() may be used to parse a line of one or
more comma-separated RFC 822 addresses. The input line may
be of arbitrary length. The result of the parsing is refer-
enced by the passed address context, adr, and the count of
addresses parsed is returned.
After calling imadr_parse_list(), each parsed address may
then be individually extracted from the address context by
calling imadr_get(). The extracted address is placed in the
buffer referenced by address and the length of the address
is returned. index argument may range from 1 to the count
of parsed addresses returned by imadr_parse_list(). The
value output by previous calls to imadr_get() is lost.
Therefore, be sure to save the content of address before
calling imadr_get() again.
After calling imadr_parse_list(), each property of each
address may then be extracted from the address context adr
by calling imadr_get_property(). The extracted property is
placed in the buffer referenced by result and the length of
the address is returned. See below the allowed values for
property. index argument may range from 1 to the count of
parsed addresses returned by imadr_parse_list(). The value
output by previous calls to imadr_get_property() related to
a different address, is lost. Therefore, be sure to save the
content of property before calling imadr_get_property()
again for a different address.
If the following example address is parsed:
phrase <@otherhost:user@host>
The accepted values of property are:
IMADR_ADDRESS Address part ( @otherhost:user@host ) of
the address
IMADR_DOMAIN Domain part ( host ) of the address
IMADR_LOCAL Local part ( user ) of the address
IMADR_PHRASE Phrase part ( phrase ) of the address, if
any
IMADR_PROPER Phrase part ( phrase
<@otherhost:user@host> ) of the address,
if any
IMADR_ROUTE Source route part ( @otherhost: ) of the
address, if any
When the address list manipulation is completed imadr_free()
should be called to free the memory allocated by
imadr_parse_list(). This function need not be called if
only imadr_parse_one() has been used.
RETURN VALUES
If successful, imadr_parse_list() returns the count of
addresses parsed. imadr_parse_one(), imadr_get(), and
imadr_get_property() return the length in byte of the pro-
perty or address returned.
-1 is returned if either the property code or index is out
for range. No address is returned.
imadr_parse_one() also returns -1 if the result buffer is
smaller than IMADR_PROPER_LEN bytes long.
ATTRIBUTES
_______________________________________
| Attribute Type | Attribute Value|
|____________________|_________________|
| Architecture | sparc, x86 |
|____________________|_________________|
| Availability | SUNWimsdk |
|____________________|_________________|
| MT-Level | MT-Safe |
|____________________|_________________|
| Interface Stability| Stable |
|____________________|_________________|
SEE ALSO
imta_error(3).