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 // l = zlistx_t * (DRAFT)
150 // U = zuuid_t *
151 // p = void * (sends the pointer value, only meaningful over inproc)
152 // m = zmsg_t * (sends all frames in the zmsg)
153 // z = sends zero-sized frame (0 arguments)
154 // u = uint (deprecated)
155 //
156 // Note that s, b, c, and f are encoded the same way and the choice is
157 // offered as a convenience to the sender, which may or may not already
158 // have data in a zchunk or zframe. Does not change or take ownership of
159 // any arguments. Returns 0 if successful, -1 if sending failed for any
160 // reason.
161 CZMQ_EXPORT int
162 zsock_send (void *self, const char *picture, ...);
163 // Send a 'picture' message to the socket (or actor). This is a va_list
165 // version of zsock_send (), so please consult its documentation for the
166 // details.
167 CZMQ_EXPORT int
168 zsock_vsend (void *self, const char *picture, va_list argptr);
169 // Receive a 'picture' message to the socket (or actor). See zsock_send for
171 // the format and meaning of the picture. Returns the picture elements into
172 // a series of pointers as provided by the caller:
173 //
174 // i = int * (stores signed integer)
175 // 4 = uint32_t * (stores 32-bit unsigned integer)
176 // 8 = uint64_t * (stores 64-bit unsigned integer)
177 // s = char ** (allocates new string)
178 // b = byte **, size_t * (2 arguments) (allocates memory)
179 // c = zchunk_t ** (creates zchunk)
180 // f = zframe_t ** (creates zframe)
181 // U = zuuid_t * (creates a zuuid with the data)
182 // h = zhashx_t ** (creates zhashx)
183 // l = zlistx_t ** (creates zlistx) (DRAFT)
184 // p = void ** (stores pointer)
185 // m = zmsg_t ** (creates a zmsg with the remaining frames)
186 // z = null, asserts empty frame (0 arguments)
187 // u = uint * (stores unsigned integer, deprecated)
188 //
189 // Note that zsock_recv creates the returned objects, and the caller must
190 // destroy them when finished with them. The supplied pointers do not need
191 // to be initialized. Returns 0 if successful, or -1 if it failed to recv
192 // a message, in which case the pointers are not modified. When message
193 // frames are truncated (a short message), sets return values to zero/null.
194 // If an argument pointer is NULL, does not store any value (skips it).
195 // An 'n' picture matches an empty frame; if the message does not match,
196 // the method will return -1.
197 CZMQ_EXPORT int
198 zsock_recv (void *self, const char *picture, ...);
199 // Receive a 'picture' message from the socket (or actor). This is a
201 // va_list version of zsock_recv (), so please consult its documentation
202 // for the details.
203 CZMQ_EXPORT int
204 zsock_vrecv (void *self, const char *picture, va_list argptr);
205 // Send a binary encoded 'picture' message to the socket (or actor). This
207 // method is similar to zsock_send, except the arguments are encoded in a
208 // binary format that is compatible with zproto, and is designed to reduce
209 // memory allocations. The pattern argument is a string that defines the
210 // type of each argument. Supports these argument types:
211 //
212 // pattern C type zproto type:
213 // 1 uint8_t type = "number" size = "1"
214 // 2 uint16_t type = "number" size = "2"
215 // 4 uint32_t type = "number" size = "3"
216 // 8 uint64_t type = "number" size = "4"
217 // s char *, 0-255 chars type = "string"
218 // S char *, 0-2^32-1 chars type = "longstr"
219 // c zchunk_t * type = "chunk"
220 // f zframe_t * type = "frame"
221 // u zuuid_t * type = "uuid"
222 // m zmsg_t * type = "msg"
223 // p void *, sends pointer value, only over inproc
224 //
225 // Does not change or take ownership of any arguments. Returns 0 if
226 // successful, -1 if sending failed for any reason.
227 CZMQ_EXPORT int
228 zsock_bsend (void *self, const char *picture, ...);
229 // Receive a binary encoded 'picture' message from the socket (or actor).
231 // This method is similar to zsock_recv, except the arguments are encoded
232 // in a binary format that is compatible with zproto, and is designed to
233 // reduce memory allocations. The pattern argument is a string that defines
234 // the type of each argument. See zsock_bsend for the supported argument
235 // types. All arguments must be pointers; this call sets them to point to
236 // values held on a per-socket basis.
237 // For types 1, 2, 4 and 8 the caller must allocate the memory itself before
238 // calling zsock_brecv.
239 // For types S, the caller must free the value once finished with it, as
240 // zsock_brecv will allocate the buffer.
241 // For type s, the caller must not free the value as it is stored in a
242 // local cache for performance purposes.
243 // For types c, f, u and m the caller must call the appropriate destructor
244 // depending on the object as zsock_brecv will create new objects.
245 // For type p the caller must coordinate with the sender, as it is just a
246 // pointer value being passed.
247 CZMQ_EXPORT int
248 zsock_brecv (void *self, const char *picture, ...);
249 // Set socket to use unbounded pipes (HWM=0); use this in cases when you are
251 // totally certain the message volume can fit in memory. This method works
252 // across all versions of ZeroMQ. Takes a polymorphic socket reference.
253 CZMQ_EXPORT void
254 zsock_set_unbounded (void *self);
255 // Send a signal over a socket. A signal is a short message carrying a
257 // success/failure code (by convention, 0 means OK). Signals are encoded
258 // to be distinguishable from "normal" messages. Accepts a zsock_t or a
259 // zactor_t argument, and returns 0 if successful, -1 if the signal could
260 // not be sent. Takes a polymorphic socket reference.
261 CZMQ_EXPORT int
262 zsock_signal (void *self, byte status);
263 // Wait on a signal. Use this to coordinate between threads, over pipe
265 // pairs. Blocks until the signal is received. Returns -1 on error, 0 or
266 // greater on success. Accepts a zsock_t or a zactor_t as argument.
267 // Takes a polymorphic socket reference.
268 CZMQ_EXPORT int
269 zsock_wait (void *self);
270 // If there is a partial message still waiting on the socket, remove and
272 // discard it. This is useful when reading partial messages, to get specific
273 // message types.
274 CZMQ_EXPORT void
275 zsock_flush (void *self);
276 // Probe the supplied object, and report if it looks like a zsock_t.
278 // Takes a polymorphic socket reference.
279 CZMQ_EXPORT bool
280 zsock_is (void *self);
281 // Probe the supplied reference. If it looks like a zsock_t instance, return
283 // the underlying libzmq socket handle; else if it looks like a file
284 // descriptor, return NULL; else if it looks like a libzmq socket handle,
285 // return the supplied value. Takes a polymorphic socket reference.
286 CZMQ_EXPORT void *
287 zsock_resolve (void *self);
288 // Get socket option `router_notify`.
290 // Available from libzmq 4.3.0.
291 // Caller owns return value and must destroy it when done.
292 CZMQ_EXPORT int
293 zsock_router_notify (void *self);
294 // Set socket option `router_notify`.
296 // Available from libzmq 4.3.0.
297 CZMQ_EXPORT void
298 zsock_set_router_notify (void *self, int router_notify);
299 // Get socket option `multicast_loop`.
301 // Available from libzmq 4.3.0.
302 // Caller owns return value and must destroy it when done.
303 CZMQ_EXPORT int
304 zsock_multicast_loop (void *self);
305 // Set socket option `multicast_loop`.
307 // Available from libzmq 4.3.0.
308 CZMQ_EXPORT void
309 zsock_set_multicast_loop (void *self, int multicast_loop);
310 // Get socket option `metadata`.
312 // Available from libzmq 4.3.0.
313 // Caller owns return value and must destroy it when done.
314 CZMQ_EXPORT char *
315 zsock_metadata (void *self);
316 // Set socket option `metadata`.
318 // Available from libzmq 4.3.0.
319 CZMQ_EXPORT void
320 zsock_set_metadata (void *self, const char *metadata);
321 // Get socket option `loopback_fastpath`.
323 // Available from libzmq 4.3.0.
324 // Caller owns return value and must destroy it when done.
325 CZMQ_EXPORT int
326 zsock_loopback_fastpath (void *self);
327 // Set socket option `loopback_fastpath`.
329 // Available from libzmq 4.3.0.
330 CZMQ_EXPORT void
331 zsock_set_loopback_fastpath (void *self, int loopback_fastpath);
332 // Get socket option `zap_enforce_domain`.
334 // Available from libzmq 4.3.0.
335 // Caller owns return value and must destroy it when done.
336 CZMQ_EXPORT int
337 zsock_zap_enforce_domain (void *self);
338 // Set socket option `zap_enforce_domain`.
340 // Available from libzmq 4.3.0.
341 CZMQ_EXPORT void
342 zsock_set_zap_enforce_domain (void *self, int zap_enforce_domain);
343 // Get socket option `gssapi_principal_nametype`.
345 // Available from libzmq 4.3.0.
346 // Caller owns return value and must destroy it when done.
347 CZMQ_EXPORT int
348 zsock_gssapi_principal_nametype (void *self);
349 // Set socket option `gssapi_principal_nametype`.
351 // Available from libzmq 4.3.0.
352 CZMQ_EXPORT void
353 zsock_set_gssapi_principal_nametype (void *self, int gssapi_principal_nametype);
354 // Get socket option `gssapi_service_principal_nametype`.
356 // Available from libzmq 4.3.0.
357 // Caller owns return value and must destroy it when done.
358 CZMQ_EXPORT int
359 zsock_gssapi_service_principal_nametype (void *self);
360 // Set socket option `gssapi_service_principal_nametype`.
362 // Available from libzmq 4.3.0.
363 CZMQ_EXPORT void
364 zsock_set_gssapi_service_principal_nametype (void *self, int gssapi_service_principal_nametype);
365 // Get socket option `bindtodevice`.
367 // Available from libzmq 4.3.0.
368 // Caller owns return value and must destroy it when done.
369 CZMQ_EXPORT char *
370 zsock_bindtodevice (void *self);
371 // Set socket option `bindtodevice`.
373 // Available from libzmq 4.3.0.
374 CZMQ_EXPORT void
375 zsock_set_bindtodevice (void *self, const char *bindtodevice);
376 // Get socket option `heartbeat_ivl`.
378 // Available from libzmq 4.2.0.
379 // Caller owns return value and must destroy it when done.
380 CZMQ_EXPORT int
381 zsock_heartbeat_ivl (void *self);
382 // Set socket option `heartbeat_ivl`.
384 // Available from libzmq 4.2.0.
385 CZMQ_EXPORT void
386 zsock_set_heartbeat_ivl (void *self, int heartbeat_ivl);
387 // Get socket option `heartbeat_ttl`.
389 // Available from libzmq 4.2.0.
390 // Caller owns return value and must destroy it when done.
391 CZMQ_EXPORT int
392 zsock_heartbeat_ttl (void *self);
393 // Set socket option `heartbeat_ttl`.
395 // Available from libzmq 4.2.0.
396 CZMQ_EXPORT void
397 zsock_set_heartbeat_ttl (void *self, int heartbeat_ttl);
398 // Get socket option `heartbeat_timeout`.
400 // Available from libzmq 4.2.0.
401 // Caller owns return value and must destroy it when done.
402 CZMQ_EXPORT int
403 zsock_heartbeat_timeout (void *self);
404 // Set socket option `heartbeat_timeout`.
406 // Available from libzmq 4.2.0.
407 CZMQ_EXPORT void
408 zsock_set_heartbeat_timeout (void *self, int heartbeat_timeout);
409 // Get socket option `use_fd`.
411 // Available from libzmq 4.2.0.
412 // Caller owns return value and must destroy it when done.
413 CZMQ_EXPORT int
414 zsock_use_fd (void *self);
415 // Set socket option `use_fd`.
417 // Available from libzmq 4.2.0.
418 CZMQ_EXPORT void
419 zsock_set_use_fd (void *self, int use_fd);
420 // Set socket option `xpub_manual`.
422 // Available from libzmq 4.2.0.
423 CZMQ_EXPORT void
424 zsock_set_xpub_manual (void *self, int xpub_manual);
425 // Set socket option `xpub_welcome_msg`.
427 // Available from libzmq 4.2.0.
428 CZMQ_EXPORT void
429 zsock_set_xpub_welcome_msg (void *self, const char *xpub_welcome_msg);
430 // Set socket option `stream_notify`.
432 // Available from libzmq 4.2.0.
433 CZMQ_EXPORT void
434 zsock_set_stream_notify (void *self, int stream_notify);
435 // Get socket option `invert_matching`.
437 // Available from libzmq 4.2.0.
438 // Caller owns return value and must destroy it when done.
439 CZMQ_EXPORT int
440 zsock_invert_matching (void *self);
441 // Set socket option `invert_matching`.
443 // Available from libzmq 4.2.0.
444 CZMQ_EXPORT void
445 zsock_set_invert_matching (void *self, int invert_matching);
446 // Set socket option `xpub_verboser`.
448 // Available from libzmq 4.2.0.
449 CZMQ_EXPORT void
450 zsock_set_xpub_verboser (void *self, int xpub_verboser);
451 // Get socket option `connect_timeout`.
453 // Available from libzmq 4.2.0.
454 // Caller owns return value and must destroy it when done.
455 CZMQ_EXPORT int
456 zsock_connect_timeout (void *self);
457 // Set socket option `connect_timeout`.
459 // Available from libzmq 4.2.0.
460 CZMQ_EXPORT void
461 zsock_set_connect_timeout (void *self, int connect_timeout);
462 // Get socket option `tcp_maxrt`.
464 // Available from libzmq 4.2.0.
465 // Caller owns return value and must destroy it when done.
466 CZMQ_EXPORT int
467 zsock_tcp_maxrt (void *self);
468 // Set socket option `tcp_maxrt`.
470 // Available from libzmq 4.2.0.
471 CZMQ_EXPORT void
472 zsock_set_tcp_maxrt (void *self, int tcp_maxrt);
473 // Get socket option `thread_safe`.
475 // Available from libzmq 4.2.0.
476 // Caller owns return value and must destroy it when done.
477 CZMQ_EXPORT int
478 zsock_thread_safe (void *self);
479 // Get socket option `multicast_maxtpdu`.
481 // Available from libzmq 4.2.0.
482 // Caller owns return value and must destroy it when done.
483 CZMQ_EXPORT int
484 zsock_multicast_maxtpdu (void *self);
485 // Set socket option `multicast_maxtpdu`.
487 // Available from libzmq 4.2.0.
488 CZMQ_EXPORT void
489 zsock_set_multicast_maxtpdu (void *self, int multicast_maxtpdu);
490 // Get socket option `vmci_buffer_size`.
492 // Available from libzmq 4.2.0.
493 // Caller owns return value and must destroy it when done.
494 CZMQ_EXPORT int
495 zsock_vmci_buffer_size (void *self);
496 // Set socket option `vmci_buffer_size`.
498 // Available from libzmq 4.2.0.
499 CZMQ_EXPORT void
500 zsock_set_vmci_buffer_size (void *self, int vmci_buffer_size);
501 // Get socket option `vmci_buffer_min_size`.
503 // Available from libzmq 4.2.0.
504 // Caller owns return value and must destroy it when done.
505 CZMQ_EXPORT int
506 zsock_vmci_buffer_min_size (void *self);
507 // Set socket option `vmci_buffer_min_size`.
509 // Available from libzmq 4.2.0.
510 CZMQ_EXPORT void
511 zsock_set_vmci_buffer_min_size (void *self, int vmci_buffer_min_size);
512 // Get socket option `vmci_buffer_max_size`.
514 // Available from libzmq 4.2.0.
515 // Caller owns return value and must destroy it when done.
516 CZMQ_EXPORT int
517 zsock_vmci_buffer_max_size (void *self);
518 // Set socket option `vmci_buffer_max_size`.
520 // Available from libzmq 4.2.0.
521 CZMQ_EXPORT void
522 zsock_set_vmci_buffer_max_size (void *self, int vmci_buffer_max_size);
523 // Get socket option `vmci_connect_timeout`.
525 // Available from libzmq 4.2.0.
526 // Caller owns return value and must destroy it when done.
527 CZMQ_EXPORT int
528 zsock_vmci_connect_timeout (void *self);
529 // Set socket option `vmci_connect_timeout`.
531 // Available from libzmq 4.2.0.
532 CZMQ_EXPORT void
533 zsock_set_vmci_connect_timeout (void *self, int vmci_connect_timeout);
534 // Get socket option `tos`.
536 // Available from libzmq 4.1.0.
537 // Caller owns return value and must destroy it when done.
538 CZMQ_EXPORT int
539 zsock_tos (void *self);
540 // Set socket option `tos`.
542 // Available from libzmq 4.1.0.
543 CZMQ_EXPORT void
544 zsock_set_tos (void *self, int tos);
545 // Set socket option `router_handover`.
547 // Available from libzmq 4.1.0.
548 CZMQ_EXPORT void
549 zsock_set_router_handover (void *self, int router_handover);
550 // Set socket option `connect_rid`.
552 // Available from libzmq 4.1.0.
553 CZMQ_EXPORT void
554 zsock_set_connect_rid (void *self, const char *connect_rid);
555 // Set socket option `connect_rid` from 32-octet binary
557 // Available from libzmq 4.1.0.
558 CZMQ_EXPORT void
559 zsock_set_connect_rid_bin (void *self, const byte *connect_rid);
560 // Get socket option `handshake_ivl`.
562 // Available from libzmq 4.1.0.
563 // Caller owns return value and must destroy it when done.
564 CZMQ_EXPORT int
565 zsock_handshake_ivl (void *self);
566 // Set socket option `handshake_ivl`.
568 // Available from libzmq 4.1.0.
569 CZMQ_EXPORT void
570 zsock_set_handshake_ivl (void *self, int handshake_ivl);
571 // Get socket option `socks_proxy`.
573 // Available from libzmq 4.1.0.
574 // Caller owns return value and must destroy it when done.
575 CZMQ_EXPORT char *
576 zsock_socks_proxy (void *self);
577 // Set socket option `socks_proxy`.
579 // Available from libzmq 4.1.0.
580 CZMQ_EXPORT void
581 zsock_set_socks_proxy (void *self, const char *socks_proxy);
582 // Set socket option `xpub_nodrop`.
584 // Available from libzmq 4.1.0.
585 CZMQ_EXPORT void
586 zsock_set_xpub_nodrop (void *self, int xpub_nodrop);
587 // Set socket option `router_mandatory`.
589 // Available from libzmq 4.0.0.
590 CZMQ_EXPORT void
591 zsock_set_router_mandatory (void *self, int router_mandatory);
592 // Set socket option `probe_router`.
594 // Available from libzmq 4.0.0.
595 CZMQ_EXPORT void
596 zsock_set_probe_router (void *self, int probe_router);
597 // Set socket option `req_relaxed`.
599 // Available from libzmq 4.0.0.
600 CZMQ_EXPORT void
601 zsock_set_req_relaxed (void *self, int req_relaxed);
602 // Set socket option `req_correlate`.
604 // Available from libzmq 4.0.0.
605 CZMQ_EXPORT void
606 zsock_set_req_correlate (void *self, int req_correlate);
607 // Set socket option `conflate`.
609 // Available from libzmq 4.0.0.
610 CZMQ_EXPORT void
611 zsock_set_conflate (void *self, int conflate);
612 // Get socket option `zap_domain`.
614 // Available from libzmq 4.0.0.
615 // Caller owns return value and must destroy it when done.
616 CZMQ_EXPORT char *
617 zsock_zap_domain (void *self);
618 // Set socket option `zap_domain`.
620 // Available from libzmq 4.0.0.
621 CZMQ_EXPORT void
622 zsock_set_zap_domain (void *self, const char *zap_domain);
623 // Get socket option `mechanism`.
625 // Available from libzmq 4.0.0.
626 // Caller owns return value and must destroy it when done.
627 CZMQ_EXPORT int
628 zsock_mechanism (void *self);
629 // Get socket option `plain_server`.
631 // Available from libzmq 4.0.0.
632 // Caller owns return value and must destroy it when done.
633 CZMQ_EXPORT int
634 zsock_plain_server (void *self);
635 // Set socket option `plain_server`.
637 // Available from libzmq 4.0.0.
638 CZMQ_EXPORT void
639 zsock_set_plain_server (void *self, int plain_server);
640 // Get socket option `plain_username`.
642 // Available from libzmq 4.0.0.
643 // Caller owns return value and must destroy it when done.
644 CZMQ_EXPORT char *
645 zsock_plain_username (void *self);
646 // Set socket option `plain_username`.
648 // Available from libzmq 4.0.0.
649 CZMQ_EXPORT void
650 zsock_set_plain_username (void *self, const char *plain_username);
651 // Get socket option `plain_password`.
653 // Available from libzmq 4.0.0.
654 // Caller owns return value and must destroy it when done.
655 CZMQ_EXPORT char *
656 zsock_plain_password (void *self);
657 // Set socket option `plain_password`.
659 // Available from libzmq 4.0.0.
660 CZMQ_EXPORT void
661 zsock_set_plain_password (void *self, const char *plain_password);
662 // Get socket option `curve_server`.
664 // Available from libzmq 4.0.0.
665 // Caller owns return value and must destroy it when done.
666 CZMQ_EXPORT int
667 zsock_curve_server (void *self);
668 // Set socket option `curve_server`.
670 // Available from libzmq 4.0.0.
671 CZMQ_EXPORT void
672 zsock_set_curve_server (void *self, int curve_server);
673 // Get socket option `curve_publickey`.
675 // Available from libzmq 4.0.0.
676 // Caller owns return value and must destroy it when done.
677 CZMQ_EXPORT char *
678 zsock_curve_publickey (void *self);
679 // Set socket option `curve_publickey`.
681 // Available from libzmq 4.0.0.
682 CZMQ_EXPORT void
683 zsock_set_curve_publickey (void *self, const char *curve_publickey);
684 // Set socket option `curve_publickey` from 32-octet binary
686 // Available from libzmq 4.0.0.
687 CZMQ_EXPORT void
688 zsock_set_curve_publickey_bin (void *self, const byte *curve_publickey);
689 // Get socket option `curve_secretkey`.
691 // Available from libzmq 4.0.0.
692 // Caller owns return value and must destroy it when done.
693 CZMQ_EXPORT char *
694 zsock_curve_secretkey (void *self);
695 // Set socket option `curve_secretkey`.
697 // Available from libzmq 4.0.0.
698 CZMQ_EXPORT void
699 zsock_set_curve_secretkey (void *self, const char *curve_secretkey);
700 // Set socket option `curve_secretkey` from 32-octet binary
702 // Available from libzmq 4.0.0.
703 CZMQ_EXPORT void
704 zsock_set_curve_secretkey_bin (void *self, const byte *curve_secretkey);
705 // Get socket option `curve_serverkey`.
707 // Available from libzmq 4.0.0.
708 // Caller owns return value and must destroy it when done.
709 CZMQ_EXPORT char *
710 zsock_curve_serverkey (void *self);
711 // Set socket option `curve_serverkey`.
713 // Available from libzmq 4.0.0.
714 CZMQ_EXPORT void
715 zsock_set_curve_serverkey (void *self, const char *curve_serverkey);
716 // Set socket option `curve_serverkey` from 32-octet binary
718 // Available from libzmq 4.0.0.
719 CZMQ_EXPORT void
720 zsock_set_curve_serverkey_bin (void *self, const byte *curve_serverkey);
721 // Get socket option `gssapi_server`.
723 // Available from libzmq 4.0.0.
724 // Caller owns return value and must destroy it when done.
725 CZMQ_EXPORT int
726 zsock_gssapi_server (void *self);
727 // Set socket option `gssapi_server`.
729 // Available from libzmq 4.0.0.
730 CZMQ_EXPORT void
731 zsock_set_gssapi_server (void *self, int gssapi_server);
732 // Get socket option `gssapi_plaintext`.
734 // Available from libzmq 4.0.0.
735 // Caller owns return value and must destroy it when done.
736 CZMQ_EXPORT int
737 zsock_gssapi_plaintext (void *self);
738 // Set socket option `gssapi_plaintext`.
740 // Available from libzmq 4.0.0.
741 CZMQ_EXPORT void
742 zsock_set_gssapi_plaintext (void *self, int gssapi_plaintext);
743 // Get socket option `gssapi_principal`.
745 // Available from libzmq 4.0.0.
746 // Caller owns return value and must destroy it when done.
747 CZMQ_EXPORT char *
748 zsock_gssapi_principal (void *self);
749 // Set socket option `gssapi_principal`.
751 // Available from libzmq 4.0.0.
752 CZMQ_EXPORT void
753 zsock_set_gssapi_principal (void *self, const char *gssapi_principal);
754 // Get socket option `gssapi_service_principal`.
756 // Available from libzmq 4.0.0.
757 // Caller owns return value and must destroy it when done.
758 CZMQ_EXPORT char *
759 zsock_gssapi_service_principal (void *self);
760 // Set socket option `gssapi_service_principal`.
762 // Available from libzmq 4.0.0.
763 CZMQ_EXPORT void
764 zsock_set_gssapi_service_principal (void *self, const char *gssapi_service_principal);
765 // Get socket option `ipv6`.
767 // Available from libzmq 4.0.0.
768 // Caller owns return value and must destroy it when done.
769 CZMQ_EXPORT int
770 zsock_ipv6 (void *self);
771 // Set socket option `ipv6`.
773 // Available from libzmq 4.0.0.
774 CZMQ_EXPORT void
775 zsock_set_ipv6 (void *self, int ipv6);
776 // Get socket option `immediate`.
778 // Available from libzmq 4.0.0.
779 // Caller owns return value and must destroy it when done.
780 CZMQ_EXPORT int
781 zsock_immediate (void *self);
782 // Set socket option `immediate`.
784 // Available from libzmq 4.0.0.
785 CZMQ_EXPORT void
786 zsock_set_immediate (void *self, int immediate);
787 // Get socket option `sndhwm`.
789 // Available from libzmq 3.0.0.
790 // Caller owns return value and must destroy it when done.
791 CZMQ_EXPORT int
792 zsock_sndhwm (void *self);
793 // Set socket option `sndhwm`.
795 // Available from libzmq 3.0.0.
796 CZMQ_EXPORT void
797 zsock_set_sndhwm (void *self, int sndhwm);
798 // Get socket option `rcvhwm`.
800 // Available from libzmq 3.0.0.
801 // Caller owns return value and must destroy it when done.
802 CZMQ_EXPORT int
803 zsock_rcvhwm (void *self);
804 // Set socket option `rcvhwm`.
806 // Available from libzmq 3.0.0.
807 CZMQ_EXPORT void
808 zsock_set_rcvhwm (void *self, int rcvhwm);
809 // Get socket option `maxmsgsize`.
811 // Available from libzmq 3.0.0.
812 // Caller owns return value and must destroy it when done.
813 CZMQ_EXPORT int
814 zsock_maxmsgsize (void *self);
815 // Set socket option `maxmsgsize`.
817 // Available from libzmq 3.0.0.
818 CZMQ_EXPORT void
819 zsock_set_maxmsgsize (void *self, int maxmsgsize);
820 // Get socket option `multicast_hops`.
822 // Available from libzmq 3.0.0.
823 // Caller owns return value and must destroy it when done.
824 CZMQ_EXPORT int
825 zsock_multicast_hops (void *self);
826 // Set socket option `multicast_hops`.
828 // Available from libzmq 3.0.0.
829 CZMQ_EXPORT void
830 zsock_set_multicast_hops (void *self, int multicast_hops);
831 // Set socket option `xpub_verbose`.
833 // Available from libzmq 3.0.0.
834 CZMQ_EXPORT void
835 zsock_set_xpub_verbose (void *self, int xpub_verbose);
836 // Get socket option `tcp_keepalive`.
838 // Available from libzmq 3.0.0.
839 // Caller owns return value and must destroy it when done.
840 CZMQ_EXPORT int
841 zsock_tcp_keepalive (void *self);
842 // Set socket option `tcp_keepalive`.
844 // Available from libzmq 3.0.0.
845 CZMQ_EXPORT void
846 zsock_set_tcp_keepalive (void *self, int tcp_keepalive);
847 // Get socket option `tcp_keepalive_idle`.
849 // Available from libzmq 3.0.0.
850 // Caller owns return value and must destroy it when done.
851 CZMQ_EXPORT int
852 zsock_tcp_keepalive_idle (void *self);
853 // Set socket option `tcp_keepalive_idle`.
855 // Available from libzmq 3.0.0.
856 CZMQ_EXPORT void
857 zsock_set_tcp_keepalive_idle (void *self, int tcp_keepalive_idle);
858 // Get socket option `tcp_keepalive_cnt`.
860 // Available from libzmq 3.0.0.
861 // Caller owns return value and must destroy it when done.
862 CZMQ_EXPORT int
863 zsock_tcp_keepalive_cnt (void *self);
864 // Set socket option `tcp_keepalive_cnt`.
866 // Available from libzmq 3.0.0.
867 CZMQ_EXPORT void
868 zsock_set_tcp_keepalive_cnt (void *self, int tcp_keepalive_cnt);
869 // Get socket option `tcp_keepalive_intvl`.
871 // Available from libzmq 3.0.0.
872 // Caller owns return value and must destroy it when done.
873 CZMQ_EXPORT int
874 zsock_tcp_keepalive_intvl (void *self);
875 // Set socket option `tcp_keepalive_intvl`.
877 // Available from libzmq 3.0.0.
878 CZMQ_EXPORT void
879 zsock_set_tcp_keepalive_intvl (void *self, int tcp_keepalive_intvl);
880 // Get socket option `tcp_accept_filter`.
882 // Available from libzmq 3.0.0.
883 // Caller owns return value and must destroy it when done.
884 CZMQ_EXPORT char *
885 zsock_tcp_accept_filter (void *self);
886 // Set socket option `tcp_accept_filter`.
888 // Available from libzmq 3.0.0.
889 CZMQ_EXPORT void
890 zsock_set_tcp_accept_filter (void *self, const char *tcp_accept_filter);
891 // Get socket option `last_endpoint`.
893 // Available from libzmq 3.0.0.
894 // Caller owns return value and must destroy it when done.
895 CZMQ_EXPORT char *
896 zsock_last_endpoint (void *self);
897 // Set socket option `router_raw`.
899 // Available from libzmq 3.0.0.
900 CZMQ_EXPORT void
901 zsock_set_router_raw (void *self, int router_raw);
902 // Get socket option `ipv4only`.
904 // Available from libzmq 3.0.0.
905 // Caller owns return value and must destroy it when done.
906 CZMQ_EXPORT int
907 zsock_ipv4only (void *self);
908 // Set socket option `ipv4only`.
910 // Available from libzmq 3.0.0.
911 CZMQ_EXPORT void
912 zsock_set_ipv4only (void *self, int ipv4only);
913 // Set socket option `delay_attach_on_connect`.
915 // Available from libzmq 3.0.0.
916 CZMQ_EXPORT void
917 zsock_set_delay_attach_on_connect (void *self, int delay_attach_on_connect);
918 // Get socket option `hwm`.
920 // Available from libzmq 2.0.0 to 3.0.0.
921 // Caller owns return value and must destroy it when done.
922 CZMQ_EXPORT int
923 zsock_hwm (void *self);
924 // Set socket option `hwm`.
926 // Available from libzmq 2.0.0 to 3.0.0.
927 CZMQ_EXPORT void
928 zsock_set_hwm (void *self, int hwm);
929 // Get socket option `swap`.
931 // Available from libzmq 2.0.0 to 3.0.0.
932 // Caller owns return value and must destroy it when done.
933 CZMQ_EXPORT int
934 zsock_swap (void *self);
935 // Set socket option `swap`.
937 // Available from libzmq 2.0.0 to 3.0.0.
938 CZMQ_EXPORT void
939 zsock_set_swap (void *self, int swap);
940 // Get socket option `affinity`.
942 // Available from libzmq 2.0.0.
943 // Caller owns return value and must destroy it when done.
944 CZMQ_EXPORT int
945 zsock_affinity (void *self);
946 // Set socket option `affinity`.
948 // Available from libzmq 2.0.0.
949 CZMQ_EXPORT void
950 zsock_set_affinity (void *self, int affinity);
951 // Get socket option `identity`.
953 // Available from libzmq 2.0.0.
954 // Caller owns return value and must destroy it when done.
955 CZMQ_EXPORT char *
956 zsock_identity (void *self);
957 // Set socket option `identity`.
959 // Available from libzmq 2.0.0.
960 CZMQ_EXPORT void
961 zsock_set_identity (void *self, const char *identity);
962 // Get socket option `rate`.
964 // Available from libzmq 2.0.0.
965 // Caller owns return value and must destroy it when done.
966 CZMQ_EXPORT int
967 zsock_rate (void *self);
968 // Set socket option `rate`.
970 // Available from libzmq 2.0.0.
971 CZMQ_EXPORT void
972 zsock_set_rate (void *self, int rate);
973 // Get socket option `recovery_ivl`.
975 // Available from libzmq 2.0.0.
976 // Caller owns return value and must destroy it when done.
977 CZMQ_EXPORT int
978 zsock_recovery_ivl (void *self);
979 // Set socket option `recovery_ivl`.
981 // Available from libzmq 2.0.0.
982 CZMQ_EXPORT void
983 zsock_set_recovery_ivl (void *self, int recovery_ivl);
984 // Get socket option `recovery_ivl_msec`.
986 // Available from libzmq 2.0.0 to 3.0.0.
987 // Caller owns return value and must destroy it when done.
988 CZMQ_EXPORT int
989 zsock_recovery_ivl_msec (void *self);
990 // Set socket option `recovery_ivl_msec`.
992 // Available from libzmq 2.0.0 to 3.0.0.
993 CZMQ_EXPORT void
994 zsock_set_recovery_ivl_msec (void *self, int recovery_ivl_msec);
995 // Get socket option `mcast_loop`.
997 // Available from libzmq 2.0.0 to 3.0.0.
998 // Caller owns return value and must destroy it when done.
999 CZMQ_EXPORT int
1000 zsock_mcast_loop (void *self);
1001 // Set socket option `mcast_loop`.
1003 // Available from libzmq 2.0.0 to 3.0.0.
1004 CZMQ_EXPORT void
1005 zsock_set_mcast_loop (void *self, int mcast_loop);
1006 // Get socket option `rcvtimeo`.
1008 // Available from libzmq 2.2.0.
1009 // Caller owns return value and must destroy it when done.
1010 CZMQ_EXPORT int
1011 zsock_rcvtimeo (void *self);
1012 // Set socket option `rcvtimeo`.
1014 // Available from libzmq 2.2.0.
1015 CZMQ_EXPORT void
1016 zsock_set_rcvtimeo (void *self, int rcvtimeo);
1017 // Get socket option `sndtimeo`.
1019 // Available from libzmq 2.2.0.
1020 // Caller owns return value and must destroy it when done.
1021 CZMQ_EXPORT int
1022 zsock_sndtimeo (void *self);
1023 // Set socket option `sndtimeo`.
1025 // Available from libzmq 2.2.0.
1026 CZMQ_EXPORT void
1027 zsock_set_sndtimeo (void *self, int sndtimeo);
1028 // Get socket option `sndbuf`.
1030 // Available from libzmq 2.0.0.
1031 // Caller owns return value and must destroy it when done.
1032 CZMQ_EXPORT int
1033 zsock_sndbuf (void *self);
1034 // Set socket option `sndbuf`.
1036 // Available from libzmq 2.0.0.
1037 CZMQ_EXPORT void
1038 zsock_set_sndbuf (void *self, int sndbuf);
1039 // Get socket option `rcvbuf`.
1041 // Available from libzmq 2.0.0.
1042 // Caller owns return value and must destroy it when done.
1043 CZMQ_EXPORT int
1044 zsock_rcvbuf (void *self);
1045 // Set socket option `rcvbuf`.
1047 // Available from libzmq 2.0.0.
1048 CZMQ_EXPORT void
1049 zsock_set_rcvbuf (void *self, int rcvbuf);
1050 // Get socket option `linger`.
1052 // Available from libzmq 2.0.0.
1053 // Caller owns return value and must destroy it when done.
1054 CZMQ_EXPORT int
1055 zsock_linger (void *self);
1056 // Set socket option `linger`.
1058 // Available from libzmq 2.0.0.
1059 CZMQ_EXPORT void
1060 zsock_set_linger (void *self, int linger);
1061 // Get socket option `reconnect_ivl`.
1063 // Available from libzmq 2.0.0.
1064 // Caller owns return value and must destroy it when done.
1065 CZMQ_EXPORT int
1066 zsock_reconnect_ivl (void *self);
1067 // Set socket option `reconnect_ivl`.
1069 // Available from libzmq 2.0.0.
1070 CZMQ_EXPORT void
1071 zsock_set_reconnect_ivl (void *self, int reconnect_ivl);
1072 // Get socket option `reconnect_ivl_max`.
1074 // Available from libzmq 2.0.0.
1075 // Caller owns return value and must destroy it when done.
1076 CZMQ_EXPORT int
1077 zsock_reconnect_ivl_max (void *self);
1078 // Set socket option `reconnect_ivl_max`.
1080 // Available from libzmq 2.0.0.
1081 CZMQ_EXPORT void
1082 zsock_set_reconnect_ivl_max (void *self, int reconnect_ivl_max);
1083 // Get socket option `backlog`.
1085 // Available from libzmq 2.0.0.
1086 // Caller owns return value and must destroy it when done.
1087 CZMQ_EXPORT int
1088 zsock_backlog (void *self);
1089 // Set socket option `backlog`.
1091 // Available from libzmq 2.0.0.
1092 CZMQ_EXPORT void
1093 zsock_set_backlog (void *self, int backlog);
1094 // Set socket option `subscribe`.
1096 // Available from libzmq 2.0.0.
1097 CZMQ_EXPORT void
1098 zsock_set_subscribe (void *self, const char *subscribe);
1099 // Set socket option `unsubscribe`.
1101 // Available from libzmq 2.0.0.
1102 CZMQ_EXPORT void
1103 zsock_set_unsubscribe (void *self, const char *unsubscribe);
1104 // Get socket option `type`.
1106 // Available from libzmq 2.0.0.
1107 // Caller owns return value and must destroy it when done.
1108 CZMQ_EXPORT int
1109 zsock_type (void *self);
1110 // Get socket option `rcvmore`.
1112 // Available from libzmq 2.0.0.
1113 // Caller owns return value and must destroy it when done.
1114 CZMQ_EXPORT int
1115 zsock_rcvmore (void *self);
1116 // Get socket option `fd`.
1118 // Available from libzmq 2.0.0.
1119 // Caller owns return value and must destroy it when done.
1120 CZMQ_EXPORT SOCKET
1121 zsock_fd (void *self);
1122 // Get socket option `events`.
1124 // Available from libzmq 2.0.0.
1125 // Caller owns return value and must destroy it when done.
1126 CZMQ_EXPORT int
1127 zsock_events (void *self);
1128 // Self test of this class.
1130 CZMQ_EXPORT void
1131 zsock_test (bool verbose);
1132 #ifdef CZMQ_BUILD_DRAFT_API
1134 // *** Draft method, for development use, may change without warning ***
1135 // Create a SERVER socket. Default action is bind.
1136 CZMQ_EXPORT zsock_t *
1137 zsock_new_server (const char *endpoint);
1138 // *** Draft method, for development use, may change without warning ***
1140 // Create a CLIENT socket. Default action is connect.
1141 CZMQ_EXPORT zsock_t *
1142 zsock_new_client (const char *endpoint);
1143 // *** Draft method, for development use, may change without warning ***
1145 // Create a RADIO socket. Default action is bind.
1146 CZMQ_EXPORT zsock_t *
1147 zsock_new_radio (const char *endpoint);
1148 // *** Draft method, for development use, may change without warning ***
1150 // Create a DISH socket. Default action is connect.
1151 CZMQ_EXPORT zsock_t *
1152 zsock_new_dish (const char *endpoint);
1153 // *** Draft method, for development use, may change without warning ***
1155 // Create a GATHER socket. Default action is bind.
1156 CZMQ_EXPORT zsock_t *
1157 zsock_new_gather (const char *endpoint);
1158 // *** Draft method, for development use, may change without warning ***
1160 // Create a SCATTER socket. Default action is connect.
1161 CZMQ_EXPORT zsock_t *
1162 zsock_new_scatter (const char *endpoint);
1163 // *** Draft method, for development use, may change without warning ***
1165 // Return socket routing ID if any. This returns 0 if the socket is not
1166 // of type ZMQ_SERVER or if no request was already received on it.
1167 CZMQ_EXPORT uint32_t
1168 zsock_routing_id (zsock_t *self);
1169 // *** Draft method, for development use, may change without warning ***
1171 // Set routing ID on socket. The socket MUST be of type ZMQ_SERVER.
1172 // This will be used when sending messages on the socket via the zsock API.
1173 CZMQ_EXPORT void
1174 zsock_set_routing_id (zsock_t *self, uint32_t routing_id);
1175 // *** Draft method, for development use, may change without warning ***
1177 // Join a group for the RADIO-DISH pattern. Call only on ZMQ_DISH.
1178 // Returns 0 if OK, -1 if failed.
1179 CZMQ_EXPORT int
1180 zsock_join (void *self, const char *group);
1181 // *** Draft method, for development use, may change without warning ***
1183 // Leave a group for the RADIO-DISH pattern. Call only on ZMQ_DISH.
1184 // Returns 0 if OK, -1 if failed.
1185 CZMQ_EXPORT int
1186 zsock_leave (void *self, const char *group);
1187 // *** Draft method, for development use, may change without warning ***
1189 // Check whether the socket has available message to read.
1190 CZMQ_EXPORT bool
1191 zsock_has_in (void *self);
1192 #endif // CZMQ_BUILD_DRAFT_API
1194 Please add '@interface' section in './../src/zsock.c'.
1195
1197 The zsock class wraps the libzmq socket handle (a void *) with a proper
1198 structure that follows the CLASS rules for construction and
1199 destruction. Some zsock methods take a void * "polymorphic" reference,
1200 which can be either a zsock_t or a zactor_t reference, or a libzmq void
1201 *.
1202 Please add @discuss section in ./../src/zsock.c.
1204
1206 From zsock_test method.
1207 zsock_t *writer = zsock_new (ZMQ_PUSH);
1209 assert (writer);
1210 int port = zsock_bind (writer, "tcp://127.0.0.1:*");
1211 assert (port != -1);
1212 assert (zsock_resolve (writer) != writer);
1213 assert (streq (zsock_type_str (writer), "PUSH"));
1214 int rc;
1216 #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (3, 2, 0))
1217 // Check unbind
1218 rc = zsock_unbind (writer, "tcp://127.0.0.1:%d", port);
1219 assert (rc == 0);
1220 // In some cases and especially when running under Valgrind, doing
1222 // a bind immediately after an unbind causes an EADDRINUSE error.
1223 // Even a short sleep allows the OS to release the port for reuse.
1224 zclock_sleep (100);
1225 // Bind again
1227 rc = zsock_bind (writer, "tcp://127.0.0.1:%d", port);
1228 assert (rc == port);
1229 char endpoint [40];
1230 sprintf (endpoint, "tcp://127.0.0.1:%d", port);
1231 assert (streq (zsock_endpoint (writer), endpoint));
1232 #endif
1233 zsock_t *reader = zsock_new (ZMQ_PULL);
1235 assert (reader);
1236 rc = zsock_connect (reader, "tcp://127.0.0.1:%d", port);
1237 assert (rc != -1);
1238 assert (zsock_resolve (reader) != reader);
1239 assert (streq (zsock_type_str (reader), "PULL"));
1240 // Basic Hello, World
1242 zstr_send (writer, "Hello, World");
1243 zmsg_t *msg = zmsg_recv (reader);
1244 assert (msg);
1245 char *string = zmsg_popstr (msg);
1246 assert (streq (string, "Hello, World"));
1247 freen (string);
1248 zmsg_destroy (&msg);
1249 // Test resolve libzmq socket
1251 #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (3, 2, 0))
1252 void *zmq_ctx = zmq_ctx_new ();
1253 #else
1254 void *zmq_ctx = zmq_ctx_new (1);
1255 #endif
1256 assert (zmq_ctx);
1257 void *zmq_sock = zmq_socket (zmq_ctx, ZMQ_PUB);
1258 assert (zmq_sock);
1259 assert (zsock_resolve (zmq_sock) == zmq_sock);
1260 zmq_close (zmq_sock);
1261 zmq_ctx_term (zmq_ctx);
1262 // Test resolve zsock
1264 zsock_t *resolve = zsock_new_pub("@tcp://127.0.0.1:*");
1265 assert (resolve);
1266 assert (zsock_resolve (resolve) == resolve->handle);
1267 zsock_destroy (&resolve);
1268 // Test resolve FD
1270 SOCKET fd = zsock_fd (reader);
1271 assert (zsock_resolve ((void *) &fd) == NULL);
1272 // Test binding to ephemeral ports, sequential and random
1274 port = zsock_bind (writer, "tcp://127.0.0.1:*");
1275 assert (port >= DYNAMIC_FIRST && port <= DYNAMIC_LAST);
1276 port = zsock_bind (writer, "tcp://127.0.0.1:*[50000-]");
1277 assert (port >= 50000 && port <= DYNAMIC_LAST);
1278 port = zsock_bind (writer, "tcp://127.0.0.1:*[-50001]");
1279 assert (port >= DYNAMIC_FIRST && port <= 50001);
1280 port = zsock_bind (writer, "tcp://127.0.0.1:*[60000-60500]");
1281 assert (port >= 60000 && port <= 60500);
1282 port = zsock_bind (writer, "tcp://127.0.0.1:!");
1284 assert (port >= DYNAMIC_FIRST && port <= DYNAMIC_LAST);
1285 port = zsock_bind (writer, "tcp://127.0.0.1:![50000-]");
1286 assert (port >= 50000 && port <= DYNAMIC_LAST);
1287 port = zsock_bind (writer, "tcp://127.0.0.1:![-50001]");
1288 assert (port >= DYNAMIC_FIRST && port <= 50001);
1289 port = zsock_bind (writer, "tcp://127.0.0.1:![60000-60500]");
1290 assert (port >= 60000 && port <= 60500);
1291 // Test zsock_attach method
1293 zsock_t *dealer = zsock_new (ZMQ_DEALER);
1294 assert (dealer);
1295 rc = zsock_attach (dealer, "@inproc://myendpoint,tcp://127.0.0.1:*,inproc://others", true);
1296 assert (rc == 0);
1297 rc = zsock_attach (dealer, "", false);
1298 assert (rc == 0);
1299 rc = zsock_attach (dealer, NULL, true);
1300 assert (rc == 0);
1301 rc = zsock_attach (dealer, ">a,@b, c,, ", false);
1302 assert (rc == -1);
1303 zsock_destroy (&dealer);
1304 // Test zsock_endpoint method
1306 rc = zsock_bind (writer, "inproc://test.%s", "writer");
1307 assert (rc == 0);
1308 assert (streq (zsock_endpoint (writer), "inproc://test.writer"));
1309 // Test error state when connecting to an invalid socket type
1311 // ('txp://' instead of 'tcp://', typo intentional)
1312 rc = zsock_connect (reader, "txp://127.0.0.1:5560");
1313 assert (rc == -1);
1314 // Test signal/wait methods
1316 rc = zsock_signal (writer, 123);
1317 assert (rc == 0);
1318 rc = zsock_wait (reader);
1319 assert (rc == 123);
1320 // Test zsock_send/recv pictures
1322 uint8_t number1 = 123;
1323 uint16_t number2 = 123 * 123;
1324 uint32_t number4 = 123 * 123;
1325 number4 *= 123;
1326 uint32_t number4_MAX = UINT32_MAX;
1327 uint64_t number8 = 123 * 123;
1328 number8 *= 123;
1329 number8 *= 123;
1330 uint64_t number8_MAX = UINT64_MAX;
1331 zchunk_t *chunk = zchunk_new ("HELLO", 5);
1333 assert (chunk);
1334 zframe_t *frame = zframe_new ("WORLD", 5);
1335 assert (frame);
1336 zhashx_t *hash = zhashx_new ();
1337 assert (hash);
1338 #ifdef CZMQ_BUILD_DRAFT_API
1339 zlistx_t *list = zlistx_new ();
1340 assert (list);
1341 #endif
1342 zuuid_t *uuid = zuuid_new ();
1343 assert (uuid);
1344 zhashx_set_destructor (hash, (zhashx_destructor_fn *) zstr_free);
1345 zhashx_set_duplicator (hash, (zhashx_duplicator_fn *) strdup);
1346 zhashx_insert (hash, "1", "value A");
1347 zhashx_insert (hash, "2", "value B");
1348 #ifdef CZMQ_BUILD_DRAFT_API
1349 zlistx_set_destructor (list, (zlistx_destructor_fn *) zstr_free);
1350 zlistx_set_duplicator (list, (zlistx_duplicator_fn *) strdup);
1351 zlistx_add_end (list, "1");
1352 zlistx_add_end (list, "2");
1353 #endif
1354 char *original = "pointer";
1355 // Test zsock_recv into each supported type
1357 #ifdef CZMQ_BUILD_DRAFT_API
1358 zsock_send (writer, "i124488zsbcfUhlp",
1359 #else
1360 zsock_send (writer, "i124488zsbcfUhp",
1361 #endif
1362 -12345, number1, number2, number4, number4_MAX,
1363 number8, number8_MAX,
1364 "This is a string", "ABCDE", 5,
1365 #ifdef CZMQ_BUILD_DRAFT_API
1366 chunk, frame, uuid, hash, list, original);
1367 #else
1368 chunk, frame, uuid, hash, original);
1369 #endif
1370 char *uuid_str = strdup (zuuid_str (uuid));
1371 zchunk_destroy (&chunk);
1372 zframe_destroy (&frame);
1373 zuuid_destroy (&uuid);
1374 zhashx_destroy (&hash);
1375 #ifdef CZMQ_BUILD_DRAFT_API
1376 zlistx_destroy (&list);
1377 #endif
1378 int integer;
1380 byte *data;
1381 size_t size;
1382 char *pointer;
1383 number8_MAX = number8 = number4_MAX = number4 = number2 = number1 = 0ULL;
1384 #ifdef CZMQ_BUILD_DRAFT_API
1385 rc = zsock_recv (reader, "i124488zsbcfUhlp",
1386 #else
1387 rc = zsock_recv (reader, "i124488zsbcfUhp",
1388 #endif
1389 &integer, &number1, &number2, &number4, &number4_MAX,
1390 &number8, &number8_MAX, &string, &data, &size, &chunk,
1391 #ifdef CZMQ_BUILD_DRAFT_API
1392 &frame, &uuid, &hash, &list, &pointer);
1393 #else
1394 &frame, &uuid, &hash, &pointer);
1395 #endif
1396 assert (rc == 0);
1397 assert (integer == -12345);
1398 assert (number1 == 123);
1399 assert (number2 == 123 * 123);
1400 assert (number4 == 123 * 123 * 123);
1401 assert (number4_MAX == UINT32_MAX);
1402 assert (number8 == 123 * 123 * 123 * 123);
1403 assert (number8_MAX == UINT64_MAX);
1404 assert (streq (string, "This is a string"));
1405 assert (memcmp (data, "ABCDE", 5) == 0);
1406 assert (size == 5);
1407 assert (memcmp (zchunk_data (chunk), "HELLO", 5) == 0);
1408 assert (zchunk_size (chunk) == 5);
1409 assert (streq (uuid_str, zuuid_str (uuid)));
1410 assert (memcmp (zframe_data (frame), "WORLD", 5) == 0);
1411 assert (zframe_size (frame) == 5);
1412 char *value = (char *) zhashx_lookup (hash, "1");
1413 assert (streq (value, "value A"));
1414 value = (char *) zhashx_lookup (hash, "2");
1415 assert (streq (value, "value B"));
1416 #ifdef CZMQ_BUILD_DRAFT_API
1417 value = (char *) zlistx_first (list);
1418 assert (streq (value, "1"));
1419 value = (char *) zlistx_last (list);
1420 assert (streq (value, "2"));
1421 #endif
1422 assert (original == pointer);
1423 freen (string);
1424 freen (data);
1425 freen (uuid_str);
1426 zframe_destroy (&frame);
1427 zchunk_destroy (&chunk);
1428 zhashx_destroy (&hash);
1429 #ifdef CZMQ_BUILD_DRAFT_API
1430 zlistx_destroy (&list);
1431 #endif
1432 zuuid_destroy (&uuid);
1433 // Test zsock_recv of short message; this lets us return a failure
1435 // with a status code and then nothing else; the receiver will get
1436 // the status code and NULL/zero for all other values
1437 zsock_send (writer, "i", -1);
1438 zsock_recv (reader, "izsbcfp",
1439 &integer, &string, &data, &size, &chunk, &frame, &pointer);
1440 assert (integer == -1);
1441 assert (string == NULL);
1442 assert (data == NULL);
1443 assert (size == 0);
1444 assert (chunk == NULL);
1445 assert (frame == NULL);
1446 assert (pointer == NULL);
1447 msg = zmsg_new ();
1449 zmsg_addstr (msg, "frame 1");
1450 zmsg_addstr (msg, "frame 2");
1451 zsock_send (writer, "szm", "header", msg);
1452 zmsg_destroy (&msg);
1453 zsock_recv (reader, "szm", &string, &msg);
1455 assert (streq ("header", string));
1457 assert (zmsg_size (msg) == 2);
1458 assert (zframe_streq (zmsg_first (msg), "frame 1"));
1459 assert (zframe_streq (zmsg_next (msg), "frame 2"));
1460 zstr_free (&string);
1461 zmsg_destroy (&msg);
1462 // Test zsock_recv with null arguments
1464 chunk = zchunk_new ("HELLO", 5);
1465 assert (chunk);
1466 frame = zframe_new ("WORLD", 5);
1467 assert (frame);
1468 zsock_send (writer, "izsbcfp",
1469 -12345, "This is a string", "ABCDE", 5, chunk, frame, original);
1470 zframe_destroy (&frame);
1471 zchunk_destroy (&chunk);
1472 zsock_recv (reader, "izsbcfp", &integer, NULL, NULL, NULL, &chunk, NULL, NULL);
1473 assert (integer == -12345);
1474 assert (memcmp (zchunk_data (chunk), "HELLO", 5) == 0);
1475 assert (zchunk_size (chunk) == 5);
1476 zchunk_destroy (&chunk);
1477 // Test zsock_bsend/brecv pictures with binary encoding
1479 frame = zframe_new ("Hello", 5);
1480 chunk = zchunk_new ("World", 5);
1481 msg = zmsg_new ();
1483 zmsg_addstr (msg, "Hello");
1484 zmsg_addstr (msg, "World");
1485 zsock_bsend (writer, "1248sSpcfm",
1487 number1, number2, number4, number8,
1488 "Hello, World",
1489 "Goodbye cruel World!",
1490 original,
1491 chunk, frame, msg);
1492 zchunk_destroy (&chunk);
1493 zframe_destroy (&frame);
1494 zmsg_destroy (&msg);
1495 number8 = number4 = number2 = number1 = 0;
1497 char *longstr;
1498 zsock_brecv (reader, "1248sSpcfm",
1499 &number1, &number2, &number4, &number8,
1500 &string, &longstr,
1501 &pointer,
1502 &chunk, &frame, &msg);
1503 assert (number1 == 123);
1504 assert (number2 == 123 * 123);
1505 assert (number4 == 123 * 123 * 123);
1506 assert (number8 == 123 * 123 * 123 * 123);
1507 assert (streq (string, "Hello, World"));
1508 assert (streq (longstr, "Goodbye cruel World!"));
1509 assert (pointer == original);
1510 zstr_free (&longstr);
1511 zchunk_destroy (&chunk);
1512 zframe_destroy (&frame);
1513 zmsg_destroy (&msg);
1514 #ifdef ZMQ_SERVER
1516 // Test zsock_bsend/brecv pictures with binary encoding on SERVER and CLIENT sockets
1518 zsock_t *server = zsock_new (ZMQ_SERVER);
1519 assert (server);
1520 port = zsock_bind (server, "tcp://127.0.0.1:*");
1521 assert (port != -1);
1522 zsock_t* client = zsock_new (ZMQ_CLIENT);
1523 assert (client);
1524 rc = zsock_connect (client, "tcp://127.0.0.1:%d", port);
1525 assert (rc != -1);
1526 // From client to server
1528 chunk = zchunk_new ("World", 5);
1529 zsock_bsend (client, "1248sSpc",
1530 number1, number2, number4, number8,
1531 "Hello, World",
1532 "Goodbye cruel World!",
1533 original,
1534 chunk);
1535 zchunk_destroy (&chunk);
1536 number8 = number4 = number2 = number1 = 0;
1538 zsock_brecv (server, "1248sSpc",
1539 &number1, &number2, &number4, &number8,
1540 &string, &longstr,
1541 &pointer,
1542 &chunk);
1543 assert (number1 == 123);
1544 assert (number2 == 123 * 123);
1545 assert (number4 == 123 * 123 * 123);
1546 assert (number8 == 123 * 123 * 123 * 123);
1547 assert (streq (string, "Hello, World"));
1548 assert (streq (longstr, "Goodbye cruel World!"));
1549 assert (pointer == original);
1550 assert (zsock_routing_id (server));
1551 zstr_free (&longstr);
1552 zchunk_destroy (&chunk);
1553 // From server to client
1555 chunk = zchunk_new ("World", 5);
1556 zsock_bsend (server, "1248sSpc",
1557 number1, number2, number4, number8,
1558 "Hello, World",
1559 "Goodbye cruel World!",
1560 original,
1561 chunk);
1562 zchunk_destroy (&chunk);
1563 number8 = number4 = number2 = number1 = 0;
1565 zsock_brecv (client, "1248sSpc",
1566 &number1, &number2, &number4, &number8,
1567 &string, &longstr,
1568 &pointer,
1569 &chunk);
1570 assert (number1 == 123);
1571 assert (number2 == 123 * 123);
1572 assert (number4 == 123 * 123 * 123);
1573 assert (number8 == 123 * 123 * 123 * 123);
1574 assert (streq (string, "Hello, World"));
1575 assert (streq (longstr, "Goodbye cruel World!"));
1576 assert (pointer == original);
1577 assert (zsock_routing_id (client) == 0);
1578 zstr_free (&longstr);
1579 zchunk_destroy (&chunk);
1580 zsock_destroy (&client);
1582 zsock_destroy (&server);
1583 #else
1585 errno = 0;
1586 zsock_t* server = zsock_new_server (NULL);
1587 assert(server == NULL);
1588 assert(errno == ENOTSUP);
1589 errno = 0;
1591 zsock_t* client = zsock_new_client (NULL);
1592 assert(client == NULL);
1593 assert(errno == ENOTSUP);
1594 #endif
1595 #ifdef ZMQ_SCATTER
1597 zsock_t* gather = zsock_new_gather ("inproc://test-gather-scatter");
1599 assert (gather);
1600 zsock_t* scatter = zsock_new_scatter ("inproc://test-gather-scatter");
1601 assert (scatter);
1602 rc = zstr_send (scatter, "HELLO");
1604 assert (rc == 0);
1605 char* message;
1607 message = zstr_recv (gather);
1608 assert (streq(message, "HELLO"));
1609 zstr_free (&message);
1610 zsock_destroy (&gather);
1612 zsock_destroy (&scatter);
1613 #else
1614 errno = 0;
1615 zsock_t* scatter = zsock_new_scatter (NULL);
1616 assert(scatter == NULL);
1617 assert(errno == ENOTSUP);
1618 errno = 0;
1620 zsock_t* gather = zsock_new_gather (NULL);
1621 assert(gather == NULL);
1622 assert(errno == ENOTSUP);
1623 #endif
1624 #ifndef ZMQ_RADIO
1626 errno = 0;
1627 zsock_t* radio = zsock_new_radio (NULL);
1628 assert(radio == NULL);
1629 assert(errno == ENOTSUP);
1630 errno = 0;
1632 zsock_t* dish = zsock_new_dish (NULL);
1633 assert(dish == NULL);
1634 assert(errno == ENOTSUP);
1635 errno = 0;
1637 zsock_t* sock = zsock_new_req (NULL); // any supported socket type
1638 rc = zsock_join (sock, "group1");
1639 assert(rc == -1);
1640 assert(errno == ENOTSUP);
1641 errno = 0;
1642 rc = zsock_leave (sock, "group1");
1643 assert(rc == -1);
1644 assert(errno == ENOTSUP);
1645 zsock_destroy (&sock);
1646 #endif
1647 // Check that we can send a zproto format message
1649 zsock_bsend (writer, "1111sS4", 0xAA, 0xA0, 0x02, 0x01, "key", "value", 1234);
1650 zgossip_msg_t *gossip = zgossip_msg_new ();
1651 zgossip_msg_recv (gossip, reader);
1652 assert (zgossip_msg_id (gossip) == ZGOSSIP_MSG_PUBLISH);
1653 zgossip_msg_destroy (&gossip);
1654 zsock_destroy (&reader);
1656 zsock_destroy (&writer);
1657
1660 The czmq manual was written by the authors in the AUTHORS file.
1661
1663 Main web site:
1664 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
1666
1668 Copyright (c) the Contributors as noted in the AUTHORS file. This file
1669 is part of CZMQ, the high-level C binding for 0MQ:
1670 http://czmq.zeromq.org. This Source Code Form is subject to the terms
1671 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
1672 distributed with this file, You can obtain one at
1673 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
1674 distribution.
1675
1677 1. zeromq-dev@lists.zeromq.org
1678 mailto:zeromq-dev@lists.zeromq.org
1679CZMQ 4.2.0 01/28/2020 ZSOCK(3)