mail::folder::addMessage — Add a message to a folder
        
        
        #include <libmail/mail.H>
        
        
        class myCallback : public mail::callback {
        public:
            void success(std::string msg);
            void fail(std::string msg);
        };
        #include <libmail/addmessage.H>
        
        mail::folder *folder;
        time_t messageDate;
        mail::messageInfo newMessageInfo;
        std::string messageBody;
| mail::addMessage *msg=folder->addMessage( | myCallback &callback ); | 
        msg->messageDate=messageDate;
        msg->messageInfo=messageInfo;
        msg->saveMessageContents(messageBody);
        
        if (changedMyMind)
            msg->fail(std::string errmsg);
        else
            msg->go();
This method begins the process of manually adding a
      message to a folder. The mail::folder::addMessage method returns a
      pointer to a mail::addMessage
      object. The application should then define the contents of
      the message by invoking the object's saveMessageContents method. The entire
      contents of the message does not have to be specified at
      once. A large message may be defined by repeatedly invoking
      saveMessageContents,
      consecutively, each time specifying the next portion of the
      message's contents.
After the contents of the message are defined by invoking
      saveMessageContents, the
      application must invoke the go
      method in order to actually place the new message into the
      folder. The application may abort the process at any time by
      invoking the fail method, and
      specifying the error message.
The application does not need to explicitly destroy the
      mail::addMessage object, the
      object is automatically destroyed by go or fail.
The application may set the following mail::addMessage fields prior to invoking
      go. If not initialized, the
      following fields will be set to their default values.
The message's timestamp, as retrieved by
            mail::account::ARRIVALDATE
            parameter to mail::account::readMessageAttributes(3x)().
This timestamp does not necessarily have to be the
              same as the timestamp in the message's Date: header.
The message flags, as returned by mail::account::getFolderIndexInfo(3x)().
The contents of uid, the message's
              unique ID, are ignored, only the message flags in
              messageInfo
              are read. The message gets automatically assigned a
              new unique ID when it gets added to the folder.
        
        
        #include <libmail/mail.H>
        
        
        class myCallback : public mail::callback {
        public:
            void success(std::string msg);
            void fail(std::string msg);
        };
mail::addMessage *msg;
| msg->assembleContent( | size_t &handleRet, | 
| const mail::Attachment &attachment, | |
| mail::callback
            &cb ); | 
| msg->assembleMessageRfc822( | size_t &handleRet, | 
| std::string headers, | |
| size_t handle, | |
| mail::callback
            &cb ); | 
| msg->assembleMultipart( | size_t &handleRet, | 
| std::string headers, | |
| const std::vector<size_t> parts, | |
| std::string multipart_type, | |
| const mail::mimestruct::parameterList &options, | |
| mail::callback
            &cb ); | 
| bool
            flag=msg->assemble( | void); | 
This is an alternative way of adding a message to a folder
      by assembling it one MIME section at a time. First, use the
      assembleContent method to
      specify the individual content-containing (non-multipart and non-message/rfc822) MIME sections. Before
      assembleContent invokes
      cb's success method it will initialize
      handleRet with a
      “handle” that refers to this MIME
      section. Use these MIME section handles to assemble the
      individual MIME sections into multipart and message/rfc822 MIME sections. The
      assembleMessageRfc822 and
      assembleMultipart methods also
      create a new MIME section handle, which refers to the
      assembled MIME section, in the same way. Those handles
      themselves may also be re-assembled into higher-level
      multipart or message/rfc822 MIME sections.
Finally, after defining the topmost MIME section, use
      assemble to assemble the entire
      message. If assemble returns
      true, use the go (or the fail) method. If assemble returns false, an errno-related error has occured; the
      application should call fail to
      report it, and clean up the mail::addMessage object.
The assembleContent method
      receives a mail::Attachment(3x)
      object.
The second parameter to assembleMessageRfc822 are the MIME headers
      of the message/rfc822
      attachment. The MIME headers must be terminated by a single
      newline character, and include the Content-Type header. In nearly all
      situations, this parameter should be set to the fixed string
      “Content-Type:
      message/rfc822\n” (note the trailing
      newline). The third parameter is the handle of the
      attachment's top-level MIME section.
