zmq.h 14 KB
Newer Older
Martin Sustrik's avatar
Martin Sustrik committed
1
/*
2
    Copyright (c) 2007-2014 Contributors as noted in the AUTHORS file
Martin Sustrik's avatar
Martin Sustrik committed
3 4 5 6

    This file is part of 0MQ.

    0MQ is free software; you can redistribute it and/or modify it under
7
    the terms of the GNU Lesser General Public License as published by
Martin Sustrik's avatar
Martin Sustrik committed
8 9 10 11 12 13
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.

    0MQ is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
    GNU Lesser General Public License for more details.
Martin Sustrik's avatar
Martin Sustrik committed
15

16
    You should have received a copy of the GNU Lesser General Public License
Martin Sustrik's avatar
Martin Sustrik committed
17
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
18 19 20 21 22 23 24 25

    *************************************************************************
    NOTE to contributors. This file comprises the principal public contract
    for ZeroMQ API users (along with zmq_utils.h). Any change to this file
    supplied in a stable release SHOULD not break existing applications.
    In practice this means that the value of constants must not change, and
    that old values may not be reused for new constants.
    *************************************************************************
Martin Sustrik's avatar
Martin Sustrik committed
26 27
*/

Martin Sustrik's avatar
Martin Sustrik committed
28 29
#ifndef __ZMQ_H_INCLUDED__
#define __ZMQ_H_INCLUDED__
Martin Sustrik's avatar
Martin Sustrik committed
30

31 32 33 34 35 36 37 38 39 40
/*  Version macros for compile-time API version detection                     */
#define ZMQ_VERSION_MAJOR 4
#define ZMQ_VERSION_MINOR 1
#define ZMQ_VERSION_PATCH 0

#define ZMQ_MAKE_VERSION(major, minor, patch) \
    ((major) * 10000 + (minor) * 100 + (patch))
#define ZMQ_VERSION \
    ZMQ_MAKE_VERSION(ZMQ_VERSION_MAJOR, ZMQ_VERSION_MINOR, ZMQ_VERSION_PATCH)

