NAME

     immd_get_recipient - accessing envelope recipients


SYNOPSIS

     #include <imta.h>

     int immd_get_recipient(immd_t md, int  *flags, char  **rcpt,
     char **orcpt);

     int immd_rewind_recipients(immd_t md);

     void *immd_get_recipient_data(immd_t md);

     void immd_set_recipient_data(immd_t md, void *data);


DESCRIPTION

     immd_get_recipient() is used to retrieve envelope recipients
     attached to a message.  As each call to immd_get_recipient()
     retrieves at most  one  recipient,  this  function  much  be
     called repeatedly, until all recipients have been retrieved.

     Envelope recipients can be retrieved after opening the  mes-
     sage with immd_get_message() and before starting to read the
     contents  of  the  message  (headers,  body).    After   all
     addresses  have been retrieved, immd_get_recipient() returns
     IMRC_EOF. For example,  if  the  message  envelope  has  two
     envelope     recipients,     then     three     calls     to
     immd_get_recipient() should be made.  The  first  two  calls
     will  retrieve  the recipients and return IMRC_OK. The third
     will not retrieve any recipient and will return IMRC_EOF.

     In some cases though, it is convenient for calling  programs
     to  browse  the envelope recipient list later on in the mes-
     sage    processing.     If     that     is     the     case,
     immd_rewind_recipients()  must be called to rewind the reci-
     pient list prior to accessing it, so that  subsequent  calls
     to  immd_get_recipient()  can  be used to retrieve all reci-
     pients, as explained above.

     To further reduce the need for  the  caller  to  create  and
     maintain   their   own  recipient  list,  the  entry  points
     immd_set_recipient_data() and immd_get_recipient_data()  can
     be  used to respectively set and access caller-specific data
     attached to one recipient.  Either of these calls  apply  to
     the last recipient returned by immd_get_recipient().

     The final (rewritten) form of  the  recipient's  address  is
     placed in a buffer referenced by rcpt.

     The orcpt gives, if known, the original form of the envelope
     To: address. This is useful when dealing with messaging for-
     mats such as X.400 which retain such information.  When  re-
     enqueuing  a  message,  this information can be subsequently
     passed back into imme_add_recipient() and otherwise used  or
     discarded as appropriate.

     The memory to  allocated  by  the  library  to  store  these
     addresses   is   valid   until  immd_dequeue(),  immd_end(),
     immd_get_message(), or immd_defer() is called.

     md is the dequeue context  output  by  an  earlier  call  to
     immd_init() .

     flags is set by the library to the  notary  flags  for  this
     recipient  the  value is a bitwise OR of zero or more of the
     following constants.

     IM_NOTIFY_FAILURE     A DSN is  requested  if  the  delivery
                           fails permanently

     IM_NOTIFY_SUCCESS     A DSN is requested if the delivery  is
                           successful

     IM_NOTIFY_DELAY       A DSN is  requested  if  the  delivery
                           fails temporarily

     IM_NOTIFY_NEVER       no DSN is requested whatsoever


RETURN VALUES

     IMRC_OK     The call is successful and an address is output.

     IMRC_EOF    There are no more addresses to read.

     IMRC_BAD_CONTEXT
                 The dequeue context md has not been  initialized
                 or  has  been  corrupted.  Make sure immd_init()
                 has been previously called.

     IMRC_NO_MESSAGE
                 No message is currently  processed.   make  sure
                 the previous call to immd_get_message() returned
                 successfully.

     IMRC_MESSAGE_CORRUPTED
                 it is likely that the file could  not  be  read,
                 because  it  was deleted or because it's missing
                 both message header and message body.  This  can
                 happen consecutively to a hardware failure.

     The calling program should  then  abort  processing  of  the
     current   message   and   call   either   immd_dequeue()  or
     immd_defer().  In this particular case, both calls have  the
     same effect.

     A textual version reason for the failure can be obtained  by
     calling imta_error() immediately afterwards.


ATTRIBUTES

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


SEE ALSO

     immd_init(3), imta_error(3), immd_get_message(3)