You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
242 lines
8.0 KiB
242 lines
8.0 KiB
'\" t
|
|
.\" Title: zstr
|
|
.\" Author: [see the "AUTHORS" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
|
|
.\" Date: 12/31/2016
|
|
.\" Manual: CZMQ Manual
|
|
.\" Source: CZMQ 4.0.2
|
|
.\" Language: English
|
|
.\"
|
|
.TH "ZSTR" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "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"
|
|
zstr \- sending and receiving strings
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.nf
|
|
// This is a stable class, and may not change except for emergencies\&. It
|
|
// is provided in stable builds\&.
|
|
// This class has draft methods, which may change over time\&. They are not
|
|
// in stable releases, by default\&. Use \-\-enable\-drafts to enable\&.
|
|
// Receive C string from socket\&. Caller must free returned string using
|
|
// zstr_free()\&. Returns NULL if the context is being terminated or the
|
|
// process was interrupted\&.
|
|
// Caller owns return value and must destroy it when done\&.
|
|
CZMQ_EXPORT char *
|
|
zstr_recv (void *source);
|
|
|
|
// Receive a series of strings (until NULL) from multipart data\&.
|
|
// Each string is allocated and filled with string data; if there
|
|
// are not enough frames, unallocated strings are set to NULL\&.
|
|
// Returns \-1 if the message could not be read, else returns the
|
|
// number of strings filled, zero or more\&. Free each returned string
|
|
// using zstr_free()\&. If not enough strings are provided, remaining
|
|
// multipart frames in the message are dropped\&.
|
|
CZMQ_EXPORT int
|
|
zstr_recvx (void *source, char **string_p, \&.\&.\&.);
|
|
|
|
// Send a C string to a socket, as a frame\&. The string is sent without
|
|
// trailing null byte; to read this you can use zstr_recv, or a similar
|
|
// method that adds a null terminator on the received string\&. String
|
|
// may be NULL, which is sent as ""\&.
|
|
CZMQ_EXPORT int
|
|
zstr_send (void *dest, const char *string);
|
|
|
|
// Send a C string to a socket, as zstr_send(), with a MORE flag, so that
|
|
// you can send further strings in the same multi\-part message\&.
|
|
CZMQ_EXPORT int
|
|
zstr_sendm (void *dest, const char *string);
|
|
|
|
// Send a formatted string to a socket\&. Note that you should NOT use
|
|
// user\-supplied strings in the format (they may contain \*(Aq%\*(Aq which
|
|
// will create security holes)\&.
|
|
CZMQ_EXPORT int
|
|
zstr_sendf (void *dest, const char *format, \&.\&.\&.) CHECK_PRINTF (2);
|
|
|
|
// Send a formatted string to a socket, as for zstr_sendf(), with a
|
|
// MORE flag, so that you can send further strings in the same multi\-part
|
|
// message\&.
|
|
CZMQ_EXPORT int
|
|
zstr_sendfm (void *dest, const char *format, \&.\&.\&.) CHECK_PRINTF (2);
|
|
|
|
// Send a series of strings (until NULL) as multipart data
|
|
// Returns 0 if the strings could be sent OK, or \-1 on error\&.
|
|
CZMQ_EXPORT int
|
|
zstr_sendx (void *dest, const char *string, \&.\&.\&.);
|
|
|
|
// Free a provided string, and nullify the parent pointer\&. Safe to call on
|
|
// a null pointer\&.
|
|
CZMQ_EXPORT void
|
|
zstr_free (char **string_p);
|
|
|
|
// Self test of this class\&.
|
|
CZMQ_EXPORT void
|
|
zstr_test (bool verbose);
|
|
|
|
#ifdef CZMQ_BUILD_DRAFT_API
|
|
// *** Draft method, for development use, may change without warning ***
|
|
// Accepts a void pointer and returns a fresh character string\&. If source
|
|
// is null, returns an empty string\&.
|
|
// Caller owns return value and must destroy it when done\&.
|
|
CZMQ_EXPORT char *
|
|
zstr_str (void *source);
|
|
|
|
#endif // CZMQ_BUILD_DRAFT_API
|
|
Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zstr\&.c\*(Aq\&.
|
|
.fi
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
The zstr class provides utility functions for sending and receiving C strings across 0MQ sockets\&. It sends strings without a terminating null, and appends a null byte on received strings\&. This class is for simple message sending\&.
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
Memory Wire
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-+ +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
Send | S t r i n g | 0 | \-\-\-\-> | 6 | S t r i n g |
|
|
+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-+ +\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
Wire Heap
|
|
+\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-+
|
|
Recv | 6 | S t r i n g | \-\-\-\-> | S t r i n g | 0 |
|
|
+\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-+
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.SH "EXAMPLE"
|
|
.PP
|
|
\fBFrom zstr_test method\fR.
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
// Create two PAIR sockets and connect over inproc
|
|
zsock_t *output = zsock_new_pair ("@inproc://zstr\&.test");
|
|
assert (output);
|
|
zsock_t *input = zsock_new_pair (">inproc://zstr\&.test");
|
|
assert (input);
|
|
|
|
// Send ten strings, five strings with MORE flag and then END
|
|
int string_nbr;
|
|
for (string_nbr = 0; string_nbr < 10; string_nbr++)
|
|
zstr_sendf (output, "this is string %d", string_nbr);
|
|
zstr_sendx (output, "This", "is", "almost", "the", "very", "END", NULL);
|
|
|
|
// Read and count until we receive END
|
|
string_nbr = 0;
|
|
for (string_nbr = 0;; string_nbr++) {
|
|
char *string = zstr_recv (input);
|
|
assert (string);
|
|
if (streq (string, "END")) {
|
|
zstr_free (&string);
|
|
break;
|
|
}
|
|
zstr_free (&string);
|
|
}
|
|
assert (string_nbr == 15);
|
|
|
|
zsock_destroy (&input);
|
|
zsock_destroy (&output);
|
|
|
|
#if defined (ZMQ_SERVER)
|
|
// Test SERVER/CLIENT over zstr
|
|
zsock_t *server = zsock_new_server ("inproc://zstr\-test\-routing");
|
|
zsock_t *client = zsock_new_client ("inproc://zstr\-test\-routing");;
|
|
assert (server);
|
|
assert (client);
|
|
|
|
// Try normal ping\-pong to check reply routing ID
|
|
int rc = zstr_send (client, "Hello");
|
|
assert (rc == 0);
|
|
char *request = zstr_recv (server);
|
|
assert (streq (request, "Hello"));
|
|
assert (zsock_routing_id (server));
|
|
free (request);
|
|
|
|
rc = zstr_send (server, "World");
|
|
assert (rc == 0);
|
|
char *reply = zstr_recv (client);
|
|
assert (streq (reply, "World"));
|
|
free (reply);
|
|
|
|
rc = zstr_sendf (server, "%s", "World");
|
|
assert (rc == 0);
|
|
reply = zstr_recv (client);
|
|
assert (streq (reply, "World"));
|
|
free (reply);
|
|
|
|
// Try ping\-pong using sendx and recx
|
|
rc = zstr_sendx (client, "Hello", NULL);
|
|
assert (rc == 0);
|
|
rc = zstr_recvx (server, &request, NULL);
|
|
assert (rc >= 0);
|
|
assert (streq (request, "Hello"));
|
|
free (request);
|
|
|
|
rc = zstr_sendx (server, "World", NULL);
|
|
assert (rc == 0);
|
|
rc = zstr_recvx (client, &reply, NULL);
|
|
assert (rc >= 0);
|
|
assert (streq (reply, "World"));
|
|
free (reply);
|
|
|
|
// Client and server disallow multipart
|
|
rc = zstr_sendm (client, "Hello");
|
|
assert (rc == \-1);
|
|
rc = zstr_sendm (server, "World");
|
|
assert (rc == \-1);
|
|
|
|
zsock_destroy (&client);
|
|
zsock_destroy (&server);
|
|
#endif
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.SH "AUTHORS"
|
|
.sp
|
|
The czmq manual was written by the authors in the AUTHORS file\&.
|
|
.SH "RESOURCES"
|
|
.sp
|
|
Main web site: \m[blue]\fB\%\fR\m[]
|
|
.sp
|
|
Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
|
|
.SH "COPYRIGHT"
|
|
.sp
|
|
Copyright (c) the Contributors as noted in the AUTHORS file\&. This file is part of CZMQ, the high\-level C binding for 0MQ: http://czmq\&.zeromq\&.org\&. This Source Code Form is subject to the terms of the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. LICENSE included with the czmq distribution\&.
|
|
.SH "NOTES"
|
|
.IP " 1." 4
|
|
zeromq-dev@lists.zeromq.org
|
|
.RS 4
|
|
\%mailto:zeromq-dev@lists.zeromq.org
|
|
.RE
|
|
|