Martin Sustrik's avatar
Martin Sustrik committed
41 42 43 44
#ifdef __cplusplus
extern "C" {
#endif

45
#if !defined _WIN32_WCE
46
#include <errno.h>
boris@boressoft.ru's avatar
boris@boressoft.ru committed
47
#endif
Martin Sustrik's avatar
Martin Sustrik committed
48
#include <stddef.h>
49
#include <stdio.h>
50
#if defined _WIN32
51
#include <winsock2.h>
52
#endif
Martin Sustrik's avatar
Martin Sustrik committed
53

54
/*  Handle DSO symbol visibility                                             */
55
#if defined _WIN32
56 57 58
#   if defined ZMQ_STATIC
#       define ZMQ_EXPORT
#   elif defined DLL_EXPORT
59 60 61 62
#       define ZMQ_EXPORT __declspec(dllexport)
#   else
#       define ZMQ_EXPORT __declspec(dllimport)
#   endif
Martin Sustrik's avatar
Martin Sustrik committed
63
#else
64 65 66 67 68 69
#   if defined __SUNPRO_C  || defined __SUNPRO_CC
#       define ZMQ_EXPORT __global
#   elif (defined __GNUC__ && __GNUC__ >= 4) || defined __INTEL_COMPILER
#       define ZMQ_EXPORT __attribute__ ((visibility("default")))
#   else
#       define ZMQ_EXPORT
70
#   endif
Martin Sustrik's avatar
Martin Sustrik committed
71 72
#endif

73 74 75 76 77 78 79 80 81 82
/*  Define integer types needed for event interface                          */
#if defined ZMQ_HAVE_SOLARIS || defined ZMQ_HAVE_OPENVMS
#   include <inttypes.h>
#elif defined _MSC_VER && _MSC_VER < 1600
#   ifndef int32_t
typedef __int32 int32_t;
#   endif
#   ifndef uint16_t
typedef unsigned __int16 uint16_t;
#   endif
83 84 85
#   ifndef uint8_t
typedef unsigned __int8 uint8_t;
#   endif
86 87 88 89 90
#else
#   include <stdint.h>
#endif


91
/******************************************************************************/
92
/*  0MQ errors.                                                               */
93
/******************************************************************************/
94

95
/*  A number random enough not to collide with different errno ranges on      */
96
/*  different OSes. The assumption is that error_t is at least 32-bit type.   */
97 98
#define ZMQ_HAUSNUMERO 156384712

99
/*  On Windows platform some of the standard POSIX errnos are not defined.    */
100 101 102 103 104 105
#ifndef ENOTSUP
#define ENOTSUP (ZMQ_HAUSNUMERO + 1)
#endif
#ifndef EPROTONOSUPPORT
#define EPROTONOSUPPORT (ZMQ_HAUSNUMERO + 2)
#endif
106 107 108 109 110 111 112 113 114 115 116 117
#ifndef ENOBUFS
#define ENOBUFS (ZMQ_HAUSNUMERO + 3)
#endif
#ifndef ENETDOWN
#define ENETDOWN (ZMQ_HAUSNUMERO + 4)
#endif
#ifndef EADDRINUSE
#define EADDRINUSE (ZMQ_HAUSNUMERO + 5)
#endif
#ifndef EADDRNOTAVAIL
#define EADDRNOTAVAIL (ZMQ_HAUSNUMERO + 6)
#endif
malosek's avatar
malosek committed
118 119 120
#ifndef ECONNREFUSED
#define ECONNREFUSED (ZMQ_HAUSNUMERO + 7)
#endif
121 122 123
#ifndef EINPROGRESS
#define EINPROGRESS (ZMQ_HAUSNUMERO + 8)
#endif
124 125 126
#ifndef ENOTSOCK
#define ENOTSOCK (ZMQ_HAUSNUMERO + 9)
#endif
127 128 129
#ifndef EMSGSIZE
#define EMSGSIZE (ZMQ_HAUSNUMERO + 10)
#endif
130
#ifndef EAFNOSUPPORT
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
#define EAFNOSUPPORT (ZMQ_HAUSNUMERO + 11)
#endif
#ifndef ENETUNREACH
#define ENETUNREACH (ZMQ_HAUSNUMERO + 12)
#endif
#ifndef ECONNABORTED
#define ECONNABORTED (ZMQ_HAUSNUMERO + 13)
#endif
#ifndef ECONNRESET
#define ECONNRESET (ZMQ_HAUSNUMERO + 14)
#endif
#ifndef ENOTCONN
#define ENOTCONN (ZMQ_HAUSNUMERO + 15)
#endif
#ifndef ETIMEDOUT
#define ETIMEDOUT (ZMQ_HAUSNUMERO + 16)
147
#endif
Pieter Hintjens's avatar
Pieter Hintjens committed
148
#ifndef EHOSTUNREACH
149
#define EHOSTUNREACH (ZMQ_HAUSNUMERO + 17)
Pieter Hintjens's avatar
Pieter Hintjens committed
150
#endif
151 152 153
#ifndef ENETRESET
#define ENETRESET (ZMQ_HAUSNUMERO + 18)
#endif
154

155
/*  Native 0MQ error codes.                                                   */
156 157
#define EFSM (ZMQ_HAUSNUMERO + 51)
#define ENOCOMPATPROTO (ZMQ_HAUSNUMERO + 52)
158
#define ETERM (ZMQ_HAUSNUMERO + 53)
159
#define EMTHREAD (ZMQ_HAUSNUMERO + 54)
160

161 162 163 164
/*  This function retrieves the errno as it is known to 0MQ library. The goal */
/*  of this function is to make the code 100% portable, including where 0MQ   */
/*  compiled with certain CRT library (on Windows) is linked to an            */
/*  application that uses different CRT library.                              */
165
ZMQ_EXPORT int zmq_errno (void);
166 167

/*  Resolves system errors and 0MQ errors to human-readable string.           */
168 169
ZMQ_EXPORT const char *zmq_strerror (int errnum);

170 171 172
/*  Run-time API version detection                                            */
ZMQ_EXPORT void zmq_version (int *major, int *minor, int *patch);

173 174 175 176 177
/******************************************************************************/
/*  0MQ infrastructure (a.k.a. context) initialisation & termination.         */
/******************************************************************************/

/*  New API                                                                   */
178 179 180
/*  Context options                                                           */
#define ZMQ_IO_THREADS  1
#define ZMQ_MAX_SOCKETS 2
181

182 183
/*  Default for new contexts                                                  */
#define ZMQ_IO_THREADS_DFLT  1
184
#define ZMQ_MAX_SOCKETS_DFLT 1023
185 186

ZMQ_EXPORT void *zmq_ctx_new (void);
187
ZMQ_EXPORT int zmq_ctx_term (void *context);
188
ZMQ_EXPORT int zmq_ctx_shutdown (void *ctx_);
189 190 191 192 193 194
ZMQ_EXPORT int zmq_ctx_set (void *context, int option, int optval);
ZMQ_EXPORT int zmq_ctx_get (void *context, int option);

/*  Old (legacy) API                                                          */
ZMQ_EXPORT void *zmq_init (int io_threads);
ZMQ_EXPORT int zmq_term (void *context);
195
ZMQ_EXPORT int zmq_ctx_destroy (void *context);
196 197


198 199 200
/******************************************************************************/
/*  0MQ message definition.                                                   */
/******************************************************************************/
201

202
typedef struct zmq_msg_t {unsigned char _ [40];} zmq_msg_t;
Martin Sustrik's avatar
Martin Sustrik committed
203

204
typedef void (zmq_free_fn) (void *data, void *hint);
Martin Sustrik's avatar
Martin Sustrik committed
205

206
ZMQ_EXPORT int zmq_msg_init (zmq_msg_t *msg);
207 208
ZMQ_EXPORT int zmq_msg_init_size (zmq_msg_t *msg, size_t size);
ZMQ_EXPORT int zmq_msg_init_data (zmq_msg_t *msg, void *data,
209
    size_t size, zmq_free_fn *ffn, void *hint);
210 211
ZMQ_EXPORT int zmq_msg_send (zmq_msg_t *msg, void *s, int flags);
ZMQ_EXPORT int zmq_msg_recv (zmq_msg_t *msg, void *s, int flags);
212 213 214 215
ZMQ_EXPORT int zmq_msg_close (zmq_msg_t *msg);
ZMQ_EXPORT int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src);
ZMQ_EXPORT int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src);
ZMQ_EXPORT void *zmq_msg_data (zmq_msg_t *msg);
216
ZMQ_EXPORT size_t zmq_msg_size (zmq_msg_t *msg);
217
ZMQ_EXPORT int zmq_msg_more (zmq_msg_t *msg);
218 219 220
ZMQ_EXPORT int zmq_msg_get (zmq_msg_t *msg, int option);
ZMQ_EXPORT int zmq_msg_set (zmq_msg_t *msg, int option, int optval);

