1ZSOCK(3) CZMQ Manual ZSOCK(3)
2
6 zsock - Class for high-level socket API that hides libzmq contexts and
7 sockets
8
10 // This is a stable class, and may not change except for emergencies. It
11 // is provided in stable builds.
12 // This class has draft methods, which may change over time. They are not
13 // in stable releases, by default. Use --enable-drafts to enable.
14 // Create a new socket. Returns the new socket, or NULL if the new socket
15 // could not be created. Note that the symbol zsock_new (and other
16 // constructors/destructors for zsock) are redirected to the *_checked
17 // variant, enabling intelligent socket leak detection. This can have
18 // performance implications if you use a LOT of sockets. To turn off this
19 // redirection behaviour, define ZSOCK_NOCHECK.
20 CZMQ_EXPORT zsock_t *
21 zsock_new (int type);
22 // Create a PUB socket. Default action is bind.
24 CZMQ_EXPORT zsock_t *
25 zsock_new_pub (const char *endpoint);
26 // Create a SUB socket, and optionally subscribe to some prefix string. Default
28 // action is connect.
29 CZMQ_EXPORT zsock_t *
30 zsock_new_sub (const char *endpoint, const char *subscribe);
31 // Create a REQ socket. Default action is connect.
33 CZMQ_EXPORT zsock_t *
34 zsock_new_req (const char *endpoint);
35 // Create a REP socket. Default action is bind.
37 CZMQ_EXPORT zsock_t *
38 zsock_new_rep (const char *endpoint);
39 // Create a DEALER socket. Default action is connect.
41 CZMQ_EXPORT zsock_t *
42 zsock_new_dealer (const char *endpoint);
43 // Create a ROUTER socket. Default action is bind.
45 CZMQ_EXPORT zsock_t *
46 zsock_new_router (const char *endpoint);
47 // Create a PUSH socket. Default action is connect.
49 CZMQ_EXPORT zsock_t *
50 zsock_new_push (const char *endpoint);
51 // Create a PULL socket. Default action is bind.
53 CZMQ_EXPORT zsock_t *
54 zsock_new_pull (const char *endpoint);
55 // Create an XPUB socket. Default action is bind.
57 CZMQ_EXPORT zsock_t *
58 zsock_new_xpub (const char *endpoint);
59 // Create an XSUB socket. Default action is connect.
61 CZMQ_EXPORT zsock_t *
62 zsock_new_xsub (const char *endpoint);
63 // Create a PAIR socket. Default action is connect.
65 CZMQ_EXPORT zsock_t *
66 zsock_new_pair (const char *endpoint);
67 // Create a STREAM socket. Default action is connect.
69 CZMQ_EXPORT zsock_t *
70 zsock_new_stream (const char *endpoint);
71 // Destroy the socket. You must use this for any socket created via the
73 // zsock_new method.
74 CZMQ_EXPORT void
75 zsock_destroy (zsock_t **self_p);
76 // Bind a socket to a formatted endpoint. For tcp:// endpoints, supports
78 // ephemeral ports, if you specify the port number as "*". By default
79 // zsock uses the IANA designated range from C000 (49152) to FFFF (65535).
80 // To override this range, follow the "*" with "[first-last]". Either or
81 // both first and last may be empty. To bind to a random port within the
82 // range, use "!" in place of "*".
83 //
84 // Examples:
85 // tcp://127.0.0.1:* bind to first free port from C000 up
86 // tcp://127.0.0.1:! bind to random port from C000 to FFFF
87 // tcp://127.0.0.1:*[60000-] bind to first free port from 60000 up
88 // tcp://127.0.0.1:![-60000] bind to random port from C000 to 60000
89 // tcp://127.0.0.1:![55000-55999]
90 // bind to random port from 55000 to 55999
91 //
92 // On success, returns the actual port number used, for tcp:// endpoints,
93 // and 0 for other transports. On failure, returns -1. Note that when using
94 // ephemeral ports, a port may be reused by different services without
95 // clients being aware. Protocols that run on ephemeral ports should take
96 // this into account.
97 CZMQ_EXPORT int
98 zsock_bind (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
99 // Returns last bound endpoint, if any.
101 CZMQ_EXPORT const char *
102 zsock_endpoint (zsock_t *self);
103 // Unbind a socket from a formatted endpoint.
105 // Returns 0 if OK, -1 if the endpoint was invalid or the function
106 // isn't supported.
107 CZMQ_EXPORT int
108 zsock_unbind (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
109 // Connect a socket to a formatted endpoint
111 // Returns 0 if OK, -1 if the endpoint was invalid.
112 CZMQ_EXPORT int
113 zsock_connect (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
114 // Disconnect a socket from a formatted endpoint
116 // Returns 0 if OK, -1 if the endpoint was invalid or the function
117 // isn't supported.
118 CZMQ_EXPORT int
119 zsock_disconnect (zsock_t *self, const char *format, ...) CHECK_PRINTF (2);
120 // Attach a socket to zero or more endpoints. If endpoints is not null,
122 // parses as list of ZeroMQ endpoints, separated by commas, and prefixed by
123 // '@' (to bind the socket) or '>' (to connect the socket). Returns 0 if all
124 // endpoints were valid, or -1 if there was a syntax error. If the endpoint
125 // does not start with '@' or '>', the serverish argument defines whether
126 // it is used to bind (serverish = true) or connect (serverish = false).
127 CZMQ_EXPORT int
128 zsock_attach (zsock_t *self, const char *endpoints, bool serverish);
129 // Returns socket type as printable constant string.
131 CZMQ_EXPORT const char *
132 zsock_type_str (zsock_t *self);
133 // Send a 'picture' message to the socket (or actor). The picture is a
135 // string that defines the type of each frame. This makes it easy to send
136 // a complex multiframe message in one call. The picture can contain any
137 // of these characters, each corresponding to one or two arguments:
138 //
139 // i = int (signed)
140 // 1 = uint8_t
141 // 2 = uint16_t
142 // 4 = uint32_t
143 // 8 = uint64_t
144 // s = char *
145 // b = byte *, size_t (2 arguments)
146 // c = zchunk_t *
147 // f = zframe_t *
148 // h = zhashx_t *
149 // U = zuuid_t *
150 // p = void * (sends the pointer value, only meaningful over inproc)
151 // m = zmsg_t * (sends all frames in the zmsg)
152 // z = sends zero-sized frame (0 arguments)
153 // u = uint (deprecated)
154 //
155 // Note that s, b, c, and f are encoded the same way and the choice is
156 // offered as a convenience to the sender, which may or may not already
157 // have data in a zchunk or zframe. Does not change or take ownership of
158 // any arguments. Returns 0 if successful, -1 if sending failed for any
159 // reason.
160 CZMQ_EXPORT int
161 zsock_send (void *self, const char *picture, ...);
162 // Send a 'picture' message to the socket (or actor). This is a va_list
164 // version of zsock_send (), so please consult its documentation for the
165 // details.
166 CZMQ_EXPORT int
167 zsock_vsend (void *self, const char *picture, va_list argptr);
168 // Receive a 'picture' message to the socket (or actor). See zsock_send for
170 // the format and meaning of the picture. Returns the picture elements into
171 // a series of pointers as provided by the caller:
172 //
173 // i = int * (stores signed integer)
174 // 4 = uint32_t * (stores 32-bit unsigned integer)
175 // 8 = uint64_t * (stores 64-bit unsigned integer)
176 // s = char ** (allocates new string)
177 // b = byte **, size_t * (2 arguments) (allocates memory)
178 // c = zchunk_t ** (creates zchunk)
179 // f = zframe_t ** (creates zframe)
180 // U = zuuid_t * (creates a zuuid with the data)
181 // h = zhashx_t ** (creates zhashx)
182 // p = void ** (stores pointer)
183 // m = zmsg_t ** (creates a zmsg with the remaing frames)
184 // z = null, asserts empty frame (0 arguments)
185 // u = uint * (stores unsigned integer, deprecated)
186 //
187 // Note that zsock_recv creates the returned objects, and the caller must
188 // destroy them when finished with them. The supplied pointers do not need
189 // to be initialized. Returns 0 if successful, or -1 if it failed to recv
190 // a message, in which case the pointers are not modified. When message
191 // frames are truncated (a short message), sets return values to zero/null.
192 // If an argument pointer is NULL, does not store any value (skips it).
193 // An 'n' picture matches an empty frame; if the message does not match,
194 // the method will return -1.
195 CZMQ_EXPORT int
196 zsock_recv (void *self, const char *picture, ...);
197 // Receive a 'picture' message from the socket (or actor). This is a
199 // va_list version of zsock_recv (), so please consult its documentation
200 // for the details.
201 CZMQ_EXPORT int
202 zsock_vrecv (void *self, const char *picture, va_list argptr);
203 // Send a binary encoded 'picture' message to the socket (or actor). This
205 // method is similar to zsock_send, except the arguments are encoded in a
206 // binary format that is compatible with zproto, and is designed to reduce
207 // memory allocations. The pattern argument is a string that defines the
208 // type of each argument. Supports these argument types:
209 //
210 // pattern C type zproto type:
211 // 1 uint8_t type = "number" size = "1"
212 // 2 uint16_t type = "number" size = "2"
213 // 4 uint32_t type = "number" size = "3"
214 // 8 uint64_t type = "number" size = "4"
215 // s char *, 0-255 chars type = "string"
216 // S char *, 0-2^32-1 chars type = "longstr"
217 // c zchunk_t * type = "chunk"
218 // f zframe_t * type = "frame"
219 // u zuuid_t * type = "uuid"
220 // m zmsg_t * type = "msg"
221 // p void *, sends pointer value, only over inproc
222 //
223 // Does not change or take ownership of any arguments. Returns 0 if
224 // successful, -1 if sending failed for any reason.
225 CZMQ_EXPORT int
226 zsock_bsend (void *self, const char *picture, ...);
227 // Receive a binary encoded 'picture' message from the socket (or actor).
229 // This method is similar to zsock_recv, except the arguments are encoded
230 // in a binary format that is compatible with zproto, and is designed to
231 // reduce memory allocations. The pattern argument is a string that defines
232 // the type of each argument. See zsock_bsend for the supported argument
233 // types. All arguments must be pointers; this call sets them to point to
234 // values held on a per-socket basis.
235 // For types 1, 2, 4 and 8 the caller must allocate the memory itself before
236 // calling zsock_brecv.
237 // For types S, the caller must free the value once finished with it, as
238 // zsock_brecv will allocate the buffer.
239 // For type s, the caller must not free the value as it is stored in a
240 // local cache for performance purposes.
241 // For types c, f, u and m the caller must call the appropriate destructor
242 // depending on the object as zsock_brecv will create new objects.
243 // For type p the caller must coordinate with the sender, as it is just a
244 // pointer value being passed.
245 CZMQ_EXPORT int
246 zsock_brecv (void *self, const char *picture, ...);
247 // Set socket to use unbounded pipes (HWM=0); use this in cases when you are
249 // totally certain the message volume can fit in memory. This method works
250 // across all versions of ZeroMQ. Takes a polymorphic socket reference.
251 CZMQ_EXPORT void
252 zsock_set_unbounded (void *self);
253 // Send a signal over a socket. A signal is a short message carrying a
255 // success/failure code (by convention, 0 means OK). Signals are encoded
256 // to be distinguishable from "normal" messages. Accepts a zsock_t or a
257 // zactor_t argument, and returns 0 if successful, -1 if the signal could
258 // not be sent. Takes a polymorphic socket reference.
259 CZMQ_EXPORT int
260 zsock_signal (void *self, byte status);
261 // Wait on a signal. Use this to coordinate between threads, over pipe
263 // pairs. Blocks until the signal is received. Returns -1 on error, 0 or
264 // greater on success. Accepts a zsock_t or a zactor_t as argument.
265 // Takes a polymorphic socket reference.
266 CZMQ_EXPORT int
267 zsock_wait (void *self);
268 // If there is a partial message still waiting on the socket, remove and
270 // discard it. This is useful when reading partial messages, to get specific
271 // message types.
272 CZMQ_EXPORT void
273 zsock_flush (void *self);
274 // Probe the supplied object, and report if it looks like a zsock_t.
276 // Takes a polymorphic socket reference.
277 CZMQ_EXPORT bool
278 zsock_is (void *self);
279 // Probe the supplied reference. If it looks like a zsock_t instance, return
281 // the underlying libzmq socket handle; else if it looks like a file
282 // descriptor, return NULL; else if it looks like a libzmq socket handle,
283 // return the supplied value. Takes a polymorphic socket reference.
284 CZMQ_EXPORT void *
285 zsock_resolve (void *self);
286 // Get socket option `heartbeat_ivl`.
288 // Available from libzmq 4.2.0.
289 // Caller owns return value and must destroy it when done.
290 CZMQ_EXPORT int
291 zsock_heartbeat_ivl (void *self);
292 // Set socket option `heartbeat_ivl`.
294 // Available from libzmq 4.2.0.
295 CZMQ_EXPORT void
296 zsock_set_heartbeat_ivl (void *self, int heartbeat_ivl);
297 // Get socket option `heartbeat_ttl`.
299 // Available from libzmq 4.2.0.
300 // Caller owns return value and must destroy it when done.
301 CZMQ_EXPORT int
302 zsock_heartbeat_ttl (void *self);
303 // Set socket option `heartbeat_ttl`.
305 // Available from libzmq 4.2.0.
306 CZMQ_EXPORT void
307 zsock_set_heartbeat_ttl (void *self, int heartbeat_ttl);
308 // Get socket option `heartbeat_timeout`.
310 // Available from libzmq 4.2.0.
311 // Caller owns return value and must destroy it when done.
312 CZMQ_EXPORT int
313 zsock_heartbeat_timeout (void *self);
314 // Set socket option `heartbeat_timeout`.
316 // Available from libzmq 4.2.0.
317 CZMQ_EXPORT void
318 zsock_set_heartbeat_timeout (void *self, int heartbeat_timeout);
319 // Get socket option `use_fd`.
321 // Available from libzmq 4.2.0.
322 // Caller owns return value and must destroy it when done.
323 CZMQ_EXPORT int
324 zsock_use_fd (void *self);
325 // Set socket option `use_fd`.
327 // Available from libzmq 4.2.0.
328 CZMQ_EXPORT void
329 zsock_set_use_fd (void *self, int use_fd);
330 // Set socket option `xpub_manual`.
332 // Available from libzmq 4.2.0.
333 CZMQ_EXPORT void
334 zsock_set_xpub_manual (void *self, int xpub_manual);
335 // Set socket option `xpub_welcome_msg`.
337 // Available from libzmq 4.2.0.
338 CZMQ_EXPORT void
339 zsock_set_xpub_welcome_msg (void *self, const char *xpub_welcome_msg);
340 // Set socket option `stream_notify`.
342 // Available from libzmq 4.2.0.
343 CZMQ_EXPORT void
344 zsock_set_stream_notify (void *self, int stream_notify);
345 // Get socket option `invert_matching`.
347 // Available from libzmq 4.2.0.
348 // Caller owns return value and must destroy it when done.
349 CZMQ_EXPORT int
350 zsock_invert_matching (void *self);
351 // Set socket option `invert_matching`.
353 // Available from libzmq 4.2.0.
354 CZMQ_EXPORT void
355 zsock_set_invert_matching (void *self, int invert_matching);
356 // Set socket option `xpub_verboser`.
358 // Available from libzmq 4.2.0.
359 CZMQ_EXPORT void
360 zsock_set_xpub_verboser (void *self, int xpub_verboser);
361 // Get socket option `connect_timeout`.
363 // Available from libzmq 4.2.0.
364 // Caller owns return value and must destroy it when done.
365 CZMQ_EXPORT int
366 zsock_connect_timeout (void *self);
367 // Set socket option `connect_timeout`.
369 // Available from libzmq 4.2.0.
370 CZMQ_EXPORT void
371 zsock_set_connect_timeout (void *self, int connect_timeout);
372 // Get socket option `tcp_maxrt`.
374 // Available from libzmq 4.2.0.
375 // Caller owns return value and must destroy it when done.
376 CZMQ_EXPORT int
377 zsock_tcp_maxrt (void *self);
378 // Set socket option `tcp_maxrt`.
380 // Available from libzmq 4.2.0.
381 CZMQ_EXPORT void
382 zsock_set_tcp_maxrt (void *self, int tcp_maxrt);
383 // Get socket option `thread_safe`.
385 // Available from libzmq 4.2.0.
386 // Caller owns return value and must destroy it when done.
387 CZMQ_EXPORT int
388 zsock_thread_safe (void *self);
389 // Get socket option `multicast_maxtpdu`.
391 // Available from libzmq 4.2.0.
392 // Caller owns return value and must destroy it when done.
393 CZMQ_EXPORT int
394 zsock_multicast_maxtpdu (void *self);
395 // Set socket option `multicast_maxtpdu`.
397 // Available from libzmq 4.2.0.
398 CZMQ_EXPORT void
399 zsock_set_multicast_maxtpdu (void *self, int multicast_maxtpdu);
400 // Get socket option `vmci_buffer_size`.
402 // Available from libzmq 4.2.0.
403 // Caller owns return value and must destroy it when done.
404 CZMQ_EXPORT int
405 zsock_vmci_buffer_size (void *self);
406 // Set socket option `vmci_buffer_size`.
408 // Available from libzmq 4.2.0.
409 CZMQ_EXPORT void
410 zsock_set_vmci_buffer_size (void *self, int vmci_buffer_size);
411 // Get socket option `vmci_buffer_min_size`.
413 // Available from libzmq 4.2.0.
414 // Caller owns return value and must destroy it when done.
415 CZMQ_EXPORT int
416 zsock_vmci_buffer_min_size (void *self);
417 // Set socket option `vmci_buffer_min_size`.
419 // Available from libzmq 4.2.0.
420 CZMQ_EXPORT void
421 zsock_set_vmci_buffer_min_size (void *self, int vmci_buffer_min_size);
422 // Get socket option `vmci_buffer_max_size`.
424 // Available from libzmq 4.2.0.
425 // Caller owns return value and must destroy it when done.
426 CZMQ_EXPORT int
427 zsock_vmci_buffer_max_size (void *self);
428 // Set socket option `vmci_buffer_max_size`.
430 // Available from libzmq 4.2.0.
431 CZMQ_EXPORT void
432 zsock_set_vmci_buffer_max_size (void *self, int vmci_buffer_max_size);
433 // Get socket option `vmci_connect_timeout`.
435 // Available from libzmq 4.2.0.
436 // Caller owns return value and must destroy it when done.
437 CZMQ_EXPORT int
438 zsock_vmci_connect_timeout (void *self);
439 // Set socket option `vmci_connect_timeout`.
441 // Available from libzmq 4.2.0.
442 CZMQ_EXPORT void
443 zsock_set_vmci_connect_timeout (void *self, int vmci_connect_timeout);
444 // Get socket option `tos`.
446 // Available from libzmq 4.1.0.
447 // Caller owns return value and must destroy it when done.
448 CZMQ_EXPORT int
449 zsock_tos (void *self);
450 // Set socket option `tos`.
452 // Available from libzmq 4.1.0.
453 CZMQ_EXPORT void
454 zsock_set_tos (void *self, int tos);
455 // Set socket option `router_handover`.
457 // Available from libzmq 4.1.0.
458 CZMQ_EXPORT void
459 zsock_set_router_handover (void *self, int router_handover);
460 // Set socket option `connect_rid`.
462 // Available from libzmq 4.1.0.
463 CZMQ_EXPORT void
464 zsock_set_connect_rid (void *self, const char *connect_rid);
465 // Set socket option `connect_rid` from 32-octet binary
467 // Available from libzmq 4.1.0.
468 CZMQ_EXPORT void
469 zsock_set_connect_rid_bin (void *self, const byte *connect_rid);
470 // Get socket option `handshake_ivl`.
472 // Available from libzmq 4.1.0.
473 // Caller owns return value and must destroy it when done.
474 CZMQ_EXPORT int
475 zsock_handshake_ivl (void *self);
476 // Set socket option `handshake_ivl`.
478 // Available from libzmq 4.1.0.
479 CZMQ_EXPORT void
480 zsock_set_handshake_ivl (void *self, int handshake_ivl);
481 // Get socket option `socks_proxy`.
483 // Available from libzmq 4.1.0.
484 // Caller owns return value and must destroy it when done.
485 CZMQ_EXPORT char *
486 zsock_socks_proxy (void *self);
487 // Set socket option `socks_proxy`.
489 // Available from libzmq 4.1.0.
490 CZMQ_EXPORT void
491 zsock_set_socks_proxy (void *self, const char *socks_proxy);
492 // Set socket option `xpub_nodrop`.
494 // Available from libzmq 4.1.0.
495 CZMQ_EXPORT void
496 zsock_set_xpub_nodrop (void *self, int xpub_nodrop);
497 // Set socket option `router_mandatory`.
499 // Available from libzmq 4.0.0.
500 CZMQ_EXPORT void
501 zsock_set_router_mandatory (void *self, int router_mandatory);
502 // Set socket option `probe_router`.
504 // Available from libzmq 4.0.0.
505 CZMQ_EXPORT void
506 zsock_set_probe_router (void *self, int probe_router);
507 // Set socket option `req_relaxed`.
509 // Available from libzmq 4.0.0.
510 CZMQ_EXPORT void
511 zsock_set_req_relaxed (void *self, int req_relaxed);
512 // Set socket option `req_correlate`.
514 // Available from libzmq 4.0.0.
515 CZMQ_EXPORT void
516 zsock_set_req_correlate (void *self, int req_correlate);
517 // Set socket option `conflate`.
519 // Available from libzmq 4.0.0.
520 CZMQ_EXPORT void
521 zsock_set_conflate (void *self, int conflate);
522 // Get socket option `zap_domain`.
524 // Available from libzmq 4.0.0.
525 // Caller owns return value and must destroy it when done.
526 CZMQ_EXPORT char *
527 zsock_zap_domain (void *self);
528 // Set socket option `zap_domain`.
530 // Available from libzmq 4.0.0.
531 CZMQ_EXPORT void
532 zsock_set_zap_domain (void *self, const char *zap_domain);
533 // Get socket option `mechanism`.
535 // Available from libzmq 4.0.0.
536 // Caller owns return value and must destroy it when done.
537 CZMQ_EXPORT int
538 zsock_mechanism (void *self);
539 // Get socket option `plain_server`.
541 // Available from libzmq 4.0.0.
542 // Caller owns return value and must destroy it when done.
543 CZMQ_EXPORT int
544 zsock_plain_server (void *self);
545 // Set socket option `plain_server`.
547 // Available from libzmq 4.0.0.
548 CZMQ_EXPORT void
549 zsock_set_plain_server (void *self, int plain_server);
550 // Get socket option `plain_username`.
552 // Available from libzmq 4.0.0.
553 // Caller owns return value and must destroy it when done.
554 CZMQ_EXPORT char *
555 zsock_plain_username (void *self);
556 // Set socket option `plain_username`.
558 // Available from libzmq 4.0.0.
559 CZMQ_EXPORT void
560 zsock_set_plain_username (void *self, const char *plain_username);
561 // Get socket option `plain_password`.
563 // Available from libzmq 4.0.0.
564 // Caller owns return value and must destroy it when done.
565 CZMQ_EXPORT char *
566 zsock_plain_password (void *self);
567 // Set socket option `plain_password`.
569 // Available from libzmq 4.0.0.
570 CZMQ_EXPORT void
571 zsock_set_plain_password (void *self, const char *plain_password);
572 // Get socket option `curve_server`.
574 // Available from libzmq 4.0.0.
575 // Caller owns return value and must destroy it when done.
576 CZMQ_EXPORT int
577 zsock_curve_server (void *self);
578 // Set socket option `curve_server`.
580 // Available from libzmq 4.0.0.
581 CZMQ_EXPORT void
582 zsock_set_curve_server (void *self, int curve_server);
583 // Get socket option `curve_publickey`.
585 // Available from libzmq 4.0.0.
586 // Caller owns return value and must destroy it when done.
587 CZMQ_EXPORT char *
588 zsock_curve_publickey (void *self);
589 // Set socket option `curve_publickey`.
591 // Available from libzmq 4.0.0.
592 CZMQ_EXPORT void
593 zsock_set_curve_publickey (void *self, const char *curve_publickey);
594 // Set socket option `curve_publickey` from 32-octet binary
596 // Available from libzmq 4.0.0.
597 CZMQ_EXPORT void
598 zsock_set_curve_publickey_bin (void *self, const byte *curve_publickey);
599 // Get socket option `curve_secretkey`.
601 // Available from libzmq 4.0.0.
602 // Caller owns return value and must destroy it when done.
603 CZMQ_EXPORT char *
604 zsock_curve_secretkey (void *self);
605 // Set socket option `curve_secretkey`.
607 // Available from libzmq 4.0.0.
608 CZMQ_EXPORT void
609 zsock_set_curve_secretkey (void *self, const char *curve_secretkey);
610 // Set socket option `curve_secretkey` from 32-octet binary
612 // Available from libzmq 4.0.0.
613 CZMQ_EXPORT void
614 zsock_set_curve_secretkey_bin (void *self, const byte *curve_secretkey);
615 // Get socket option `curve_serverkey`.
617 // Available from libzmq 4.0.0.
618 // Caller owns return value and must destroy it when done.
619 CZMQ_EXPORT char *
620 zsock_curve_serverkey (void *self);
621 // Set socket option `curve_serverkey`.
623 // Available from libzmq 4.0.0.
624 CZMQ_EXPORT void
625 zsock_set_curve_serverkey (void *self, const char *curve_serverkey);
626 // Set socket option `curve_serverkey` from 32-octet binary
628 // Available from libzmq 4.0.0.
629 CZMQ_EXPORT void
630 zsock_set_curve_serverkey_bin (void *self, const byte *curve_serverkey);
631 // Get socket option `gssapi_server`.
633 // Available from libzmq 4.0.0.
634 // Caller owns return value and must destroy it when done.
635 CZMQ_EXPORT int
636 zsock_gssapi_server (void *self);
637 // Set socket option `gssapi_server`.
639 // Available from libzmq 4.0.0.
640 CZMQ_EXPORT void
641 zsock_set_gssapi_server (void *self, int gssapi_server);
642 // Get socket option `gssapi_plaintext`.
644 // Available from libzmq 4.0.0.
645 // Caller owns return value and must destroy it when done.
646 CZMQ_EXPORT int
647 zsock_gssapi_plaintext (void *self);
648 // Set socket option `gssapi_plaintext`.
650 // Available from libzmq 4.0.0.
651 CZMQ_EXPORT void
652 zsock_set_gssapi_plaintext (void *self, int gssapi_plaintext);
653 // Get socket option `gssapi_principal`.
655 // Available from libzmq 4.0.0.
656 // Caller owns return value and must destroy it when done.
657 CZMQ_EXPORT char *
658 zsock_gssapi_principal (void *self);
659 // Set socket option `gssapi_principal`.
661 // Available from libzmq 4.0.0.
662 CZMQ_EXPORT void
663 zsock_set_gssapi_principal (void *self, const char *gssapi_principal);
664 // Get socket option `gssapi_service_principal`.
666 // Available from libzmq 4.0.0.
667 // Caller owns return value and must destroy it when done.
668 CZMQ_EXPORT char *
669 zsock_gssapi_service_principal (void *self);
670 // Set socket option `gssapi_service_principal`.
672 // Available from libzmq 4.0.0.
673 CZMQ_EXPORT void
674 zsock_set_gssapi_service_principal (void *self, const char *gssapi_service_principal);
675 // Get socket option `ipv6`.
677 // Available from libzmq 4.0.0.
678 // Caller owns return value and must destroy it when done.
679 CZMQ_EXPORT int
680 zsock_ipv6 (void *self);
681 // Set socket option `ipv6`.
683 // Available from libzmq 4.0.0.
684 CZMQ_EXPORT void
685 zsock_set_ipv6 (void *self, int ipv6);
686 // Get socket option `immediate`.
688 // Available from libzmq 4.0.0.
689 // Caller owns return value and must destroy it when done.
690 CZMQ_EXPORT int
691 zsock_immediate (void *self);
692 // Set socket option `immediate`.
694 // Available from libzmq 4.0.0.
695 CZMQ_EXPORT void
696 zsock_set_immediate (void *self, int immediate);
697 // Get socket option `sndhwm`.
699 // Available from libzmq 3.0.0.
700 // Caller owns return value and must destroy it when done.
701 CZMQ_EXPORT int
702 zsock_sndhwm (void *self);
703 // Set socket option `sndhwm`.
705 // Available from libzmq 3.0.0.
706 CZMQ_EXPORT void
707 zsock_set_sndhwm (void *self, int sndhwm);
708 // Get socket option `rcvhwm`.
710 // Available from libzmq 3.0.0.
711 // Caller owns return value and must destroy it when done.
712 CZMQ_EXPORT int
713 zsock_rcvhwm (void *self);
714 // Set socket option `rcvhwm`.
716 // Available from libzmq 3.0.0.
717 CZMQ_EXPORT void
718 zsock_set_rcvhwm (void *self, int rcvhwm);
719 // Get socket option `maxmsgsize`.
721 // Available from libzmq 3.0.0.
722 // Caller owns return value and must destroy it when done.
723 CZMQ_EXPORT int
724 zsock_maxmsgsize (void *self);
725 // Set socket option `maxmsgsize`.
727 // Available from libzmq 3.0.0.
728 CZMQ_EXPORT void
729 zsock_set_maxmsgsize (void *self, int maxmsgsize);
730 // Get socket option `multicast_hops`.
732 // Available from libzmq 3.0.0.
733 // Caller owns return value and must destroy it when done.
734 CZMQ_EXPORT int
735 zsock_multicast_hops (void *self);
736 // Set socket option `multicast_hops`.
738 // Available from libzmq 3.0.0.
739 CZMQ_EXPORT void
740 zsock_set_multicast_hops (void *self, int multicast_hops);
741 // Set socket option `xpub_verbose`.
743 // Available from libzmq 3.0.0.
744 CZMQ_EXPORT void
745 zsock_set_xpub_verbose (void *self, int xpub_verbose);
746 // Get socket option `tcp_keepalive`.
748 // Available from libzmq 3.0.0.
749 // Caller owns return value and must destroy it when done.
750 CZMQ_EXPORT int
751 zsock_tcp_keepalive (void *self);
752 // Set socket option `tcp_keepalive`.
754 // Available from libzmq 3.0.0.
755 CZMQ_EXPORT void
756 zsock_set_tcp_keepalive (void *self, int tcp_keepalive);
757 // Get socket option `tcp_keepalive_idle`.
759 // Available from libzmq 3.0.0.
760 // Caller owns return value and must destroy it when done.
761 CZMQ_EXPORT int
762 zsock_tcp_keepalive_idle (void *self);
763 // Set socket option `tcp_keepalive_idle`.
765 // Available from libzmq 3.0.0.
766 CZMQ_EXPORT void
767 zsock_set_tcp_keepalive_idle (void *self, int tcp_keepalive_idle);
768 // Get socket option `tcp_keepalive_cnt`.
770 // Available from libzmq 3.0.0.
771 // Caller owns return value and must destroy it when done.
772 CZMQ_EXPORT int
773 zsock_tcp_keepalive_cnt (void *self);
774 // Set socket option `tcp_keepalive_cnt`.
776 // Available from libzmq 3.0.0.
777 CZMQ_EXPORT void
778 zsock_set_tcp_keepalive_cnt (void *self, int tcp_keepalive_cnt);
779 // Get socket option `tcp_keepalive_intvl`.
781 // Available from libzmq 3.0.0.
782 // Caller owns return value and must destroy it when done.
783 CZMQ_EXPORT int
784 zsock_tcp_keepalive_intvl (void *self);
785 // Set socket option `tcp_keepalive_intvl`.
787 // Available from libzmq 3.0.0.
788 CZMQ_EXPORT void
789 zsock_set_tcp_keepalive_intvl (void *self, int tcp_keepalive_intvl);
790 // Get socket option `tcp_accept_filter`.
792 // Available from libzmq 3.0.0.
793 // Caller owns return value and must destroy it when done.
794 CZMQ_EXPORT char *
795 zsock_tcp_accept_filter (void *self);
796 // Set socket option `tcp_accept_filter`.
798 // Available from libzmq 3.0.0.
799 CZMQ_EXPORT void
800 zsock_set_tcp_accept_filter (void *self, const char *tcp_accept_filter);
801 // Get socket option `last_endpoint`.
803 // Available from libzmq 3.0.0.
804 // Caller owns return value and must destroy it when done.
805 CZMQ_EXPORT char *
806 zsock_last_endpoint (void *self);
807 // Set socket option `router_raw`.
809 // Available from libzmq 3.0.0.
810 CZMQ_EXPORT void
811 zsock_set_router_raw (void *self, int router_raw);
812 // Get socket option `ipv4only`.
814 // Available from libzmq 3.0.0.
815 // Caller owns return value and must destroy it when done.
816 CZMQ_EXPORT int
817 zsock_ipv4only (void *self);
818 // Set socket option `ipv4only`.
820 // Available from libzmq 3.0.0.
821 CZMQ_EXPORT void
822 zsock_set_ipv4only (void *self, int ipv4only);
823 // Set socket option `delay_attach_on_connect`.
825 // Available from libzmq 3.0.0.
826 CZMQ_EXPORT void
827 zsock_set_delay_attach_on_connect (void *self, int delay_attach_on_connect);
828 // Get socket option `hwm`.
830 // Available from libzmq 2.0.0 to 3.0.0.
831 // Caller owns return value and must destroy it when done.
832 CZMQ_EXPORT int
833 zsock_hwm (void *self);
834 // Set socket option `hwm`.
836 // Available from libzmq 2.0.0 to 3.0.0.
837 CZMQ_EXPORT void
838 zsock_set_hwm (void *self, int hwm);
839 // Get socket option `swap`.
841 // Available from libzmq 2.0.0 to 3.0.0.
842 // Caller owns return value and must destroy it when done.
843 CZMQ_EXPORT int
844 zsock_swap (void *self);
845 // Set socket option `swap`.
847 // Available from libzmq 2.0.0 to 3.0.0.
848 CZMQ_EXPORT void
849 zsock_set_swap (void *self, int swap);
850 // Get socket option `affinity`.
852 // Available from libzmq 2.0.0.
853 // Caller owns return value and must destroy it when done.
854 CZMQ_EXPORT int
855 zsock_affinity (void *self);
856 // Set socket option `affinity`.
858 // Available from libzmq 2.0.0.
859 CZMQ_EXPORT void
860 zsock_set_affinity (void *self, int affinity);
861 // Get socket option `identity`.
863 // Available from libzmq 2.0.0.
864 // Caller owns return value and must destroy it when done.
865 CZMQ_EXPORT char *
866 zsock_identity (void *self);
867 // Set socket option `identity`.
869 // Available from libzmq 2.0.0.
870 CZMQ_EXPORT void
871 zsock_set_identity (void *self, const char *identity);
872 // Get socket option `rate`.
874 // Available from libzmq 2.0.0.
875 // Caller owns return value and must destroy it when done.
876 CZMQ_EXPORT int
877 zsock_rate (void *self);
878 // Set socket option `rate`.
880 // Available from libzmq 2.0.0.
881 CZMQ_EXPORT void
882 zsock_set_rate (void *self, int rate);
883 // Get socket option `recovery_ivl`.
885 // Available from libzmq 2.0.0.
886 // Caller owns return value and must destroy it when done.
887 CZMQ_EXPORT int
888 zsock_recovery_ivl (void *self);
889 // Set socket option `recovery_ivl`.
891 // Available from libzmq 2.0.0.
892 CZMQ_EXPORT void
893 zsock_set_recovery_ivl (void *self, int recovery_ivl);
894 // Get socket option `recovery_ivl_msec`.
896 // Available from libzmq 2.0.0 to 3.0.0.
897 // Caller owns return value and must destroy it when done.
898 CZMQ_EXPORT int
899 zsock_recovery_ivl_msec (void *self);
900 // Set socket option `recovery_ivl_msec`.
902 // Available from libzmq 2.0.0 to 3.0.0.
903 CZMQ_EXPORT void
904 zsock_set_recovery_ivl_msec (void *self, int recovery_ivl_msec);
905 // Get socket option `mcast_loop`.
907 // Available from libzmq 2.0.0 to 3.0.0.
908 // Caller owns return value and must destroy it when done.
909 CZMQ_EXPORT int
910 zsock_mcast_loop (void *self);
911 // Set socket option `mcast_loop`.
913 // Available from libzmq 2.0.0 to 3.0.0.
914 CZMQ_EXPORT void
915 zsock_set_mcast_loop (void *self, int mcast_loop);
916 // Get socket option `rcvtimeo`.
918 // Available from libzmq 2.2.0.
919 // Caller owns return value and must destroy it when done.
920 CZMQ_EXPORT int
921 zsock_rcvtimeo (void *self);
922 // Set socket option `rcvtimeo`.
924 // Available from libzmq 2.2.0.
925 CZMQ_EXPORT void
926 zsock_set_rcvtimeo (void *self, int rcvtimeo);
927 // Get socket option `sndtimeo`.
929 // Available from libzmq 2.2.0.
930 // Caller owns return value and must destroy it when done.
931 CZMQ_EXPORT int
932 zsock_sndtimeo (void *self);
933 // Set socket option `sndtimeo`.
935 // Available from libzmq 2.2.0.
936 CZMQ_EXPORT void
937 zsock_set_sndtimeo (void *self, int sndtimeo);
938 // Get socket option `sndbuf`.
940 // Available from libzmq 2.0.0.
941 // Caller owns return value and must destroy it when done.
942 CZMQ_EXPORT int
943 zsock_sndbuf (void *self);
944 // Set socket option `sndbuf`.
946 // Available from libzmq 2.0.0.
947 CZMQ_EXPORT void
948 zsock_set_sndbuf (void *self, int sndbuf);
949 // Get socket option `rcvbuf`.
951 // Available from libzmq 2.0.0.
952 // Caller owns return value and must destroy it when done.
953 CZMQ_EXPORT int
954 zsock_rcvbuf (void *self);
955 // Set socket option `rcvbuf`.
957 // Available from libzmq 2.0.0.
958 CZMQ_EXPORT void
959 zsock_set_rcvbuf (void *self, int rcvbuf);
960 // Get socket option `linger`.
962 // Available from libzmq 2.0.0.
963 // Caller owns return value and must destroy it when done.
964 CZMQ_EXPORT int
965 zsock_linger (void *self);
966 // Set socket option `linger`.
968 // Available from libzmq 2.0.0.
969 CZMQ_EXPORT void
970 zsock_set_linger (void *self, int linger);
971 // Get socket option `reconnect_ivl`.
973 // Available from libzmq 2.0.0.
974 // Caller owns return value and must destroy it when done.
975 CZMQ_EXPORT int
976 zsock_reconnect_ivl (void *self);
977 // Set socket option `reconnect_ivl`.
979 // Available from libzmq 2.0.0.
980 CZMQ_EXPORT void
981 zsock_set_reconnect_ivl (void *self, int reconnect_ivl);
982 // Get socket option `reconnect_ivl_max`.
984 // Available from libzmq 2.0.0.
985 // Caller owns return value and must destroy it when done.
986 CZMQ_EXPORT int
987 zsock_reconnect_ivl_max (void *self);
988 // Set socket option `reconnect_ivl_max`.
990 // Available from libzmq 2.0.0.
991 CZMQ_EXPORT void
992 zsock_set_reconnect_ivl_max (void *self, int reconnect_ivl_max);
993 // Get socket option `backlog`.
995 // Available from libzmq 2.0.0.
996 // Caller owns return value and must destroy it when done.
997 CZMQ_EXPORT int
998 zsock_backlog (void *self);
999 // Set socket option `backlog`.
1001 // Available from libzmq 2.0.0.
1002 CZMQ_EXPORT void
1003 zsock_set_backlog (void *self, int backlog);
1004 // Set socket option `subscribe`.
1006 // Available from libzmq 2.0.0.
1007 CZMQ_EXPORT void
1008 zsock_set_subscribe (void *self, const char *subscribe);
1009 // Set socket option `unsubscribe`.
1011 // Available from libzmq 2.0.0.
1012 CZMQ_EXPORT void
1013 zsock_set_unsubscribe (void *self, const char *unsubscribe);
1014 // Get socket option `type`.
1016 // Available from libzmq 2.0.0.
1017 // Caller owns return value and must destroy it when done.
1018 CZMQ_EXPORT int
1019 zsock_type (void *self);
1020 // Get socket option `rcvmore`.
1022 // Available from libzmq 2.0.0.
1023 // Caller owns return value and must destroy it when done.
1024 CZMQ_EXPORT int
1025 zsock_rcvmore (void *self);
1026 // Get socket option `fd`.
1028 // Available from libzmq 2.0.0.
1029 // Caller owns return value and must destroy it when done.
1030 CZMQ_EXPORT SOCKET
1031 zsock_fd (void *self);
1032 // Get socket option `events`.
1034 // Available from libzmq 2.0.0.
1035 // Caller owns return value and must destroy it when done.
1036 CZMQ_EXPORT int
1037 zsock_events (void *self);
1038 // Self test of this class.
1040 CZMQ_EXPORT void
1041 zsock_test (bool verbose);
1042 #ifdef CZMQ_BUILD_DRAFT_API
1044 // *** Draft method, for development use, may change without warning ***
1045 // Create a SERVER socket. Default action is bind.
1046 CZMQ_EXPORT zsock_t *
1047 zsock_new_server (const char *endpoint);
1048 // *** Draft method, for development use, may change without warning ***
1050 // Create a CLIENT socket. Default action is connect.
1051 CZMQ_EXPORT zsock_t *
1052 zsock_new_client (const char *endpoint);
1053 // *** Draft method, for development use, may change without warning ***
1055 // Create a RADIO socket. Default action is bind.
1056 CZMQ_EXPORT zsock_t *
1057 zsock_new_radio (const char *endpoint);
1058 // *** Draft method, for development use, may change without warning ***
1060 // Create a DISH socket. Default action is connect.
1061 CZMQ_EXPORT zsock_t *
1062 zsock_new_dish (const char *endpoint);
1063 // *** Draft method, for development use, may change without warning ***
1065 // Create a GATHER socket. Default action is bind.
1066 CZMQ_EXPORT zsock_t *
1067 zsock_new_gather (const char *endpoint);
1068 // *** Draft method, for development use, may change without warning ***
1070 // Create a SCATTER socket. Default action is connect.
1071 CZMQ_EXPORT zsock_t *
1072 zsock_new_scatter (const char *endpoint);
1073 // *** Draft method, for development use, may change without warning ***
1075 // Return socket routing ID if any. This returns 0 if the socket is not
1076 // of type ZMQ_SERVER or if no request was already received on it.
1077 CZMQ_EXPORT uint32_t
1078 zsock_routing_id (zsock_t *self);
1079 // *** Draft method, for development use, may change without warning ***
1081 // Set routing ID on socket. The socket MUST be of type ZMQ_SERVER.
1082 // This will be used when sending messages on the socket via the zsock API.
1083 CZMQ_EXPORT void
1084 zsock_set_routing_id (zsock_t *self, uint32_t routing_id);
1085 // *** Draft method, for development use, may change without warning ***
1087 // Join a group for the RADIO-DISH pattern. Call only on ZMQ_DISH.
1088 // Returns 0 if OK, -1 if failed.
1089 CZMQ_EXPORT int
1090 zsock_join (void *self, const char *group);
1091 // *** Draft method, for development use, may change without warning ***
1093 // Leave a group for the RADIO-DISH pattern. Call only on ZMQ_DISH.
1094 // Returns 0 if OK, -1 if failed.
1095 CZMQ_EXPORT int
1096 zsock_leave (void *self, const char *group);
1097 #endif // CZMQ_BUILD_DRAFT_API
1099 Please add '@interface' section in './../src/zsock.c'.
1100
1102 The zsock class wraps the libzmq socket handle (a void *) with a proper
1103 structure that follows the CLASS rules for construction and
1104 destruction. Some zsock methods take a void * "polymorphic" reference,
1105 which can be either a zsock_t or a zactor_t reference, or a libzmq void
1106 *.
1107 Please add @discuss section in ./../src/zsock.c.
1109
1111 From zsock_test method.
1112 zsock_t *writer = zsock_new (ZMQ_PUSH);
1114 assert (writer);
1115 int port = zsock_bind (writer, "tcp://127.0.0.1:*");
1116 assert (port != -1);
1117 assert (zsock_resolve (writer) != writer);
1118 assert (streq (zsock_type_str (writer), "PUSH"));
1119 int rc;
1121 #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (3, 2, 0))
1122 // Check unbind
1123 rc = zsock_unbind (writer, "tcp://127.0.0.1:%d", port);
1124 assert (rc == 0);
1125 // In some cases and especially when running under Valgrind, doing
1127 // a bind immediately after an unbind causes an EADDRINUSE error.
1128 // Even a short sleep allows the OS to release the port for reuse.
1129 zclock_sleep (100);
1130 // Bind again
1132 rc = zsock_bind (writer, "tcp://127.0.0.1:%d", port);
1133 assert (rc == port);
1134 char endpoint [40];
1135 sprintf (endpoint, "tcp://127.0.0.1:%d", port);
1136 assert (streq (zsock_endpoint (writer), endpoint));
1137 #endif
1138 zsock_t *reader = zsock_new (ZMQ_PULL);
1140 assert (reader);
1141 rc = zsock_connect (reader, "tcp://127.0.0.1:%d", port);
1142 assert (rc != -1);
1143 assert (zsock_resolve (reader) != reader);
1144 assert (streq (zsock_type_str (reader), "PULL"));
1145 // Basic Hello, World
1147 zstr_send (writer, "Hello, World");
1148 zmsg_t *msg = zmsg_recv (reader);
1149 assert (msg);
1150 char *string = zmsg_popstr (msg);
1151 assert (streq (string, "Hello, World"));
1152 freen (string);
1153 zmsg_destroy (&msg);
1154 // Test resolve libzmq socket
1156 #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (3, 2, 0))
1157 void *zmq_ctx = zmq_ctx_new ();
1158 #else
1159 void *zmq_ctx = zmq_ctx_new (1);
1160 #endif
1161 assert (zmq_ctx);
1162 void *zmq_sock = zmq_socket (zmq_ctx, ZMQ_PUB);
1163 assert (zmq_sock);
1164 assert (zsock_resolve (zmq_sock) == zmq_sock);
1165 zmq_close (zmq_sock);
1166 zmq_ctx_term (zmq_ctx);
1167 // Test resolve zsock
1169 zsock_t *resolve = zsock_new_pub("@tcp://127.0.0.1:*");
1170 assert (resolve);
1171 assert (zsock_resolve (resolve) == resolve->handle);
1172 zsock_destroy (&resolve);
1173 // Test resolve FD
1175 SOCKET fd = zsock_fd (reader);
1176 assert (zsock_resolve ((void *) &fd) == NULL);
1177 // Test binding to ephemeral ports, sequential and random
1179 port = zsock_bind (writer, "tcp://127.0.0.1:*");
1180 assert (port >= DYNAMIC_FIRST && port <= DYNAMIC_LAST);
1181 port = zsock_bind (writer, "tcp://127.0.0.1:*[50000-]");
1182 assert (port >= 50000 && port <= DYNAMIC_LAST);
1183 port = zsock_bind (writer, "tcp://127.0.0.1:*[-50001]");
1184 assert (port >= DYNAMIC_FIRST && port <= 50001);
1185 port = zsock_bind (writer, "tcp://127.0.0.1:*[60000-60500]");
1186 assert (port >= 60000 && port <= 60500);
1187 port = zsock_bind (writer, "tcp://127.0.0.1:!");
1189 assert (port >= DYNAMIC_FIRST && port <= DYNAMIC_LAST);
1190 port = zsock_bind (writer, "tcp://127.0.0.1:![50000-]");
1191 assert (port >= 50000 && port <= DYNAMIC_LAST);
1192 port = zsock_bind (writer, "tcp://127.0.0.1:![-50001]");
1193 assert (port >= DYNAMIC_FIRST && port <= 50001);
1194 port = zsock_bind (writer, "tcp://127.0.0.1:![60000-60500]");
1195 assert (port >= 60000 && port <= 60500);
1196 // Test zsock_attach method
1198 zsock_t *dealer = zsock_new (ZMQ_DEALER);
1199 assert (dealer);
1200 rc = zsock_attach (dealer, "@inproc://myendpoint,tcp://127.0.0.1:*,inproc://others", true);
1201 assert (rc == 0);
1202 rc = zsock_attach (dealer, "", false);
1203 assert (rc == 0);
1204 rc = zsock_attach (dealer, NULL, true);
1205 assert (rc == 0);
1206 rc = zsock_attach (dealer, ">a,@b, c,, ", false);
1207 assert (rc == -1);
1208 zsock_destroy (&dealer);
1209 // Test zsock_endpoint method
1211 rc = zsock_bind (writer, "inproc://test.%s", "writer");
1212 assert (rc == 0);
1213 assert (streq (zsock_endpoint (writer), "inproc://test.writer"));
1214 // Test error state when connecting to an invalid socket type
1216 // ('txp://' instead of 'tcp://', typo intentional)
1217 rc = zsock_connect (reader, "txp://127.0.0.1:5560");
1218 assert (rc == -1);
1219 // Test signal/wait methods
1221 rc = zsock_signal (writer, 123);
1222 assert (rc == 0);
1223 rc = zsock_wait (reader);
1224 assert (rc == 123);
1225 // Test zsock_send/recv pictures
1227 uint8_t number1 = 123;
1228 uint16_t number2 = 123 * 123;
1229 uint32_t number4 = 123 * 123;
1230 number4 *= 123;
1231 uint32_t number4_MAX = UINT32_MAX;
1232 uint64_t number8 = 123 * 123;
1233 number8 *= 123;
1234 number8 *= 123;
1235 uint64_t number8_MAX = UINT64_MAX;
1236 zchunk_t *chunk = zchunk_new ("HELLO", 5);
1238 assert (chunk);
1239 zframe_t *frame = zframe_new ("WORLD", 5);
1240 assert (frame);
1241 zhashx_t *hash = zhashx_new ();
1242 assert (hash);
1243 zuuid_t *uuid = zuuid_new ();
1244 assert (uuid);
1245 zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
1246 zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
1247 zhashx_insert (hash, "1", "value A");
1248 zhashx_insert (hash, "2", "value B");
1249 char *original = "pointer";
1250 // Test zsock_recv into each supported type
1252 zsock_send (writer, "i124488zsbcfUhp",
1253 -12345, number1, number2, number4, number4_MAX,
1254 number8, number8_MAX,
1255 "This is a string", "ABCDE", 5,
1256 chunk, frame, uuid, hash, original);
1257 char *uuid_str = strdup (zuuid_str (uuid));
1258 zchunk_destroy (&chunk);
1259 zframe_destroy (&frame);
1260 zuuid_destroy (&uuid);
1261 zhashx_destroy (&hash);
1262 int integer;
1264 byte *data;
1265 size_t size;
1266 char *pointer;
1267 number8_MAX = number8 = number4_MAX = number4 = number2 = number1 = 0ULL;
1268 rc = zsock_recv (reader, "i124488zsbcfUhp",
1269 &integer, &number1, &number2, &number4, &number4_MAX,
1270 &number8, &number8_MAX, &string, &data, &size, &chunk,
1271 &frame, &uuid, &hash, &pointer);
1272 assert (rc == 0);
1273 assert (integer == -12345);
1274 assert (number1 == 123);
1275 assert (number2 == 123 * 123);
1276 assert (number4 == 123 * 123 * 123);
1277 assert (number4_MAX == UINT32_MAX);
1278 assert (number8 == 123 * 123 * 123 * 123);
1279 assert (number8_MAX == UINT64_MAX);
1280 assert (streq (string, "This is a string"));
1281 assert (memcmp (data, "ABCDE", 5) == 0);
1282 assert (size == 5);
1283 assert (memcmp (zchunk_data (chunk), "HELLO", 5) == 0);
1284 assert (zchunk_size (chunk) == 5);
1285 assert (streq (uuid_str, zuuid_str (uuid)));
1286 assert (memcmp (zframe_data (frame), "WORLD", 5) == 0);
1287 assert (zframe_size (frame) == 5);
1288 char *value = (char *) zhashx_lookup (hash, "1");
1289 assert (streq (value, "value A"));
1290 value = (char *) zhashx_lookup (hash, "2");
1291 assert (streq (value, "value B"));
1292 assert (original == pointer);
1293 freen (string);
1294 freen (data);
1295 freen (uuid_str);
1296 zframe_destroy (&frame);
1297 zchunk_destroy (&chunk);
1298 zhashx_destroy (&hash);
1299 zuuid_destroy (&uuid);
1300 // Test zsock_recv of short message; this lets us return a failure
1302 // with a status code and then nothing else; the receiver will get
1303 // the status code and NULL/zero for all other values
1304 zsock_send (writer, "i", -1);
1305 zsock_recv (reader, "izsbcfp",
1306 &integer, &string, &data, &size, &chunk, &frame, &pointer);
1307 assert (integer == -1);
1308 assert (string == NULL);
1309 assert (data == NULL);
1310 assert (size == 0);
1311 assert (chunk == NULL);
1312 assert (frame == NULL);
1313 assert (pointer == NULL);
1314 msg = zmsg_new ();
1316 zmsg_addstr (msg, "frame 1");
1317 zmsg_addstr (msg, "frame 2");
1318 zsock_send (writer, "szm", "header", msg);
1319 zmsg_destroy (&msg);
1320 zsock_recv (reader, "szm", &string, &msg);
1322 assert (streq ("header", string));
1324 assert (zmsg_size (msg) == 2);
1325 assert (zframe_streq (zmsg_first (msg), "frame 1"));
1326 assert (zframe_streq (zmsg_next (msg), "frame 2"));
1327 zstr_free (&string);
1328 zmsg_destroy (&msg);
1329 // Test zsock_recv with null arguments
1331 chunk = zchunk_new ("HELLO", 5);
1332 assert (chunk);
1333 frame = zframe_new ("WORLD", 5);
1334 assert (frame);
1335 zsock_send (writer, "izsbcfp",
1336 -12345, "This is a string", "ABCDE", 5, chunk, frame, original);
1337 zframe_destroy (&frame);
1338 zchunk_destroy (&chunk);
1339 zsock_recv (reader, "izsbcfp", &integer, NULL, NULL, NULL, &chunk, NULL, NULL);
1340 assert (integer == -12345);
1341 assert (memcmp (zchunk_data (chunk), "HELLO", 5) == 0);
1342 assert (zchunk_size (chunk) == 5);
1343 zchunk_destroy (&chunk);
1344 // Test zsock_bsend/brecv pictures with binary encoding
1346 frame = zframe_new ("Hello", 5);
1347 chunk = zchunk_new ("World", 5);
1348 msg = zmsg_new ();
1350 zmsg_addstr (msg, "Hello");
1351 zmsg_addstr (msg, "World");
1352 zsock_bsend (writer, "1248sSpcfm",
1354 number1, number2, number4, number8,
1355 "Hello, World",
1356 "Goodbye cruel World!",
1357 original,
1358 chunk, frame, msg);
1359 zchunk_destroy (&chunk);
1360 zframe_destroy (&frame);
1361 zmsg_destroy (&msg);
1362 number8 = number4 = number2 = number1 = 0;
1364 char *longstr;
1365 zsock_brecv (reader, "1248sSpcfm",
1366 &number1, &number2, &number4, &number8,
1367 &string, &longstr,
1368 &pointer,
1369 &chunk, &frame, &msg);
1370 assert (number1 == 123);
1371 assert (number2 == 123 * 123);
1372 assert (number4 == 123 * 123 * 123);
1373 assert (number8 == 123 * 123 * 123 * 123);
1374 assert (streq (string, "Hello, World"));
1375 assert (streq (longstr, "Goodbye cruel World!"));
1376 assert (pointer == original);
1377 zstr_free (&longstr);
1378 zchunk_destroy (&chunk);
1379 zframe_destroy (&frame);
1380 zmsg_destroy (&msg);
1381 #ifdef ZMQ_SERVER
1383 // Test zsock_bsend/brecv pictures with binary encoding on SERVER and CLIENT sockets
1385 zsock_t *server = zsock_new (ZMQ_SERVER);
1386 assert (server);
1387 port = zsock_bind (server, "tcp://127.0.0.1:*");
1388 assert (port != -1);
1389 zsock_t* client = zsock_new (ZMQ_CLIENT);
1390 assert (client);
1391 rc = zsock_connect (client, "tcp://127.0.0.1:%d", port);
1392 assert (rc != -1);
1393 // From client to server
1395 chunk = zchunk_new ("World", 5);
1396 zsock_bsend (client, "1248sSpc",
1397 number1, number2, number4, number8,
1398 "Hello, World",
1399 "Goodbye cruel World!",
1400 original,
1401 chunk);
1402 zchunk_destroy (&chunk);
1403 number8 = number4 = number2 = number1 = 0;
1405 zsock_brecv (server, "1248sSpc",
1406 &number1, &number2, &number4, &number8,
1407 &string, &longstr,
1408 &pointer,
1409 &chunk);
1410 assert (number1 == 123);
1411 assert (number2 == 123 * 123);
1412 assert (number4 == 123 * 123 * 123);
1413 assert (number8 == 123 * 123 * 123 * 123);
1414 assert (streq (string, "Hello, World"));
1415 assert (streq (longstr, "Goodbye cruel World!"));
1416 assert (pointer == original);
1417 assert (zsock_routing_id (server));
1418 zstr_free (&longstr);
1419 zchunk_destroy (&chunk);
1420 // From server to client
1422 chunk = zchunk_new ("World", 5);
1423 zsock_bsend (server, "1248sSpc",
1424 number1, number2, number4, number8,
1425 "Hello, World",
1426 "Goodbye cruel World!",
1427 original,
1428 chunk);
1429 zchunk_destroy (&chunk);
1430 number8 = number4 = number2 = number1 = 0;
1432 zsock_brecv (client, "1248sSpc",
1433 &number1, &number2, &number4, &number8,
1434 &string, &longstr,
1435 &pointer,
1436 &chunk);
1437 assert (number1 == 123);
1438 assert (number2 == 123 * 123);
1439 assert (number4 == 123 * 123 * 123);
1440 assert (number8 == 123 * 123 * 123 * 123);
1441 assert (streq (string, "Hello, World"));
1442 assert (streq (longstr, "Goodbye cruel World!"));
1443 assert (pointer == original);
1444 assert (zsock_routing_id (client) == 0);
1445 zstr_free (&longstr);
1446 zchunk_destroy (&chunk);
1447 zsock_destroy (&client);
1449 zsock_destroy (&server);
1450 #else
1452 errno = 0;
1453 zsock_t* server = zsock_new_server (NULL);
1454 assert(server == NULL);
1455 assert(errno == ENOTSUP);
1456 errno = 0;
1458 zsock_t* client = zsock_new_client (NULL);
1459 assert(client == NULL);
1460 assert(errno == ENOTSUP);
1461 #endif
1462 #ifdef ZMQ_SCATTER
1464 zsock_t* gather = zsock_new_gather ("inproc://test-gather-scatter");
1466 assert (gather);
1467 zsock_t* scatter = zsock_new_scatter ("inproc://test-gather-scatter");
1468 assert (scatter);
1469 rc = zstr_send (scatter, "HELLO");
1471 assert (rc == 0);
1472 char* message;
1474 message = zstr_recv (gather);
1475 assert (streq(message, "HELLO"));
1476 zstr_free (&message);
1477 zsock_destroy (&gather);
1479 zsock_destroy (&scatter);
1480 #else
1481 errno = 0;
1482 zsock_t* scatter = zsock_new_scatter (NULL);
1483 assert(scatter == NULL);
1484 assert(errno == ENOTSUP);
1485 errno = 0;
1487 zsock_t* gather = zsock_new_gather (NULL);
1488 assert(gather == NULL);
1489 assert(errno == ENOTSUP);
1490 #endif
1491 #ifndef ZMQ_RADIO
1493 errno = 0;
1494 zsock_t* radio = zsock_new_radio (NULL);
1495 assert(radio == NULL);
1496 assert(errno == ENOTSUP);
1497 errno = 0;
1499 zsock_t* dish = zsock_new_dish (NULL);
1500 assert(dish == NULL);
1501 assert(errno == ENOTSUP);
1502 errno = 0;
1504 zsock_t* sock = zsock_new_req (NULL); // any supported socket type
1505 rc = zsock_join (sock, "group1");
1506 assert(rc == -1);
1507 assert(errno == ENOTSUP);
1508 errno = 0;
1509 rc = zsock_leave (sock, "group1");
1510 assert(rc == -1);
1511 assert(errno == ENOTSUP);
1512 zsock_destroy (&sock);
1513 #endif
1514 // Check that we can send a zproto format message
1516 zsock_bsend (writer, "1111sS4", 0xAA, 0xA0, 0x02, 0x01, "key", "value", 1234);
1517 zgossip_msg_t *gossip = zgossip_msg_new ();
1518 zgossip_msg_recv (gossip, reader);
1519 assert (zgossip_msg_id (gossip) == ZGOSSIP_MSG_PUBLISH);
1520 zgossip_msg_destroy (&gossip);
1521 zsock_destroy (&reader);
1523 zsock_destroy (&writer);
1524
1527 The czmq manual was written by the authors in the AUTHORS file.
1528
1530 Main web site:
1531 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
1533
1535 Copyright (c) the Contributors as noted in the AUTHORS file. This file
1536 is part of CZMQ, the high-level C binding for 0MQ:
1537 http://czmq.zeromq.org. This Source Code Form is subject to the terms
1538 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
1539 distributed with this file, You can obtain one at
1540 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
1541 distribution.
1542
1544 1. zeromq-dev@lists.zeromq.org
1545 mailto:zeromq-dev@lists.zeromq.org
1546CZMQ 4.1.1 07/24/2019 ZSOCK(3)