'\" t .\" Title: zmsg .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 .\" Date: 08/30/2011 .\" Manual: czmq Manual .\" Source: czmq 1.1.0 .\" Language: English .\" .TH "ZMSG" "7" "08/30/2011" "czmq 1\&.1\&.0" "czmq Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" zmsg \- working with multipart messages .SH "SYNOPSIS" .sp .nf // Create a new empty message object zmsg_t * zmsg_new (void); // Destroy a message object and all frames it contains void zmsg_destroy (zmsg_t **self_p); // Read 1 or more frames off the socket, into a new message object zmsg_t * zmsg_recv (void *socket); // Send a message to the socket, and then destroy it void zmsg_send (zmsg_t **self_p, void *socket); // Return number of frames in message size_t zmsg_size (zmsg_t *self); // Return combined size of all frames in message size_t zmsg_content_size (zmsg_t *self); // Push frame to front of message, before first frame void zmsg_push (zmsg_t *self, zframe_t *frame); // Pop frame off front of message, caller now owns frame zframe_t * zmsg_pop (zmsg_t *self); // Add frame to end of message, after last frame void zmsg_add (zmsg_t *self, zframe_t *frame); // Push block of memory as new frame to front of message void zmsg_pushmem (zmsg_t *self, const void *src, size_t size); // Push block of memory as new frame to end of message void zmsg_addmem (zmsg_t *self, const void *src, size_t size); // Push string as new frame to front of message void zmsg_pushstr (zmsg_t *self, const char *format, \&.\&.\&.); // Push string as new frame to end of message void zmsg_addstr (zmsg_t *self, const char *format, \&.\&.\&.); // Pop frame off front of message, return as fresh string char * zmsg_popstr (zmsg_t *self); // Push frame to front of message, before first frame // Pushes an empty frame in front of frame 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\&. zframe_t * zmsg_unwrap (zmsg_t *self); // Remove frame from message, at any position, caller owns it void zmsg_remove (zmsg_t *self, zframe_t *frame); // Return first frame in message, or null zframe_t * zmsg_first (zmsg_t *self); // Return next frame in message, or null zframe_t * zmsg_next (zmsg_t *self); // Return last frame in message, or null zframe_t * zmsg_last (zmsg_t *self); // Save message to an open file, return 0 if OK, else \-1\&. int zmsg_save (zmsg_t *self, FILE *file); // Load/append an open file into message, create new message if // null message provided\&. zmsg_t * zmsg_load (zmsg_t *self, FILE *file); // Encode message to a new buffer, return buffer size size_t zmsg_encode (zmsg_t *self, byte **buffer); // Decode a buffer into a new message, returns NULL if buffer is not // properly formatted\&. zmsg_t * zmsg_decode (byte *buffer, size_t buffer_size); // Create copy of message, as new message object zmsg_t * zmsg_dup (zmsg_t *self); // Print message to stderr, for debugging void zmsg_dump (zmsg_t *self); // Self test of this class int zmsg_test (Bool verbose); .fi .SH "DESCRIPTION" .sp The zmsg class provides methods to send and receive multipart messages across 0MQ 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\&. .SH "EXAMPLE" .PP \fBFrom zmsg_test method\fR. .sp .if n \{\ .RS 4 .\} .nf zctx_t *ctx = zctx_new (); void *output = zsocket_new (ctx, ZMQ_PAIR); zsocket_bind (output, "inproc://zmsg\&.test"); void *input = zsocket_new (ctx, ZMQ_PAIR); zsocket_connect (input, "inproc://zmsg\&.test"); // Test send and receive of single\-frame message zmsg_t *msg = zmsg_new (); zframe_t *frame = zframe_new ("Hello", 5); zmsg_push (msg, frame); assert (zmsg_size (msg) == 1); assert (zmsg_content_size (msg) == 5); zmsg_send (&msg, output); assert (msg == NULL); 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 (); zmsg_addmem (msg, "Frame0", 6); zmsg_addmem (msg, "Frame1", 6); zmsg_addmem (msg, "Frame2", 6); zmsg_addmem (msg, "Frame3", 6); zmsg_addmem (msg, "Frame4", 6); zmsg_addmem (msg, "Frame5", 6); zmsg_addmem (msg, "Frame6", 6); zmsg_addmem (msg, "Frame7", 6); zmsg_addmem (msg, "Frame8", 6); zmsg_addmem (msg, "Frame9", 6); zmsg_t *copy = zmsg_dup (msg); zmsg_send (©, output); zmsg_send (&msg, output); copy = zmsg_recv (input); assert (copy); assert (zmsg_size (copy) == 10); assert (zmsg_content_size (copy) == 60); zmsg_destroy (©); 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); int 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); 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); assert (zmsg_content_size (msg) == 12); frame = zframe_new ("Address", 7); zmsg_wrap (msg, frame); assert (zmsg_size (msg) == 4); zmsg_addstr (msg, "Body"); 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 (); byte *blank = zmalloc (100000); zmsg_addmem (msg, blank, 0); zmsg_addmem (msg, blank, 1); zmsg_addmem (msg, blank, 253); zmsg_addmem (msg, blank, 254); zmsg_addmem (msg, blank, 255); zmsg_addmem (msg, blank, 256); zmsg_addmem (msg, blank, 65535); zmsg_addmem (msg, blank, 65536); zmsg_addmem (msg, blank, 65537); 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 (zmsg_size (msg) == 0); assert (zmsg_first (msg) == NULL); assert (zmsg_next (msg) == NULL); assert (zmsg_pop (msg) == NULL); zmsg_destroy (&msg); zctx_destroy (&ctx); .fi .if n \{\ .RE .\} .sp .SH "SEE ALSO" .sp \fBczmq\fR(7) .SH "AUTHORS" .sp The czmq manual was written by Pieter Hintjens<\m[blue]\fBph@imatix\&.com\fR\m[]\&\s-2\u[1]\d\s+2>\&. .SH "RESOURCES" .sp Main web site: \m[blue]\fBhttp://czmq\&.zeromq\&.org/\fR\m[] .sp Report bugs to the 0MQ development mailing list: <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[2]\d\s+2> .SH "COPYRIGHT" .sp Copyright (c) 1991\-2010 iMatix Corporation and contributors\&. License LGPLv3+: GNU LGPL 3 or later <\m[blue]\fBhttp://gnu\&.org/licenses/lgpl\&.html\fR\m[]>\&. 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\&. .SH "NOTES" .IP " 1." 4 ph@imatix.com .RS 4 \%mailto:ph@imatix.com .RE .IP " 2." 4 zeromq-dev@lists.zeromq.org .RS 4 \%mailto:zeromq-dev@lists.zeromq.org .RE