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