221

222 223 224
/******************************************************************************/
/*  0MQ socket definition.                                                    */
/******************************************************************************/
225

226
/*  Socket types.                                                             */
227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242
#define ZMQ_PAIR 0
#define ZMQ_PUB 1
#define ZMQ_SUB 2
#define ZMQ_REQ 3
#define ZMQ_REP 4
#define ZMQ_DEALER 5
#define ZMQ_ROUTER 6
#define ZMQ_PULL 7
#define ZMQ_PUSH 8
#define ZMQ_XPUB 9
#define ZMQ_XSUB 10
#define ZMQ_STREAM 11

/*  Deprecated aliases                                                        */
#define ZMQ_XREQ ZMQ_DEALER
#define ZMQ_XREP ZMQ_ROUTER
243

244
/*  Socket options.                                                           */
245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
#define ZMQ_AFFINITY 4
#define ZMQ_IDENTITY 5
#define ZMQ_SUBSCRIBE 6
#define ZMQ_UNSUBSCRIBE 7
#define ZMQ_RATE 8
#define ZMQ_RECOVERY_IVL 9
#define ZMQ_SNDBUF 11
#define ZMQ_RCVBUF 12
#define ZMQ_RCVMORE 13
#define ZMQ_FD 14
#define ZMQ_EVENTS 15
#define ZMQ_TYPE 16
#define ZMQ_LINGER 17
#define ZMQ_RECONNECT_IVL 18
#define ZMQ_BACKLOG 19
#define ZMQ_RECONNECT_IVL_MAX 21
#define ZMQ_MAXMSGSIZE 22
#define ZMQ_SNDHWM 23
#define ZMQ_RCVHWM 24
#define ZMQ_MULTICAST_HOPS 25
#define ZMQ_RCVTIMEO 27
#define ZMQ_SNDTIMEO 28
#define ZMQ_LAST_ENDPOINT 32
#define ZMQ_ROUTER_MANDATORY 33
#define ZMQ_TCP_KEEPALIVE 34
#define ZMQ_TCP_KEEPALIVE_CNT 35
#define ZMQ_TCP_KEEPALIVE_IDLE 36
#define ZMQ_TCP_KEEPALIVE_INTVL 37
#define ZMQ_TCP_ACCEPT_FILTER 38
#define ZMQ_IMMEDIATE 39
#define ZMQ_XPUB_VERBOSE 40
#define ZMQ_ROUTER_RAW 41
#define ZMQ_IPV6 42
#define ZMQ_MECHANISM 43
#define ZMQ_PLAIN_SERVER 44
#define ZMQ_PLAIN_USERNAME 45
#define ZMQ_PLAIN_PASSWORD 46
#define ZMQ_CURVE_SERVER 47
#define ZMQ_CURVE_PUBLICKEY 48
#define ZMQ_CURVE_SECRETKEY 49
#define ZMQ_CURVE_SERVERKEY 50
#define ZMQ_PROBE_ROUTER 51
#define ZMQ_REQ_CORRELATE 52
#define ZMQ_REQ_RELAXED 53
#define ZMQ_CONFLATE 54
#define ZMQ_ZAP_DOMAIN 55
291
#define ZMQ_ROUTER_HANDOVER 56
292
#define ZMQ_TOS 57
293 294 295
#define ZMQ_IPC_FILTER_PID 58
#define ZMQ_IPC_FILTER_UID 59
#define ZMQ_IPC_FILTER_GID 60
296 297
#define ZMQ_CONNECT_RID 61 

