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 CZMQ_EXPORT void 119 zframe_print (zframe_t *self, const char *prefix); 120 121 // Probe the supplied object, and report if it looks like a zframe_t. 122 CZMQ_EXPORT bool 123 zframe_is (void *self); 124 125 // Self test of this class. 126 CZMQ_EXPORT void 127 zframe_test (bool verbose); 128 129 #ifdef CZMQ_BUILD_DRAFT_API 130 // *** Draft method, for development use, may change without warning *** 131 // Return frame routing ID, if the frame came from a ZMQ_SERVER socket. 132 // Else returns zero. 133 CZMQ_EXPORT uint32_t 134 zframe_routing_id (zframe_t *self); 135 136 // *** Draft method, for development use, may change without warning *** 137 // Set routing ID on frame. This is used if/when the frame is sent to a 138 // ZMQ_SERVER socket. 139 CZMQ_EXPORT void 140 zframe_set_routing_id (zframe_t *self, uint32_t routing_id); 141 142 // *** Draft method, for development use, may change without warning *** 143 // Return frame group of radio-dish pattern. 144 CZMQ_EXPORT const char * 145 zframe_group (zframe_t *self); 146 147 // *** Draft method, for development use, may change without warning *** 148 // Set group on frame. This is used if/when the frame is sent to a 149 // ZMQ_RADIO socket. 150 // Return -1 on error, 0 on success. 151 CZMQ_EXPORT int 152 zframe_set_group (zframe_t *self, const char *group); 153 154 #endif // CZMQ_BUILD_DRAFT_API 155 // @end 156 157 158 // DEPRECATED as poor style -- callers should use zloop or zpoller 159 // Receive a new frame off the socket. Returns newly allocated frame, or 160 // NULL if there was no input waiting, or if the read was interrupted. 161 CZMQ_EXPORT zframe_t * 162 zframe_recv_nowait (void *source); 163 164 // DEPRECATED as inconsistent; breaks principle that logging should all go 165 // to a single destination. 166 // Print contents of the frame to FILE stream. 167 CZMQ_EXPORT void 168 zframe_fprint (zframe_t *self, const char *prefix, FILE *file); 169 170 // Deprecated method aliases 171 #define zframe_print_to_stream(s,p,F) zframe_fprint(s,p,F) 172 173 #ifdef __cplusplus 174 } 175 #endif 176 177 #endif 178