1ZMSG(3) CZMQ Manual ZMSG(3)
2
6 zmsg - Class for working with multipart messages
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // This class has draft methods, which may change over time. They are not
12 // in stable releases, by default. Use --enable-drafts to enable.
13 // Create a new empty message object
14 CZMQ_EXPORT zmsg_t *
15 zmsg_new (void);
16 // Receive message from socket, returns zmsg_t object or NULL if the recv
18 // was interrupted. Does a blocking recv. If you want to not block then use
19 // the zloop class or zmsg_recv_nowait or zmq_poll to check for socket input
20 // before receiving.
21 CZMQ_EXPORT zmsg_t *
22 zmsg_recv (void *source);
23 // Load/append an open file into new message, return the message.
25 // Returns NULL if the message could not be loaded.
26 CZMQ_EXPORT zmsg_t *
27 zmsg_load (FILE *file);
28 // Decodes a serialized message frame created by zmsg_encode () and returns
30 // a new zmsg_t object. Returns NULL if the frame was badly formatted or
31 // there was insufficient memory to work.
32 CZMQ_EXPORT zmsg_t *
33 zmsg_decode (zframe_t *frame);
34 // Generate a signal message encoding the given status. A signal is a short
36 // message carrying a 1-byte success/failure code (by convention, 0 means
37 // OK). Signals are encoded to be distinguishable from "normal" messages.
38 CZMQ_EXPORT zmsg_t *
39 zmsg_new_signal (byte status);
40 // Destroy a message object and all frames it contains
42 CZMQ_EXPORT void
43 zmsg_destroy (zmsg_t **self_p);
44 // Send message to destination socket, and destroy the message after sending
46 // it successfully. If the message has no frames, sends nothing but destroys
47 // the message anyhow. Nullifies the caller's reference to the message (as
48 // it is a destructor).
49 CZMQ_EXPORT int
50 zmsg_send (zmsg_t **self_p, void *dest);
51 // Send message to destination socket as part of a multipart sequence, and
53 // destroy the message after sending it successfully. Note that after a
54 // zmsg_sendm, you must call zmsg_send or another method that sends a final
55 // message part. If the message has no frames, sends nothing but destroys
56 // the message anyhow. Nullifies the caller's reference to the message (as
57 // it is a destructor).
58 CZMQ_EXPORT int
59 zmsg_sendm (zmsg_t **self_p, void *dest);
60 // Return size of message, i.e. number of frames (0 or more).
62 CZMQ_EXPORT size_t
63 zmsg_size (zmsg_t *self);
64 // Return total size of all frames in message.
66 CZMQ_EXPORT size_t
67 zmsg_content_size (zmsg_t *self);
68 // Push frame to the front of the message, i.e. before all other frames.
70 // Message takes ownership of frame, will destroy it when message is sent.
71 // Returns 0 on success, -1 on error. Deprecates zmsg_push, which did not
72 // nullify the caller's frame reference.
73 CZMQ_EXPORT int
74 zmsg_prepend (zmsg_t *self, zframe_t **frame_p);
75 // Add frame to the end of the message, i.e. after all other frames.
77 // Message takes ownership of frame, will destroy it when message is sent.
78 // Returns 0 on success. Deprecates zmsg_add, which did not nullify the
79 // caller's frame reference.
80 CZMQ_EXPORT int
81 zmsg_append (zmsg_t *self, zframe_t **frame_p);
82 // Remove first frame from message, if any. Returns frame, or NULL.
84 // Caller owns return value and must destroy it when done.
85 CZMQ_EXPORT zframe_t *
86 zmsg_pop (zmsg_t *self);
87 // Push block of memory to front of message, as a new frame.
89 // Returns 0 on success, -1 on error.
90 CZMQ_EXPORT int
91 zmsg_pushmem (zmsg_t *self, const void *data, size_t size);
92 // Add block of memory to the end of the message, as a new frame.
94 // Returns 0 on success, -1 on error.
95 CZMQ_EXPORT int
96 zmsg_addmem (zmsg_t *self, const void *data, size_t size);
97 // Push string as new frame to front of message.
99 // Returns 0 on success, -1 on error.
100 CZMQ_EXPORT int
101 zmsg_pushstr (zmsg_t *self, const char *string);
102 // Push string as new frame to end of message.
104 // Returns 0 on success, -1 on error.
105 CZMQ_EXPORT int
106 zmsg_addstr (zmsg_t *self, const char *string);
107 // Push formatted string as new frame to front of message.
109 // Returns 0 on success, -1 on error.
110 CZMQ_EXPORT int
111 zmsg_pushstrf (zmsg_t *self, const char *format, ...) CHECK_PRINTF (2);
112 // Push formatted string as new frame to end of message.
114 // Returns 0 on success, -1 on error.
115 CZMQ_EXPORT int
116 zmsg_addstrf (zmsg_t *self, const char *format, ...) CHECK_PRINTF (2);
117 // Pop frame off front of message, return as fresh string. If there were
119 // no more frames in the message, returns NULL.
120 // Caller owns return value and must destroy it when done.
121 CZMQ_EXPORT char *
122 zmsg_popstr (zmsg_t *self);
123 // Push encoded message as a new frame. Message takes ownership of
125 // submessage, so the original is destroyed in this call. Returns 0 on
126 // success, -1 on error.
127 CZMQ_EXPORT int
128 zmsg_addmsg (zmsg_t *self, zmsg_t **msg_p);
129 // Remove first submessage from message, if any. Returns zmsg_t, or NULL if
131 // decoding was not successful.
132 // Caller owns return value and must destroy it when done.
133 CZMQ_EXPORT zmsg_t *
134 zmsg_popmsg (zmsg_t *self);
135 // Remove specified frame from list, if present. Does not destroy frame.
137 CZMQ_EXPORT void
138 zmsg_remove (zmsg_t *self, zframe_t *frame);
139 // Set cursor to first frame in message. Returns frame, or NULL, if the
141 // message is empty. Use this to navigate the frames as a list.
142 CZMQ_EXPORT zframe_t *
143 zmsg_first (zmsg_t *self);
144 // Return the next frame. If there are no more frames, returns NULL. To move
146 // to the first frame call zmsg_first(). Advances the cursor.
147 CZMQ_EXPORT zframe_t *
148 zmsg_next (zmsg_t *self);
149 // Return the last frame. If there are no frames, returns NULL.
151 CZMQ_EXPORT zframe_t *
152 zmsg_last (zmsg_t *self);
153 // Save message to an open file, return 0 if OK, else -1. The message is
155 // saved as a series of frames, each with length and data. Note that the
156 // file is NOT guaranteed to be portable between operating systems, not
157 // versions of CZMQ. The file format is at present undocumented and liable
158 // to arbitrary change.
159 CZMQ_EXPORT int
160 zmsg_save (zmsg_t *self, FILE *file);
161 // Serialize multipart message to a single message frame. Use this method
163 // to send structured messages across transports that do not support
164 // multipart data. Allocates and returns a new frame containing the
165 // serialized message. To decode a serialized message frame, use
166 // zmsg_decode ().
167 // Caller owns return value and must destroy it when done.
168 CZMQ_EXPORT zframe_t *
169 zmsg_encode (zmsg_t *self);
170 // Create copy of message, as new message object. Returns a fresh zmsg_t
172 // object. If message is null, or memory was exhausted, returns null.
173 // Caller owns return value and must destroy it when done.
174 CZMQ_EXPORT zmsg_t *
175 zmsg_dup (zmsg_t *self);
176 // Send message to zsys log sink (may be stdout, or system facility as
178 // configured by zsys_set_logstream).
179 CZMQ_EXPORT void
180 zmsg_print (zmsg_t *self);
181 // Return true if the two messages have the same number of frames and each
183 // frame in the first message is identical to the corresponding frame in the
184 // other message. As with zframe_eq, return false if either message is NULL.
185 CZMQ_EXPORT bool
186 zmsg_eq (zmsg_t *self, zmsg_t *other);
187 // Return signal value, 0 or greater, if message is a signal, -1 if not.
189 CZMQ_EXPORT int
190 zmsg_signal (zmsg_t *self);
191 // Probe the supplied object, and report if it looks like a zmsg_t.
193 CZMQ_EXPORT bool
194 zmsg_is (void *self);
195 // Self test of this class.
197 CZMQ_EXPORT void
198 zmsg_test (bool verbose);
199 #ifdef CZMQ_BUILD_DRAFT_API
201 // *** Draft method, for development use, may change without warning ***
202 // Return message routing ID, if the message came from a ZMQ_SERVER socket.
203 // Else returns zero.
204 CZMQ_EXPORT uint32_t
205 zmsg_routing_id (zmsg_t *self);
206 // *** Draft method, for development use, may change without warning ***
208 // Set routing ID on message. This is used if/when the message is sent to a
209 // ZMQ_SERVER socket.
210 CZMQ_EXPORT void
211 zmsg_set_routing_id (zmsg_t *self, uint32_t routing_id);
212 #endif // CZMQ_BUILD_DRAFT_API
214 Please add '@interface' section in './../src/zmsg.c'.
215
217 The zmsg class provides methods to send and receive multipart messages
218 across 0MQ sockets. This class provides a list-like container
219 interface, with methods to work with the overall container. zmsg_t
220 messages are composed of zero or more zframe_t frames.
221 Please add @discuss section in ./../src/zmsg.c.
223
225 From zmsg_test method.
226 // Create two PAIR sockets and connect over inproc
228 zsock_t *output = zsock_new_pair ("@inproc://zmsg.test");
229 assert (output);
230 zsock_t *input = zsock_new_pair (">inproc://zmsg.test");
231 assert (input);
232 // Test send and receive of single-frame message
234 zmsg_t *msg = zmsg_new ();
235 assert (msg);
236 zframe_t *frame = zframe_new ("Hello", 5);
237 assert (frame);
238 zmsg_prepend (msg, &frame);
239 assert (zmsg_size (msg) == 1);
240 assert (zmsg_content_size (msg) == 5);
241 rc = zmsg_send (&msg, output);
242 assert (msg == NULL);
243 assert (rc == 0);
244 msg = zmsg_recv (input);
246 assert (msg);
247 assert (zmsg_size (msg) == 1);
248 assert (zmsg_content_size (msg) == 5);
249 zmsg_destroy (&msg);
250 // Test send and receive of multi-frame message
252 msg = zmsg_new ();
253 assert (msg);
254 rc = zmsg_addmem (msg, "Frame0", 6);
255 assert (rc == 0);
256 rc = zmsg_addmem (msg, "Frame1", 6);
257 assert (rc == 0);
258 rc = zmsg_addmem (msg, "Frame2", 6);
259 assert (rc == 0);
260 rc = zmsg_addmem (msg, "Frame3", 6);
261 assert (rc == 0);
262 rc = zmsg_addmem (msg, "Frame4", 6);
263 assert (rc == 0);
264 rc = zmsg_addmem (msg, "Frame5", 6);
265 assert (rc == 0);
266 rc = zmsg_addmem (msg, "Frame6", 6);
267 assert (rc == 0);
268 rc = zmsg_addmem (msg, "Frame7", 6);
269 assert (rc == 0);
270 rc = zmsg_addmem (msg, "Frame8", 6);
271 assert (rc == 0);
272 rc = zmsg_addmem (msg, "Frame9", 6);
273 assert (rc == 0);
274 zmsg_t *copy = zmsg_dup (msg);
275 assert (copy);
276 rc = zmsg_send (©, output);
277 assert (rc == 0);
278 rc = zmsg_send (&msg, output);
279 assert (rc == 0);
280 copy = zmsg_recv (input);
282 assert (copy);
283 assert (zmsg_size (copy) == 10);
284 assert (zmsg_content_size (copy) == 60);
285 zmsg_destroy (©);
286 msg = zmsg_recv (input);
288 assert (msg);
289 assert (zmsg_size (msg) == 10);
290 assert (zmsg_content_size (msg) == 60);
291 // Save to a file, read back
293 FILE *file = fopen ("zmsg.test", "w");
294 assert (file);
295 rc = zmsg_save (msg, file);
296 assert (rc == 0);
297 fclose (file);
298 file = fopen ("zmsg.test", "r");
300 rc = zmsg_save (msg, file);
301 assert (rc == -1);
302 fclose (file);
303 zmsg_destroy (&msg);
304 file = fopen ("zmsg.test", "r");
306 msg = zmsg_load (file);
307 assert (msg);
308 fclose (file);
309 remove ("zmsg.test");
310 assert (zmsg_size (msg) == 10);
311 assert (zmsg_content_size (msg) == 60);
312 // Remove all frames except first and last
314 int frame_nbr;
315 for (frame_nbr = 0; frame_nbr < 8; frame_nbr++) {
316 zmsg_first (msg);
317 frame = zmsg_next (msg);
318 zmsg_remove (msg, frame);
319 zframe_destroy (&frame);
320 }
321 // Test message frame manipulation
322 assert (zmsg_size (msg) == 2);
323 frame = zmsg_last (msg);
324 assert (zframe_streq (frame, "Frame9"));
325 assert (zmsg_content_size (msg) == 12);
326 frame = zframe_new ("Address", 7);
327 assert (frame);
328 zmsg_prepend (msg, &frame);
329 assert (zmsg_size (msg) == 3);
330 rc = zmsg_addstr (msg, "Body");
331 assert (rc == 0);
332 assert (zmsg_size (msg) == 4);
333 frame = zmsg_pop (msg);
334 zframe_destroy (&frame);
335 assert (zmsg_size (msg) == 3);
336 char *body = zmsg_popstr (msg);
337 assert (streq (body, "Frame0"));
338 freen (body);
339 zmsg_destroy (&msg);
340 // Test encoding/decoding
342 msg = zmsg_new ();
343 assert (msg);
344 byte *blank = (byte *) zmalloc (100000);
345 assert (blank);
346 rc = zmsg_addmem (msg, blank, 0);
347 assert (rc == 0);
348 rc = zmsg_addmem (msg, blank, 1);
349 assert (rc == 0);
350 rc = zmsg_addmem (msg, blank, 253);
351 assert (rc == 0);
352 rc = zmsg_addmem (msg, blank, 254);
353 assert (rc == 0);
354 rc = zmsg_addmem (msg, blank, 255);
355 assert (rc == 0);
356 rc = zmsg_addmem (msg, blank, 256);
357 assert (rc == 0);
358 rc = zmsg_addmem (msg, blank, 65535);
359 assert (rc == 0);
360 rc = zmsg_addmem (msg, blank, 65536);
361 assert (rc == 0);
362 rc = zmsg_addmem (msg, blank, 65537);
363 assert (rc == 0);
364 freen (blank);
365 assert (zmsg_size (msg) == 9);
366 frame = zmsg_encode (msg);
367 zmsg_destroy (&msg);
368 msg = zmsg_decode (frame);
369 assert (msg);
370 zmsg_destroy (&msg);
371 zframe_destroy (&frame);
372 // Test submessages
374 msg = zmsg_new ();
375 assert (msg);
376 zmsg_t *submsg = zmsg_new ();
377 zmsg_pushstr (msg, "matr");
378 zmsg_pushstr (submsg, "joska");
379 rc = zmsg_addmsg (msg, &submsg);
380 assert (rc == 0);
381 assert (submsg == NULL);
382 submsg = zmsg_popmsg (msg);
383 assert (submsg == NULL); // string "matr" is not encoded zmsg_t, so was discarded
384 submsg = zmsg_popmsg (msg);
385 assert (submsg);
386 body = zmsg_popstr (submsg);
387 assert (streq (body, "joska"));
388 freen (body);
389 zmsg_destroy (&submsg);
390 frame = zmsg_pop (msg);
391 assert (frame == NULL);
392 zmsg_destroy (&msg);
393 // Test comparison of two messages
395 msg = zmsg_new ();
396 zmsg_addstr (msg, "One");
397 zmsg_addstr (msg, "Two");
398 zmsg_addstr (msg, "Three");
399 zmsg_t *msg_other = zmsg_new ();
400 zmsg_addstr (msg_other, "One");
401 zmsg_addstr (msg_other, "Two");
402 zmsg_addstr (msg_other, "One-Hundred");
403 zmsg_t *msg_dup = zmsg_dup (msg);
404 zmsg_t *empty_msg = zmsg_new ();
405 zmsg_t *empty_msg_2 = zmsg_new ();
406 assert (zmsg_eq (msg, msg_dup));
407 assert (!zmsg_eq (msg, msg_other));
408 assert (zmsg_eq (empty_msg, empty_msg_2));
409 assert (!zmsg_eq (msg, NULL));
410 assert (!zmsg_eq (NULL, empty_msg));
411 assert (!zmsg_eq (NULL, NULL));
412 zmsg_destroy (&msg);
413 zmsg_destroy (&msg_other);
414 zmsg_destroy (&msg_dup);
415 zmsg_destroy (&empty_msg);
416 zmsg_destroy (&empty_msg_2);
417 // Test signal messages
419 msg = zmsg_new_signal (0);
420 assert (zmsg_signal (msg) == 0);
421 zmsg_destroy (&msg);
422 msg = zmsg_new_signal (-1);
423 assert (zmsg_signal (msg) == 255);
424 zmsg_destroy (&msg);
425 // Now try methods on an empty message
427 msg = zmsg_new ();
428 assert (msg);
429 assert (zmsg_size (msg) == 0);
430 assert (zmsg_unwrap (msg) == NULL);
431 assert (zmsg_first (msg) == NULL);
432 assert (zmsg_last (msg) == NULL);
433 assert (zmsg_next (msg) == NULL);
434 assert (zmsg_pop (msg) == NULL);
435 // Sending an empty message is valid and destroys the message
436 assert (zmsg_send (&msg, output) == 0);
437 assert (!msg);
438 zsock_destroy (&input);
440 zsock_destroy (&output);
441 #if defined (ZMQ_SERVER)
443 // Create server and client sockets and connect over inproc
444 zsock_t *server = zsock_new_server ("inproc://zmsg-test-routing");
445 assert (server);
446 zsock_t *client = zsock_new_client ("inproc://zmsg-test-routing");
447 assert (client);
448 // Send request from client to server
450 zmsg_t *request = zmsg_new ();
451 assert (request);
452 zmsg_addstr (request, "Hello");
453 rc = zmsg_send (&request, client);
454 assert (rc == 0);
455 assert (!request);
456 // Read request and send reply
458 request = zmsg_recv (server);
459 assert (request);
460 char *string = zmsg_popstr (request);
461 assert (streq (string, "Hello"));
462 assert (zmsg_routing_id (request));
463 zstr_free (&string);
464 zmsg_t *reply = zmsg_new ();
466 assert (reply);
467 zmsg_addstr (reply, "World");
468 zmsg_set_routing_id (reply, zmsg_routing_id (request));
469 rc = zmsg_send (&reply, server);
470 assert (rc == 0);
471 zmsg_destroy (&request);
472 // Read reply
474 reply = zmsg_recv (client);
475 string = zmsg_popstr (reply);
476 assert (streq (string, "World"));
477 assert (zmsg_routing_id (reply) == 0);
478 zmsg_destroy (&reply);
479 zstr_free (&string);
480 // Client and server disallow multipart
482 msg = zmsg_new ();
483 zmsg_addstr (msg, "One");
484 zmsg_addstr (msg, "Two");
485 rc = zmsg_send (&msg, client);
486 assert (rc == -1);
487 assert (zmsg_size (msg) == 2);
488 rc = zmsg_send (&msg, server);
489 assert (rc == -1);
490 assert (zmsg_size (msg) == 2);
491 zmsg_destroy (&msg);
492 zsock_destroy (&client);
494 zsock_destroy (&server);
495 #endif
496 // Test message length calculation after removal
498 msg = zmsg_new ();
499 zmsg_addstr (msg, "One");
500 zmsg_addstr (msg, "Two");
501 size_t size_before = zmsg_content_size (msg);
502 frame = zframe_new ("Three", strlen ("Three"));
503 assert (frame);
504 zmsg_remove (msg, frame);
505 size_t size_after = zmsg_content_size (msg);
506 assert (size_before == size_after);
507 zframe_destroy (&frame);
508 zmsg_destroy (&msg);
509 #if defined (__WINDOWS__)
511 zsys_shutdown();
512 #endif
513
516 The czmq manual was written by the authors in the AUTHORS file.
517
519 Main web site:
520 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
522
524 Copyright (c) the Contributors as noted in the AUTHORS file. This file
525 is part of CZMQ, the high-level C binding for 0MQ:
526 http://czmq.zeromq.org. This Source Code Form is subject to the terms
527 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
528 distributed with this file, You can obtain one at
529 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
530 distribution.
531
533 1. zeromq-dev@lists.zeromq.org
534 mailto:zeromq-dev@lists.zeromq.org
535CZMQ 4.1.1 07/24/2019 ZMSG(3)