zmsg(3)

zmsg(3)

CZMQ Manual - CZMQ/1.4.1

Name

zmsg - working with multipart messages

Synopsis

//  Create a new empty message object
CZMQ_EXPORT zmsg_t *
    zmsg_new (void);

//  Destroy a message object and all frames it contains
CZMQ_EXPORT void
    zmsg_destroy (zmsg_t **self_p);

//  Read 1 or more frames off the socket, into a new message object
CZMQ_EXPORT zmsg_t *
    zmsg_recv (void *socket);

//  Send a message to the socket, and then destroy it
CZMQ_EXPORT int
    zmsg_send (zmsg_t **self_p, void *socket);

//  Return number of frames in message
CZMQ_EXPORT size_t
    zmsg_size (zmsg_t *self);

//  Return combined size of all frames in message
CZMQ_EXPORT size_t
    zmsg_content_size (zmsg_t *self);

//  Push frame to front of message, before first frame
CZMQ_EXPORT int
    zmsg_push (zmsg_t *self, zframe_t *frame);

//  Pop frame off front of message, caller now owns frame
CZMQ_EXPORT zframe_t *
    zmsg_pop (zmsg_t *self);

//  Add frame to end of message, after last frame
CZMQ_EXPORT int
    zmsg_add (zmsg_t *self, zframe_t *frame);

//  Push block of memory as new frame to front of message.
//  Returns 0 on success, -1 on error.
CZMQ_EXPORT int
    zmsg_pushmem (zmsg_t *self, const void *src, size_t size);

//  Push block of memory as new frame to end of message.
//  Returns 0 on success, -1 on error.
CZMQ_EXPORT int
    zmsg_addmem (zmsg_t *self, const void *src, size_t size);

//  Push string as new frame to front of message.
//  Returns 0 on success, -1 on error.
CZMQ_EXPORT int
    zmsg_pushstr (zmsg_t *self, const char *format, ...);

//  Push string as new frame to end of message.
//  Returns 0 on success, -1 on error.
CZMQ_EXPORT int
    zmsg_addstr (zmsg_t *self, const char *format, ...);

//  Pop frame off front of message, return as fresh string
CZMQ_EXPORT char *
    zmsg_popstr (zmsg_t *self);

//  Push frame to front of message, before first frame
//  Pushes an empty frame in front of frame
CZMQ_EXPORT void
    zmsg_wrap (zmsg_t *self, zframe_t *frame);

//  Pop frame off front of message, caller now owns frame
//  If next frame is empty, pops and destroys that empty frame.
CZMQ_EXPORT zframe_t *
    zmsg_unwrap (zmsg_t *self);

//  Remove frame from message, at any position, caller owns it
CZMQ_EXPORT void
    zmsg_remove (zmsg_t *self, zframe_t *frame);

//  Return first frame in message, or null
CZMQ_EXPORT zframe_t *
    zmsg_first (zmsg_t *self);

//  Return next frame in message, or null
CZMQ_EXPORT zframe_t *
    zmsg_next (zmsg_t *self);

//  Return last frame in message, or null
CZMQ_EXPORT zframe_t *
    zmsg_last (zmsg_t *self);

//  Save message to an open file, return 0 if OK, else -1.
CZMQ_EXPORT int
    zmsg_save (zmsg_t *self, FILE *file);

//  Load/append an open file into message, create new message if
//  null message provided.
CZMQ_EXPORT zmsg_t *
    zmsg_load (zmsg_t *self, FILE *file);

//  Encode message to a new buffer, return buffer size
CZMQ_EXPORT size_t
    zmsg_encode (zmsg_t *self, byte **buffer);

//  Decode a buffer into a new message, returns NULL if buffer is not
//  properly formatted.
CZMQ_EXPORT zmsg_t *
    zmsg_decode (byte *buffer, size_t buffer_size);

//  Create copy of message, as new message object
CZMQ_EXPORT zmsg_t *
    zmsg_dup (zmsg_t *self);

//  Print message to stderr, for debugging
CZMQ_EXPORT void
    zmsg_dump (zmsg_t *self);

//  Self test of this class
CZMQ_EXPORT int
    zmsg_test (bool verbose);

Description

The zmsg class provides methods to send and receive multipart messages across ØMQ sockets. This class provides a list-like container interface, with methods to work with the overall container. zmsg_t messages are composed of zero or more zframe_t frames.

Example