298
/*  Message options                                                           */
299
#define ZMQ_MORE 1
300
#define ZMQ_SRCFD 2
301

302
/*  Send/recv options.                                                        */
303 304
#define ZMQ_DONTWAIT 1
#define ZMQ_SNDMORE 2
305

306
/*  Security mechanisms                                                       */
307 308 309 310 311 312 313 314 315 316
#define ZMQ_NULL 0
#define ZMQ_PLAIN 1
#define ZMQ_CURVE 2

/*  Deprecated options and aliases                                            */
#define ZMQ_IPV4ONLY                31
#define ZMQ_DELAY_ATTACH_ON_CONNECT ZMQ_IMMEDIATE
#define ZMQ_NOBLOCK                 ZMQ_DONTWAIT
#define ZMQ_FAIL_UNROUTABLE         ZMQ_ROUTER_MANDATORY
#define ZMQ_ROUTER_BEHAVIOR         ZMQ_ROUTER_MANDATORY
317

318 319 320 321 322
/******************************************************************************/
/*  0MQ socket events and monitoring                                          */
/******************************************************************************/

/*  Socket transport events (tcp and ipc only)                                */
323 324 325
#define ZMQ_EVENT_CONNECTED 1
#define ZMQ_EVENT_CONNECT_DELAYED 2
#define ZMQ_EVENT_CONNECT_RETRIED 4
326

327 328
#define ZMQ_EVENT_LISTENING 8
#define ZMQ_EVENT_BIND_FAILED 16
329

330 331
#define ZMQ_EVENT_ACCEPTED 32
#define ZMQ_EVENT_ACCEPT_FAILED 64
332

333 334 335 336
#define ZMQ_EVENT_CLOSED 128
#define ZMQ_EVENT_CLOSE_FAILED 256
#define ZMQ_EVENT_DISCONNECTED 512
#define ZMQ_EVENT_MONITOR_STOPPED 1024
337

338 339 340 341
#define ZMQ_EVENT_ALL ( ZMQ_EVENT_CONNECTED | ZMQ_EVENT_CONNECT_DELAYED | \
                        ZMQ_EVENT_CONNECT_RETRIED | ZMQ_EVENT_LISTENING | \
                        ZMQ_EVENT_BIND_FAILED | ZMQ_EVENT_ACCEPTED | \
                        ZMQ_EVENT_ACCEPT_FAILED | ZMQ_EVENT_CLOSED | \
