1 #ifndef MUPDF_FITZ_BUFFER_H 2 #define MUPDF_FITZ_BUFFER_H 3 4 #include "mupdf/fitz/system.h" 5 #include "mupdf/fitz/context.h" 6 7 /** 8 fz_buffer is a wrapper around a dynamically allocated array of 9 bytes. 10 11 Buffers have a capacity (the number of bytes storage immediately 12 available) and a current size. 13 14 The contents of the structure are considered implementation 15 details and are subject to change. Users should use the accessor 16 functions in preference. 17 */ 18 typedef struct 19 { 20 int refs; 21 unsigned char *data; 22 size_t cap, len; 23 int unused_bits; 24 int shared; 25 } fz_buffer; 26 27 /** 28 Take an additional reference to the buffer. The same pointer 29 is returned. 30 31 Never throws exceptions. 32 */ 33 fz_buffer *fz_keep_buffer(fz_context *ctx, fz_buffer *buf); 34 35 /** 36 Drop a reference to the buffer. When the reference count reaches 37 zero, the buffer is destroyed. 38 39 Never throws exceptions. 40 */ 41 void fz_drop_buffer(fz_context *ctx, fz_buffer *buf); 42 43 /** 44 Retrieve internal memory of buffer. 45 46 datap: Output parameter that will be pointed to the data. 47 48 Returns the current size of the data in bytes. 49 */ 50 size_t fz_buffer_storage(fz_context *ctx, fz_buffer *buf, unsigned char **datap); 51 52 /** 53 Ensure that a buffer's data ends in a 54 0 byte, and return a pointer to it. 55 */ 56 const char *fz_string_from_buffer(fz_context *ctx, fz_buffer *buf); 57 58 fz_buffer *fz_new_buffer(fz_context *ctx, size_t capacity); 59 60 /** 61 Create a new buffer with existing data. 62 63 data: Pointer to existing data. 64 size: Size of existing data. 65 66 Takes ownership of data. Does not make a copy. Calls fz_free on 67 the data when the buffer is deallocated. Do not use 'data' after 68 passing to this function. 69 70 Returns pointer to new buffer. Throws exception on allocation 71 failure. 72 */ 73 fz_buffer *fz_new_buffer_from_data(fz_context *ctx, unsigned char *data, size_t size); 74 75 /** 76 Like fz_new_buffer, but does not take ownership. 77 */ 78 fz_buffer *fz_new_buffer_from_shared_data(fz_context *ctx, const unsigned char *data, size_t size); 79 80 /** 81 Create a new buffer containing a copy of the passed data. 82 */ 83 fz_buffer *fz_new_buffer_from_copied_data(fz_context *ctx, const unsigned char *data, size_t size); 84 85 /** 86 Create a new buffer with data decoded from a base64 input string. 87 */ 88 fz_buffer *fz_new_buffer_from_base64(fz_context *ctx, const char *data, size_t size); 89 90 /** 91 Ensure that a buffer has a given capacity, 92 truncating data if required. 93 94 capacity: The desired capacity for the buffer. If the current 95 size of the buffer contents is smaller than capacity, it is 96 truncated. 97 */ 98 void fz_resize_buffer(fz_context *ctx, fz_buffer *buf, size_t capacity); 99 100 /** 101 Make some space within a buffer (i.e. ensure that 102 capacity > size). 103 */ 104 void fz_grow_buffer(fz_context *ctx, fz_buffer *buf); 105 106 /** 107 Trim wasted capacity from a buffer by resizing internal memory. 108 */ 109 void fz_trim_buffer(fz_context *ctx, fz_buffer *buf); 110 111 /** 112 Empties the buffer. Storage is not freed, but is held ready 113 to be reused as the buffer is refilled. 114 115 Never throws exceptions. 116 */ 117 void fz_clear_buffer(fz_context *ctx, fz_buffer *buf); 118 119 /** 120 Append the contents of the source buffer onto the end of the 121 destination buffer, extending automatically as required. 122 123 Ownership of buffers does not change. 124 */ 125 void fz_append_buffer(fz_context *ctx, fz_buffer *destination, fz_buffer *source); 126 127 /** 128 fz_append_*: Append data to a buffer. 129 130 The buffer will automatically grow as required. 131 */ 132 void fz_append_data(fz_context *ctx, fz_buffer *buf, const void *data, size_t len); 133 void fz_append_string(fz_context *ctx, fz_buffer *buf, const char *data); 134 void fz_append_byte(fz_context *ctx, fz_buffer *buf, int c); 135 void fz_append_rune(fz_context *ctx, fz_buffer *buf, int c); 136 void fz_append_int32_le(fz_context *ctx, fz_buffer *buf, int x); 137 void fz_append_int16_le(fz_context *ctx, fz_buffer *buf, int x); 138 void fz_append_int32_be(fz_context *ctx, fz_buffer *buf, int x); 139 void fz_append_int16_be(fz_context *ctx, fz_buffer *buf, int x); 140 void fz_append_bits(fz_context *ctx, fz_buffer *buf, int value, int count); 141 void fz_append_bits_pad(fz_context *ctx, fz_buffer *buf); 142 143 /** 144 fz_append_pdf_string: Append a string with PDF syntax quotes and 145 escapes. 146 147 The buffer will automatically grow as required. 148 */ 149 void fz_append_pdf_string(fz_context *ctx, fz_buffer *buffer, const char *text); 150 151 /** 152 fz_append_printf: Format and append data to buffer using 153 printf-like formatting (see fz_vsnprintf). 154 155 The buffer will automatically grow as required. 156 */ 157 void fz_append_printf(fz_context *ctx, fz_buffer *buffer, const char *fmt, ...); 158 159 /** 160 fz_append_vprintf: Format and append data to buffer using 161 printf-like formatting with varargs (see fz_vsnprintf). 162 */ 163 void fz_append_vprintf(fz_context *ctx, fz_buffer *buffer, const char *fmt, va_list args); 164 165 /** 166 Zero-terminate buffer in order to use as a C string. 167 168 This byte is invisible and does not affect the length of the 169 buffer as returned by fz_buffer_storage. The zero byte is 170 written *after* the data, and subsequent writes will overwrite 171 the terminating byte. 172 173 Subsequent changes to the size of the buffer (such as by 174 fz_buffer_trim, fz_buffer_grow, fz_resize_buffer, etc) may 175 invalidate this. 176 */ 177 void fz_terminate_buffer(fz_context *ctx, fz_buffer *buf); 178 179 /** 180 Create an MD5 digest from buffer contents. 181 182 Never throws exceptions. 183 */ 184 void fz_md5_buffer(fz_context *ctx, fz_buffer *buffer, unsigned char digest[16]); 185 186 /** 187 Take ownership of buffer contents. 188 189 Performs the same task as fz_buffer_storage, but ownership of 190 the data buffer returns with this call. The buffer is left 191 empty. 192 193 Note: Bad things may happen if this is called on a buffer with 194 multiple references that is being used from multiple threads. 195 196 data: Pointer to place to retrieve data pointer. 197 198 Returns length of stream. 199 */ 200 size_t fz_buffer_extract(fz_context *ctx, fz_buffer *buf, unsigned char **data); 201 202 #endif 203