The second parameter to assembleMultipart is a string containing
      MIME headers for the multipart MIME section. These headers
      should not include the
      Content-Type header. The
      Content-Type header for the
      multipart section will be generated internally. If there are
      any extra headers, they must have a single trailing newline
      character. Most situations do not need extra headers, so this
      parameter should be an empty string, “”.
The third parameter to assembleMultipart is the vector of
      previously-defined handles of each MIME section that's to be
      assembled into a multipart MIME section. The fourth parameter
      is the actual MIME type of this section, usually “multipart/mixed” or “multipart/alternative” (any
      “multipart” type is allowed). The
      fifth parameter is optional, and specifies the MIME content
      type parameter list (the parameter list should not include
      the “boundary” parameter, because it's
      taken care of automatically by this function).
The last parameter to assembleContent, assembleMessageRfc822, or assembleMultipart is the callback object.
      The callback object's success
      method will be invoked when the MIME section has been
      assembled. The fail method will
      be invoked if an error occured. Depending on the type of the
      folder the message is being added to, the MIME section may be
      assembled immediately (in which case success or fail gets called right before the function
      terminates) or the function will terminate immediately, and
      the callback function will be called at a later time.
mail::addMessage *msg;
| msg->assembleImportAttachment( | size_t &handleRet, | 
| mail::account *acct, | |
| std::string uid, | |
| const mail::mimestruct &attachment, | |
| mail::callback
              &cb ); | 
| msg->assembleRemoveAttachmentsFrom( | size_t &handleRet, | 
| mail::account *acct, | |
| std::string uid, | |
| const mail::mimestruct &attachment, | |
| const std::set &mimeIdList, | |
| mail::callback
              &cb ); | 
The assembleImportAttachment function
        assembles a new MIME section by copying an existing MIME
        section from another message. acct specifies an open mail
        account, with an open mail folder. uid specifies the unique
        identifier of a message in acct's open folder, which can
        be obtained from mail::account::getFolderIndexInfo(3x).
        attachment
        specifies which attachment in message uid should be copied.
        attachment must be
        obtained using mail::account::MIMESTRUCTURE with
        mail::account::readMessageAttributes(3x).
acct can refer
          to any open mail account or folder, and does not have to
          be the same folder the message is being added to!
attachment may
        refer to a multipart, or a non-multipart MIME section. An
        attachment
        referring to a multipart MIME section imports the entire
        multipart MIME section, and all subsections it contains.
        assembleRemoveAttachmentsFrom
        also copies the entire multipart MIME section, but skips
        selected MIME subsections. Any subsection appearing in
        mimeIdList is not
        copied. mimeIdList
        is a list of MIME section identifiers, obtained from
        mail::mimestruct(3x)'s
        mime_id
        field.
assembleRemoveAttachmentsFrom implements
        the “Remove
        Attachments” function in a typical mail
        client, which removes individual attachments from a
        message. To do that, set attachment to the top-level
        MIME section that refers to the entire message (literally
        the same object returned by mail::account::readMessageAttributes(3x))
        and specify the attachments to remove in mimeIdList. Use mail::folder::addMessage(3x)
        to add the message to the same folder as the original
        message (this must be done before invoking assembleRemoveAttachmentsFrom, of
        course), then when that's done remove the original
        message.
mail::addMessage::fail
      automatically invokes the callback object's fail method, prior to returning.
      mail::addMessage::go
      automatically invokes the callback object's success method, when the message is added.
      mail::addMessage::go will
      invoke fail if the message
      cannot be added to the folder, for some reason.
The mail::folder::addMessage function returns
        a NULL pointer if the mail::addMessage object cannot be
        created. This does not necessarily indicate an
        out-of-memory condition. It is not possible to manually add
        messages to some types of folders. For example, messages
        cannot be manually added to POP3 folders, since this is not
        supported by the POP3 protocol.
The callback object's fail
        method gets invoked just prior to this function returning
        NULL, in these kinds of situations.
The application must wait until callback's success or fail method is invoked. The success method is invoked when this request
      is succesfully processed. The fail method is invoked if this request
      cannot be processed. The application must not destroy
      callback until either
      the success or fail method is invoked.
callback's
        fail method may be invoked
        even after other callback methods were invoked. This
        indicates that the request was partially completed before
        the error was encountered.
folder does not
        necessarily have to be a mail::folder object that refers to the
        currently open folder. Any mail::folder object from an active
        mail::account object may be
        used.