342 343
                        ZMQ_EVENT_CLOSE_FAILED | ZMQ_EVENT_DISCONNECTED | \
                        ZMQ_EVENT_MONITOR_STOPPED)
344

345
/*  Socket event data  */
346
typedef struct {
347 348
    uint16_t event;  // id of the event as bitfield
    int32_t  value ; // value is either error code, fd or reconnect interval
349
} zmq_event_t;
350

351 352 353
ZMQ_EXPORT void *zmq_socket (void *, int type);
ZMQ_EXPORT int zmq_close (void *s);
ZMQ_EXPORT int zmq_setsockopt (void *s, int option, const void *optval,
354
    size_t optvallen);
355
ZMQ_EXPORT int zmq_getsockopt (void *s, int option, void *optval,
356
    size_t *optvallen);
357 358
ZMQ_EXPORT int zmq_bind (void *s, const char *addr);
ZMQ_EXPORT int zmq_connect (void *s, const char *addr);
359 360
ZMQ_EXPORT int zmq_unbind (void *s, const char *addr);
ZMQ_EXPORT int zmq_disconnect (void *s, const char *addr);
361
ZMQ_EXPORT int zmq_send (void *s, const void *buf, size_t len, int flags);
Uli Köhler's avatar
Uli Köhler committed
362
ZMQ_EXPORT int zmq_send_const (void *s, const void *buf, size_t len, int flags);
363
ZMQ_EXPORT int zmq_recv (void *s, void *buf, size_t len, int flags);
364
ZMQ_EXPORT int zmq_socket_monitor (void *s, const char *addr, int events);
365

366 367
ZMQ_EXPORT int zmq_sendmsg (void *s, zmq_msg_t *msg, int flags);
ZMQ_EXPORT int zmq_recvmsg (void *s, zmq_msg_t *msg, int flags);
Martin Sustrik's avatar
Martin Sustrik committed
368

369
/*  Experimental                                                              */
MinRK's avatar
MinRK committed
370 371
struct iovec;

372 373
ZMQ_EXPORT int zmq_sendiov (void *s, struct iovec *iov, size_t count, int flags);
ZMQ_EXPORT int zmq_recviov (void *s, struct iovec *iov, size_t *count, int flags);
skaller's avatar
skaller committed
374

375 376 377
/******************************************************************************/
/*  I/O multiplexing.                                                         */
/******************************************************************************/
378

379 380 381
#define ZMQ_POLLIN 1
#define ZMQ_POLLOUT 2
#define ZMQ_POLLERR 4
382 383 384

typedef struct
{
385
    void *socket;
386 387 388
#if defined _WIN32
    SOCKET fd;
#else
389
    int fd;
390
#endif
391 392 393 394
    short events;
    short revents;
} zmq_pollitem_t;

395 396
#define ZMQ_POLLITEMS_DFLT 16

397
ZMQ_EXPORT int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);
398

399
/*  Built-in message proxy (3-way) */
Pieter Hintjens's avatar
Pieter Hintjens committed
400

401 402
ZMQ_EXPORT int zmq_proxy (void *frontend, void *backend, void *capture);
ZMQ_EXPORT int zmq_proxy_steerable (void *frontend, void *backend, void *capture, void *control);
403

404 405 406 407 408 409
/*  Encode a binary key as printable text using ZMQ RFC 32  */
ZMQ_EXPORT char *zmq_z85_encode (char *dest, uint8_t *data, size_t size);

/*  Encode a binary key from printable text per ZMQ RFC 32  */
ZMQ_EXPORT uint8_t *zmq_z85_decode (uint8_t *dest, char *string);

410 411 412 413
/*  Deprecated aliases */
#define ZMQ_STREAMER 1
#define ZMQ_FORWARDER 2
#define ZMQ_QUEUE 3
414
/*  Deprecated method */
415
ZMQ_EXPORT int zmq_device (int type, void *frontend, void *backend);
Pieter Hintjens's avatar
Pieter Hintjens committed
416

417 418
#undef ZMQ_EXPORT

Martin Sustrik's avatar
Martin Sustrik committed
419 420 421 422 423
#ifdef __cplusplus
}
#endif

#endif
424