From zmsg_test method

 zctx_t *ctx = zctx_new ();
 assert (ctx);

 void *output = zsocket_new (ctx, ZMQ_PAIR);
 assert (output);
 zsocket_bind (output, "inproc://zmsg.test");
 void *input = zsocket_new (ctx, ZMQ_PAIR);
 assert (input);
 zsocket_connect (input, "inproc://zmsg.test");

 // Test send and receive of single-frame message
 zmsg_t *msg = zmsg_new ();
 assert (msg);
 zframe_t *frame = zframe_new ("Hello", 5);
 assert (frame);
 zmsg_push (msg, frame);
 assert (zmsg_size (msg) == 1);
 assert (zmsg_content_size (msg) == 5);
 rc = zmsg_send (&msg, output);
 assert (msg == NULL);
 assert (rc == 0);

 msg = zmsg_recv (input);
 assert (msg);
 assert (zmsg_size (msg) == 1);
 assert (zmsg_content_size (msg) == 5);
 zmsg_destroy (&msg);

 // Test send and receive of multi-frame message
 msg = zmsg_new ();
 assert (msg);
 rc = zmsg_addmem (msg, "Frame0", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame1", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame2", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame3", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame4", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame5", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame6", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame7", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame8", 6);
 assert (rc == 0);
 rc = zmsg_addmem (msg, "Frame9", 6);
 assert (rc == 0);
 zmsg_t *copy = zmsg_dup (msg);
 assert (copy);
 rc = zmsg_send (&copy, output);
 assert (rc == 0);
 rc = zmsg_send (&msg, output);
 assert (rc == 0);

 copy = zmsg_recv (input);
 assert (copy);
 assert (zmsg_size (copy) == 10);
 assert (zmsg_content_size (copy) == 60);
 zmsg_destroy (&copy);

 msg = zmsg_recv (input);
 assert (msg);
 assert (zmsg_size (msg) == 10);
 assert (zmsg_content_size (msg) == 60);
 if (verbose)
 zmsg_dump (msg);

 // Save to a file, read back
 FILE *file = fopen ("zmsg.test", "w");
 assert (file);
 rc = zmsg_save (msg, file);
 assert (rc == 0);
 fclose (file);

 file = fopen ("zmsg.test", "r");
 rc = zmsg_save (msg, file);
 assert (rc == -1);
 fclose (file);
 zmsg_destroy (&msg);

 file = fopen ("zmsg.test", "r");
 msg = zmsg_load (NULL, file);
 assert (msg);
 fclose (file);
 remove ("zmsg.test");
 assert (zmsg_size (msg) == 10);
 assert (zmsg_content_size (msg) == 60);

 // Remove all frames except first and last
 int frame_nbr;
 for (frame_nbr = 0; frame_nbr < 8; frame_nbr++) {
 zmsg_first (msg);
 frame = zmsg_next (msg);
 zmsg_remove (msg, frame);
 zframe_destroy (&frame);
 }
 // Test message frame manipulation
 assert (zmsg_size (msg) == 2);
 frame = zmsg_last (msg);
 assert (zframe_streq (frame, "Frame9"));
 assert (zmsg_content_size (msg) == 12);
 frame = zframe_new ("Address", 7);
 assert (frame);
 zmsg_wrap (msg, frame);
 assert (zmsg_size (msg) == 4);
 rc = zmsg_addstr (msg, "Body");
 assert (rc == 0);
 assert (zmsg_size (msg) == 5);
 frame = zmsg_unwrap (msg);
 zframe_destroy (&frame);
 assert (zmsg_size (msg) == 3);
 char *body = zmsg_popstr (msg);
 assert (streq (body, "Frame0"));
 free (body);
 zmsg_destroy (&msg);

 // Test encoding/decoding
 msg = zmsg_new ();
 assert (msg);
 byte *blank = (byte *) zmalloc (100000);
 assert (blank);
 rc = zmsg_addmem (msg, blank, 0);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 1);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 253);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 254);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 255);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 256);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 65535);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 65536);
 assert (rc == 0);
 rc = zmsg_addmem (msg, blank, 65537);
 assert (rc == 0);
 free (blank);
 assert (zmsg_size (msg) == 9);
 byte *buffer;
 size_t buffer_size = zmsg_encode (msg, &buffer);
 zmsg_destroy (&msg);
 msg = zmsg_decode (buffer, buffer_size);
 assert (msg);
 free (buffer);
 zmsg_destroy (&msg);

 // Now try methods on an empty message
 msg = zmsg_new ();
 assert (msg);
 assert (zmsg_size (msg) == 0);
 assert (zmsg_first (msg) == NULL);
 assert (zmsg_last (msg) == NULL);
 assert (zmsg_next (msg) == NULL);
 assert (zmsg_pop (msg) == NULL);
 zmsg_destroy (&msg);
  zctx_destroy (&ctx);

See also

czmq(7)

Authors

The CZMQ manual was written by Pieter Hintjens<moc.xitami|hp#moc.xitami|hp>.

Resources

Main web site: http://czmq.zeromq.org/

Report bugs to the ØMQ development mailing list: <gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez>

Copyright

Copyright (c) 1991-2010 iMatix Corporation and contributors. License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>. This is free software: you are free to change it and redistribute it. There is NO WARRANTY, to the extent permitted by law. For details see the files COPYING and COPYING.LESSER included with the CZMQ distribution.