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