1 /* ========================================================================= 2 zchunk - work with memory chunks 3 4 Copyright (c) the Contributors as noted in the AUTHORS file. 5 This file is part of CZMQ, the high-level C binding for 0MQ: 6 http://czmq.zeromq.org. 7 8 This Source Code Form is subject to the terms of the Mozilla Public 9 License, v. 2.0. If a copy of the MPL was not distributed with this 10 file, You can obtain one at http://mozilla.org/MPL/2.0/. 11 ========================================================================= 12 */ 13 14 #ifndef __ZCHUNK_H_INCLUDED__ 15 #define __ZCHUNK_H_INCLUDED__ 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 // @warning THE FOLLOWING @INTERFACE BLOCK IS AUTO-GENERATED BY ZPROJECT 22 // @warning Please edit the model at "api/zchunk.api" to make changes. 23 // @interface 24 // This is a stable class, and may not change except for emergencies. It 25 // is provided in stable builds. 26 // This class has draft methods, which may change over time. They are not 27 // in stable releases, by default. Use --enable-drafts to enable. 28 // Create a new chunk of the specified size. If you specify the data, it 29 // is copied into the chunk. If you do not specify the data, the chunk is 30 // allocated and left empty, and you can then add data using zchunk_append. 31 CZMQ_EXPORT zchunk_t * 32 zchunk_new (const void *data, size_t size); 33 34 // Destroy a chunk 35 CZMQ_EXPORT void 36 zchunk_destroy (zchunk_t **self_p); 37 38 // Resizes chunk max_size as requested; chunk_cur size is set to zero 39 CZMQ_EXPORT void 40 zchunk_resize (zchunk_t *self, size_t size); 41 42 // Return chunk cur size 43 CZMQ_EXPORT size_t 44 zchunk_size (zchunk_t *self); 45 46 // Return chunk max size 47 CZMQ_EXPORT size_t 48 zchunk_max_size (zchunk_t *self); 49 50 // Return chunk data 51 CZMQ_EXPORT byte * 52 zchunk_data (zchunk_t *self); 53 54 // Set chunk data from user-supplied data; truncate if too large. Data may 55 // be null. Returns actual size of chunk 56 CZMQ_EXPORT size_t 57 zchunk_set (zchunk_t *self, const void *data, size_t size); 58 59 // Fill chunk data from user-supplied octet 60 CZMQ_EXPORT size_t 61 zchunk_fill (zchunk_t *self, byte filler, size_t size); 62 63 // Append user-supplied data to chunk, return resulting chunk size. If the 64 // data would exceeded the available space, it is truncated. If you want to 65 // grow the chunk to accommodate new data, use the zchunk_extend method. 66 CZMQ_EXPORT size_t 67 zchunk_append (zchunk_t *self, const void *data, size_t size); 68 69 // Append user-supplied data to chunk, return resulting chunk size. If the 70 // data would exceeded the available space, the chunk grows in size. 71 CZMQ_EXPORT size_t 72 zchunk_extend (zchunk_t *self, const void *data, size_t size); 73 74 // Copy as much data from 'source' into the chunk as possible; returns the 75 // new size of chunk. If all data from 'source' is used, returns exhausted 76 // on the source chunk. Source can be consumed as many times as needed until 77 // it is exhausted. If source was already exhausted, does not change chunk. 78 CZMQ_EXPORT size_t 79 zchunk_consume (zchunk_t *self, zchunk_t *source); 80 81 // Returns true if the chunk was exhausted by consume methods, or if the 82 // chunk has a size of zero. 83 CZMQ_EXPORT bool 84 zchunk_exhausted (zchunk_t *self); 85 86 // Read chunk from an open file descriptor 87 // Caller owns return value and must destroy it when done. 88 CZMQ_EXPORT zchunk_t * 89 zchunk_read (FILE *handle, size_t bytes); 90 91 // Write chunk to an open file descriptor 92 CZMQ_EXPORT int 93 zchunk_write (zchunk_t *self, FILE *handle); 94 95 // Try to slurp an entire file into a chunk. Will read up to maxsize of 96 // the file. If maxsize is 0, will attempt to read the entire file and 97 // fail with an assertion if that cannot fit into memory. Returns a new 98 // chunk containing the file data, or NULL if the file could not be read. 99 // Caller owns return value and must destroy it when done. 100 CZMQ_EXPORT zchunk_t * 101 zchunk_slurp (const char *filename, size_t maxsize); 102 103 // Create copy of chunk, as new chunk object. Returns a fresh zchunk_t 104 // object, or null if there was not enough heap memory. If chunk is null, 105 // returns null. 106 // Caller owns return value and must destroy it when done. 107 CZMQ_EXPORT zchunk_t * 108 zchunk_dup (zchunk_t *self); 109 110 // Return chunk data encoded as printable hex string. Caller must free 111 // string when finished with it. 112 // Caller owns return value and must destroy it when done. 113 CZMQ_EXPORT char * 114 zchunk_strhex (zchunk_t *self); 115 116 // Return chunk data copied into freshly allocated string 117 // Caller must free string when finished with it. 118 // Caller owns return value and must destroy it when done. 119 CZMQ_EXPORT char * 120 zchunk_strdup (zchunk_t *self); 121 122 // Return TRUE if chunk body is equal to string, excluding terminator 123 CZMQ_EXPORT bool 124 zchunk_streq (zchunk_t *self, const char *string); 125 126 // Transform zchunk into a zframe that can be sent in a message. 127 // Caller owns return value and must destroy it when done. 128 CZMQ_EXPORT zframe_t * 129 zchunk_pack (zchunk_t *self); 130 131 // Transform a zframe into a zchunk. 132 // Caller owns return value and must destroy it when done. 133 CZMQ_EXPORT zchunk_t * 134 zchunk_unpack (zframe_t *frame); 135 136 // Calculate SHA1 digest for chunk, using zdigest class. 137 CZMQ_EXPORT const char * 138 zchunk_digest (zchunk_t *self); 139 140 // Dump chunk to FILE stream, for debugging and tracing. 141 CZMQ_EXPORT void 142 zchunk_fprint (zchunk_t *self, FILE *file); 143 144 // Dump message to stderr, for debugging and tracing. 145 // See zchunk_fprint for details 146 CZMQ_EXPORT void 147 zchunk_print (zchunk_t *self); 148 149 // Probe the supplied object, and report if it looks like a zchunk_t. 150 CZMQ_EXPORT bool 151 zchunk_is (void *self); 152 153 // Self test of this class. 154 CZMQ_EXPORT void 155 zchunk_test (bool verbose); 156 157 #ifdef CZMQ_BUILD_DRAFT_API 158 // Destroy an item 159 typedef void (zchunk_destructor_fn) ( 160 void **hint); 161 162 // *** Draft method, for development use, may change without warning *** 163 // Create a new chunk from memory. Take ownership of the memory and calling the destructor 164 // on destroy. 165 CZMQ_EXPORT zchunk_t * 166 zchunk_frommem (void *data, size_t size, zchunk_destructor_fn destructor, void *hint); 167 168 // *** Draft method, for development use, may change without warning *** 169 // Transform zchunk into a zframe that can be sent in a message. 170 // Take ownership of the chunk. 171 // Caller owns return value and must destroy it when done. 172 CZMQ_EXPORT zframe_t * 173 zchunk_packx (zchunk_t **self_p); 174 175 #endif // CZMQ_BUILD_DRAFT_API 176 // @end 177 178 179 #ifdef __cplusplus 180 } 181 #endif 182 183 #endif 184 185