src/mime.h
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Wed, 27 Jan 2021 17:13:24 +0100
branchmime-integrate
changeset 5281 2eeac2d5d012
parent 5237 0d3fd1083cbb
permissions -rw-r--r--
push before migration
     1 /**
     2  * @file    mime.h
     3  * @brief   mime functionality as produced/consumed by the engine. This is the interface to the engine's
     4  *          use of the underlying MIME parser
     5  * @license GNU General Public License 3.0 - see LICENSE.txt
     6  */
     7 
     8 #ifndef MIME_H
     9 #define MIME_H
    10 
    11 #include "message.h"
    12 
    13 #ifdef __cplusplus
    14 extern "C" {
    15 #endif
    16 
    17 /**
    18  *  <!--       is_PGP_message_text()       -->
    19  *  
    20  *  @brief Determine if text encodes a PGP message
    21  *  
    22  *  @param[in]   text    text to examine
    23  *  
    24  *  @retval true if text is a PGP message, false otherwise
    25  *  
    26  *  
    27  */
    28 
    29 DYNAMIC_API bool is_PGP_message_text(const char *text);
    30 
    31 
    32 /**
    33  *  <!--       mime_encode_message()       -->
    34  *  
    35  *  @brief Encode a MIME message
    36  *  
    37  *  @param[in]   msg                       message to encode
    38  *  @param[in]   omit_fields               only encode message body and
    39  *                                           attachments
    40  *  @param[out]    mimetext                  the resulting encoded text or 
    41  *                                           NULL on any error
    42  *  @param[in]   has_pEp_msg_attachment    is the first *attachment* to this
    43  *                                           message an embedded pEp message
    44  *                                           which needs appropriate marking
    45  *                                           (forwarded=no, etc) and encoding?
    46  *                                           (this argument is internal to 
    47  *                                           pEp and should almost
    48  *                                           ALWAYS be false when used 
    49  *                                           by external callers, including
    50  *                                           adapters!!!)
    51  *  
    52  *  @retval PEP_STATUS_OK           if everything worked
    53  *  @retval PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
    54  *  @retval PEP_CANNOT_CREATE_TEMP_FILE
    55  *  @retval if there are issues with temp files; in
    56  *  @retval this case errno will contain the underlying
    57  *  @retval error
    58  *  @retval PEP_OUT_OF_MEMORY       if not enough memory could be allocated
    59  *  
    60  *  @warning the resulttext will go to the ownership of the caller
    61  *           the message will remain in the ownership of the caller
    62  *           omit_fields is true for payload of PGP/MIME messages
    63  *           also: note that the encryption type will be used to determine what
    64  *           gets encoded from the message struct, so if using this on an 
    65  *           already-encrypted message, set the enc_format of the msg to PEP_enc_none.
    66  *  
    67  */
    68 
    69 DYNAMIC_API PEP_STATUS mime_encode_message(
    70         const message * msg,
    71         bool omit_fields,
    72         char **mimetext,
    73         bool has_pEp_msg_attachment     
    74     );
    75 
    76 
    77 /**
    78  *  <!--       mime_decode_message()       -->
    79  *  
    80  *  @brief Decode a MIME message
    81  *  
    82  *  @param[in]     mimetext                MIME encoded text to decode
    83  *  @param[in]     size                    size of text to decode
    84  *  @param[out]    msg                     decoded message
    85  *  @param[in,out] has_possible_pEp_msg    If non-NULL, will return 
    86  *                                         true when the first attachment 
    87  *                                         is a potential pEp message
    88  *                                         (mime-type = message/rfc822 and 
    89  *                                         content-disposition parameter
    90  *                                         forwarded=no) 
    91  *  
    92  *  @retval PEP_STATUS_OK           if everything worked
    93  *  @retval PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
    94  *  @retval PEP_CANNOT_CREATE_TEMP_FILE
    95  *  @retval if there are issues with temp files; in
    96  *  @retval this case errno will contain the underlying
    97  *  @retval error
    98  *  @retval PEP_OUT_OF_MEMORY       if not enough memory could be allocated
    99  *  
   100  *  @warning the decoded message will go to the ownership of the caller; mimetext
   101  *           will remain in the ownership of the caller
   102  *  
   103  */
   104 
   105 DYNAMIC_API PEP_STATUS mime_decode_message(
   106         const char *mimetext,
   107         size_t size,
   108         message **msg,
   109         bool* has_possible_pEp_msg
   110     );
   111 
   112 #ifdef __cplusplus
   113 }
   114 #endif
   115 
   116 #endif