1 /* ========================================================================= 2 zframe - working with single message frames 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 __ZFRAME_H_INCLUDED__ 15 #define __ZFRAME_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/zframe.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 #define ZFRAME_MORE 1 // 29 #define ZFRAME_REUSE 2 // 30 #define ZFRAME_DONTWAIT 4 // 31 32 // Create a new frame. If size is not null, allocates the frame data 33 // to the specified size. If additionally, data is not null, copies 34 // size octets from the specified data into the frame body. 35 CZMQ_EXPORT zframe_t * 36 zframe_new (const void *data, size_t size); 37 38 // Create an empty (zero-sized) frame 39 CZMQ_EXPORT zframe_t * 40 zframe_new_empty (void); 41 42 // Create a frame with a specified string content. 43 CZMQ_EXPORT zframe_t * 44 zframe_from (const char *string); 45 46 // Receive frame from socket, returns zframe_t object or NULL if the recv 47 // was interrupted. Does a blocking recv, if you want to not block then use 48 // zpoller or zloop. 49 CZMQ_EXPORT zframe_t * 50 zframe_recv (void *source); 51 52 // Destroy a frame 53 CZMQ_EXPORT void 54 zframe_destroy (zframe_t **self_p); 55 56 // Send a frame to a socket, destroy frame after sending. 57 // Return -1 on error, 0 on success. 58 CZMQ_EXPORT int 59 zframe_send (zframe_t **self_p, void *dest, int flags); 60 61 // Return number of bytes in frame data 62 CZMQ_EXPORT size_t 63 zframe_size (zframe_t *self); 64 65 // Return address of frame data 66 CZMQ_EXPORT byte * 67 zframe_data (zframe_t *self); 68 69 // Return meta data property for frame 70 // The caller shall not modify or free the returned value, which shall be 71 // owned by the message. 72 CZMQ_EXPORT const char * 73 zframe_meta (zframe_t *self, const char *property); 74 75 // Create a new frame that duplicates an existing frame. If frame is null, 76 // or memory was exhausted, returns null. 77 // Caller owns return value and must destroy it when done. 78 CZMQ_EXPORT zframe_t * 79 zframe_dup (zframe_t *self); 80 81 // Return frame data encoded as printable hex string, useful for 0MQ UUIDs. 82 // Caller must free string when finished with it. 83 // Caller owns return value and must destroy it when done. 84 CZMQ_EXPORT char * 85 zframe_strhex (zframe_t *self); 86 87 // Return frame data copied into freshly allocated string 88 // Caller must free string when finished with it. 89 // Caller owns return value and must destroy it when done. 90 CZMQ_EXPORT char * 91 zframe_strdup (zframe_t *self); 92 93 // Return TRUE if frame body is equal to string, excluding terminator 94 CZMQ_EXPORT bool 95 zframe_streq (zframe_t *self, const char *string); 96 97 // Return frame MORE indicator (1 or 0), set when reading frame from socket 98 // or by the zframe_set_more() method 99 CZMQ_EXPORT int 100 zframe_more (zframe_t *self); 101 102 // Set frame MORE indicator (1 or 0). Note this is NOT used when sending 103 // frame to socket, you have to specify flag explicitly. 104 CZMQ_EXPORT void 105 zframe_set_more (zframe_t *self, int more); 106 107 // Return TRUE if two frames have identical size and data 108 // If either frame is NULL, equality is always false. 109 CZMQ_EXPORT bool 110 zframe_eq (zframe_t *self, zframe_t *other); 111 112 // Set new contents for frame 113 CZMQ_EXPORT void 114 zframe_reset (zframe_t *self, const void *data, size_t size); 115 116 // Send message to zsys log sink (may be stdout, or system facility as 117 // configured by zsys_set_logstream). Prefix shows before frame, if not null. 118 // Long messages are truncated. 119 CZMQ_EXPORT void 120 zframe_print (zframe_t *self, const char *prefix); 121 122 // Probe the supplied object, and report if it looks like a zframe_t. 123 CZMQ_EXPORT bool 124 zframe_is (void *self); 125 126 // Self test of this class. 127 CZMQ_EXPORT void 128 zframe_test (bool verbose); 129 130 #ifdef CZMQ_BUILD_DRAFT_API 131 // Destroy an item 132 typedef void (zframe_destructor_fn) ( 133 void **hint); 134 135 // *** Draft method, for development use, may change without warning *** 136 // Create a new frame from memory. Take ownership of the memory and calling the destructor 137 // on destroy. 138 CZMQ_EXPORT zframe_t * 139 zframe_frommem (void *data, size_t size, zframe_destructor_fn destructor, void *hint); 140 141 // *** Draft method, for development use, may change without warning *** 142 // Return frame routing ID, if the frame came from a ZMQ_SERVER socket. 143 // Else returns zero. 144 CZMQ_EXPORT uint32_t 145 zframe_routing_id (zframe_t *self); 146 147 // *** Draft method, for development use, may change without warning *** 148 // Set routing ID on frame. This is used if/when the frame is sent to a 149 // ZMQ_SERVER socket. 150 CZMQ_EXPORT void 151 zframe_set_routing_id (zframe_t *self, uint32_t routing_id); 152 153 // *** Draft method, for development use, may change without warning *** 154 // Return frame group of radio-dish pattern. 155 CZMQ_EXPORT const char * 156 zframe_group (zframe_t *self); 157 158 // *** Draft method, for development use, may change without warning *** 159 // Set group on frame. This is used if/when the frame is sent to a 160 // ZMQ_RADIO socket. 161 // Return -1 on error, 0 on success. 162 CZMQ_EXPORT int 163 zframe_set_group (zframe_t *self, const char *group); 164 165 // *** Draft method, for development use, may change without warning *** 166 // Send message to zsys log sink (may be stdout, or system facility as 167 // configured by zsys_set_logstream). Prefix shows before frame, if not null. 168 // Message length is specified; no truncation unless length is zero. 169 // Backwards compatible with zframe_print when length is zero. 170 CZMQ_EXPORT void 171 zframe_print_n (zframe_t *self, const char *prefix, size_t length); 172 173 #endif // CZMQ_BUILD_DRAFT_API 174 // @end 175 176 177 // DEPRECATED as poor style -- callers should use zloop or zpoller 178 // Receive a new frame off the socket. Returns newly allocated frame, or 179 // NULL if there was no input waiting, or if the read was interrupted. 180 CZMQ_EXPORT zframe_t * 181 zframe_recv_nowait (void *source); 182 183 // DEPRECATED as inconsistent; breaks principle that logging should all go 184 // to a single destination. 185 // Print contents of the frame to FILE stream. 186 CZMQ_EXPORT void 187 zframe_fprint (zframe_t *self, const char *prefix, FILE *file); 188 189 // Deprecated method aliases 190 #define zframe_print_to_stream(s,p,F) zframe_fprint(s,p,F) 191 192 #ifdef __cplusplus 193 } 194 #endif 195 196 #endif 197