src/bloblist.h
author Neal H. Walfield <neal@pep.foundation>
Wed, 08 May 2019 12:20:37 +0200
branchemail_comparison
changeset 3649 1dd837adc30b
parent 2462 48b526a0daac
child 3965 9a59d1fa3d09
permissions -rw-r--r--
Fix public key.
     1 // This file is under GNU General Public License 3.0
     2 // see LICENSE.txt
     3 
     4 #pragma once
     5 
     6 #include "dynamic_api.h"
     7 #include "stringpair.h"
     8 
     9 #ifdef __cplusplus
    10 extern "C" {
    11 #endif
    12 
    13 typedef enum {
    14     PEP_CONTENT_DISP_ATTACHMENT = 0,
    15     PEP_CONTENT_DISP_INLINE = 1,
    16     PEP_CONTENT_DISP_OTHER = -1      // must be affirmatively set
    17 } content_disposition_type;
    18 
    19 typedef struct _bloblist_t {
    20     char *value;                        // blob
    21     size_t size;                        // size of blob
    22     char *mime_type;                    // UTF-8 string of MIME type of blob or
    23                                         // NULL if unknown
    24     char *filename;                     // UTF-8 string of file name of blob or
    25                                         // NULL if unknown
    26     content_disposition_type disposition;
    27                                         // default is attachment when allocated
    28                                         // (see mime.h and RFC2183)
    29     struct _bloblist_t *next;           // this is a single linked list
    30     void (*release_value)(char *);      // pointer to release function;
    31                                         // pEp_free() if not set
    32 } bloblist_t;
    33 
    34 
    35 // new_bloblist() - allocate a new bloblist
    36 //
    37 //  parameters:
    38 //      blob (in)       blob to add to the list
    39 //      size (in)       size of the blob
    40 //      mime_type (in)  MIME type of the blob data or NULL if unknown
    41 //      filename (in)  file name of origin of blob data or NULL if unknown
    42 //
    43 //  return value:
    44 //      pointer to new bloblist_t or NULL if out of memory
    45 //
    46 //  caveat:
    47 //      the ownership of the blob goes to the bloblist; mime_type and filename
    48 //      are being copied, the originals remain in the ownership of the caller
    49 //
    50 //      if blob is on a different heap then after the call release_value has to
    51 //      be set by the adapter; this is relevant on operating systems with
    52 //      multiple heaps like Microsoft Windows
    53 
    54 DYNAMIC_API bloblist_t *new_bloblist(char *blob, size_t size, const char *mime_type,
    55         const char *filename);
    56 
    57 
    58 // free_bloblist() - free bloblist
    59 //
    60 //  parameters:
    61 //      bloblist (in)   bloblist to free
    62 
    63 DYNAMIC_API void free_bloblist(bloblist_t *bloblist);
    64 
    65 
    66 // bloblist_dup() - duplicate bloblist
    67 //
    68 //  parameters:
    69 //      src (in)    bloblist to duplicate
    70 //
    71 //  return value:
    72 //      pointer to a new bloblist_t or NULL if out of memory
    73 //
    74 //  caveat:
    75 //      this is an expensive operation because all blobs are copied
    76 
    77 DYNAMIC_API bloblist_t *bloblist_dup(const bloblist_t *src);
    78 
    79 
    80 // bloblist_add() - add reference to a blob to bloblist
    81 //
    82 //  parameters:
    83 //      bloblist (in)   bloblist to add to
    84 //      blob (in)       blob
    85 //      size (in)       size of the blob
    86 //      mime_type (in)  MIME type of the blob or NULL if unknown
    87 //      filename (in)  file name of the blob or NULL if unknown
    88 //
    89 //  return value:
    90 //      pointer to the last element of bloblist or NULL if out of memory or
    91 //      NULL passed in as blob value
    92 //
    93 //  caveat:
    94 //      the ownership of the blob goes to the bloblist; mime_type and filename
    95 //      are being copied, the originals remain in the ownership of the caller.
    96 //      bloblist input parameter equal to NULL or with value == NULL is a valid
    97 //      empty input list.
    98 //
    99 //      If there is release_value set in bloblist it is copied to the added
   100 //      leaf
   101 
   102 DYNAMIC_API bloblist_t *bloblist_add(bloblist_t *bloblist, char *blob, size_t size,
   103         const char *mime_type, const char *filename);
   104 
   105 
   106 // bloblist_length() - get length of bloblist
   107 //
   108 //  parameters:
   109 //      bloblist (in)   bloblist struct to determine length of
   110 //
   111 //  return value:
   112 //      length of bloblist in number of elements
   113 
   114 DYNAMIC_API int bloblist_length(const bloblist_t *bloblist);
   115 
   116 
   117 // set_blob_content_disposition() - set blob content disposition and parameters
   118 //                                  when necessary
   119 //
   120 //  parameters:
   121 //      blob (in)               bloblist struct to change disposition for
   122 //      disposition (in)        disposition type (see enum)
   123 
   124 DYNAMIC_API void set_blob_disposition(bloblist_t* blob, 
   125         content_disposition_type disposition);
   126 
   127 
   128 #ifdef __cplusplus
   129 }
   130 #endif