NAME

     imhdr_alloc,       imhdr_add_line,        imhdr_delete_line,
     imhdr_get_line,  imhdr_free, imhdr_free_line - rfc822 header
     manipulations.


SYNOPSIS

     #include <rfc822.h>

     int  imhdr_alloc(imhdr_t *hdr);

     int  imhdr_add_line(imhdr_t *hdr, int type, char *line,  int
     insert);

     int  imhdr_delete_line(imhdr_t hdr, int type);

     int  imhdr_get_line(imhdr_t hdr, int type, char **line);

     int  imhdr_free_line(imhdr_t hdr, char *line);

     void imhdr_free(imhdr_t hdr);


DESCRIPTION

     imhdr_alloc() allocates  and  initializes  a  header  object
     referenced by hdr.  immd_read_header() is the only other way
     of creating a header object.  Either of these functions must
     be called prior to calling any of the following.

     imhdr_add_line() adds a header line of the specified type to
     the  header  object  referenced  by hdr.  type specifies the
     type of header  line  being  added  (e.g.,  HL_FROM,  HL_TO,
     HL_DATE,  etc.).  The  accepted  header types are defined in
     rfc822_header.h; Header lines of types that are not  defined
     in  this  file  can be generated by using the HL_OTHER type.
     In this case, the full header line, field name,  colon,  and
     body,  must be specified (e.g., "X-whatever: bob@yoyo.com"),
     whereas for known header types, line may specify either  the
     entire header line or just the header value.

     If there are several header lines of a  given  type,  insert
     can  be  used  to  specify  that  the added header line must
     appear first among the header lines  of  this  type  in  the
     header  object.   A value of 0 will make this line appear in
     the header after the previously created lines  of  the  same
     type.

     imhdr_delete_line() removes all header lines  of  the  given
     type  from  the  header object referenced by hdr.  As above,
     the accepted types are defined in  rfc822_header.h;  specify
     HL_OTHER for a header line type not recognized by the API.

     imhdr_get_line() may be called to extract one header line of
     a  given  type.   Upon success, line points to the extracted
     header line (label and value), and the length of this header
     line  is returned.  A return value of 0 signifies that there
     are no or no more header lines of this type, in  the  header
     context  referenced by hdr.  All header line of a given type
     can be obtained by calling repetedly imhdr_get_line()  until
     0 is returned.

     Every header line obtained with imhdr_get_line() is left  to
     the caller to free, by calling imhdr_free_line().

     imhdr_free() must be called to dispose of a previously allo-
     cated   header   object  created  by  immd_read_header()  or
     imhdr_alloc().


RETURN VALUES

     imhdr_get_line() returns the length in  bytes  of  the  line
     returned, or 0 if there are no (more) line of the given type
     .

     All other calls return 0 when successful.

     A value of -1 is returned if the requested  header  type  is
     invalid.


NOTES

     The insert argument is not functional in this  beta  version
     of the SDK.

     The HL_OTHER header type doesn't work in this version.  Will
     be fixed for FCS.


ATTRIBUTES

               _______________________________________
              |   Attribute Type   |  Attribute Value|
              |____________________|_________________|
              | Architecture       |  sparc, x86     |
              |____________________|_________________|
              | Availability       |  SUNWimsdk      |
              |____________________|_________________|
              | MT-Level           |  MT-Safe        |
              |____________________|_________________|
              | Interface Stability|  Stable         |
              |____________________|_________________|


SEE ALSO

     imta_header.h(4), immd_read_header(3)