zmq.h 9.15 KB
Newer Older
Martin Sustrik's avatar
Martin Sustrik committed
1
/*
2 3
    Copyright (c) 2007-2011 iMatix Corporation
    Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file
Martin Sustrik's avatar
Martin Sustrik committed
4 5 6 7

    This file is part of 0MQ.

    0MQ is free software; you can redistribute it and/or modify it under
8
    the terms of the GNU Lesser General Public License as published by
Martin Sustrik's avatar
Martin Sustrik committed
9 10 11 12 13 14
    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
15
    GNU Lesser General Public License for more details.
Martin Sustrik's avatar
Martin Sustrik committed
16

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

Martin Sustrik's avatar
Martin Sustrik committed
21 22
#ifndef __ZMQ_H_INCLUDED__
#define __ZMQ_H_INCLUDED__
Martin Sustrik's avatar
Martin Sustrik committed
23 24 25 26 27

#ifdef __cplusplus
extern "C" {
#endif

28
#include <errno.h>
Martin Sustrik's avatar
Martin Sustrik committed
29
#include <stddef.h>
30 31 32
#if defined _WIN32
#include "winsock2.h"
#endif
Martin Sustrik's avatar
Martin Sustrik committed
33

34
/*  Handle DSO symbol visibility                                             */
35 36 37 38 39 40
#if defined _WIN32
#   if defined DLL_EXPORT
#       define ZMQ_EXPORT __declspec(dllexport)
#   else
#       define ZMQ_EXPORT __declspec(dllimport)
#   endif
Martin Sustrik's avatar
Martin Sustrik committed
41
#else
42 43 44 45 46 47
#   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
48
#   endif
Martin Sustrik's avatar
Martin Sustrik committed
49 50
#endif

51
/******************************************************************************/
52
/*  0MQ versioning support.                                                   */
53
/******************************************************************************/
54

55
/*  Version macros for compile-time API version detection                     */
Martin Sustrik's avatar
Martin Sustrik committed
56 57
#define ZMQ_VERSION_MAJOR 3
#define ZMQ_VERSION_MINOR 0
Martin Sustrik's avatar
Martin Sustrik committed
58
#define ZMQ_VERSION_PATCH 0
59 60 61 62 63 64 65

#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)

/*  Run-time API version detection                                            */
66 67
ZMQ_EXPORT void zmq_version (int *major, int *minor, int *patch);

68
/******************************************************************************/
69
/*  0MQ errors.                                                               */
70
/******************************************************************************/
71

72
/*  A number random enough not to collide with different errno ranges on      */
73
/*  different OSes. The assumption is that error_t is at least 32-bit type.   */
74 75
#define ZMQ_HAUSNUMERO 156384712

76
/*  On Windows platform some of the standard POSIX errnos are not defined.    */
77 78 79 80 81 82
#ifndef ENOTSUP
#define ENOTSUP (ZMQ_HAUSNUMERO + 1)
#endif
#ifndef EPROTONOSUPPORT
#define EPROTONOSUPPORT (ZMQ_HAUSNUMERO + 2)
#endif
83 84 85 86 87 88 89 90 91 92 93 94
#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
95 96 97
#ifndef ECONNREFUSED
#define ECONNREFUSED (ZMQ_HAUSNUMERO + 7)
#endif
98 99 100
#ifndef EINPROGRESS
#define EINPROGRESS (ZMQ_HAUSNUMERO + 8)
#endif
101

102
/*  Native 0MQ error codes.                                                   */
103 104
#define EFSM (ZMQ_HAUSNUMERO + 51)
#define ENOCOMPATPROTO (ZMQ_HAUSNUMERO + 52)
105
#define ETERM (ZMQ_HAUSNUMERO + 53)
106
#define EMTHREAD (ZMQ_HAUSNUMERO + 54)
107

108 109 110 111
/*  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.                              */
112
ZMQ_EXPORT int zmq_errno (void);
113 114

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

117 118 119
/******************************************************************************/
/*  0MQ message definition.                                                   */
/******************************************************************************/
120

121 122 123 124
/*  Maximal size of "Very Small Message". VSMs are passed by value            */
/*  to avoid excessive memory allocation/deallocation.                        */
/*  If VMSs larger than 255 bytes are required, type of 'vsm_size'            */
/*  field in zmq_msg_t structure should be modified accordingly.              */
Martin Sustrik's avatar
Martin Sustrik committed
125
#define ZMQ_MAX_VSM_SIZE 30
Martin Sustrik's avatar
Martin Sustrik committed
126

127 128
/*  Message types. These integers may be stored in 'content' member of the    */
/*  message instead of regular pointer to the data.                           */
Martin Sustrik's avatar
Martin Sustrik committed
129 130
#define ZMQ_DELIMITER 31
#define ZMQ_VSM 32
Martin Sustrik's avatar
Martin Sustrik committed
131

132 133 134
/*  Message flags. ZMQ_MSG_SHARED is strictly speaking not a message flag     */
/*  (it has no equivalent in the wire format), however, making  it a flag     */
/*  allows us to pack the stucture tigher and thus improve performance.       */
135
#define ZMQ_MSG_MORE 1
136 137
#define ZMQ_MSG_SHARED 128

138 139 140
/*  A message. Note that 'content' is not a pointer to the raw data.          */
/*  Rather it is pointer to zmq::msg_content_t structure                      */
/*  (see src/msg_content.hpp for its definition).                             */
141
typedef struct
Martin Sustrik's avatar
Martin Sustrik committed
142
{
143
    void *content;
144
    unsigned char flags;
unknown's avatar
unknown committed
145
    unsigned char vsm_size;
Martin Sustrik's avatar
Martin Sustrik committed
146
    unsigned char vsm_data [ZMQ_MAX_VSM_SIZE];
147
} zmq_msg_t;
Martin Sustrik's avatar
Martin Sustrik committed
148

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

151
ZMQ_EXPORT int zmq_msg_init (zmq_msg_t *msg);
152 153
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,
154
    size_t size, zmq_free_fn *ffn, void *hint);
155 156 157 158 159
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);
ZMQ_EXPORT size_t zmq_msg_size (zmq_msg_t *msg);
Martin Sustrik's avatar
Martin Sustrik committed
160

161 162 163
/******************************************************************************/
/*  0MQ infrastructure (a.k.a. context) initialisation & termination.         */
/******************************************************************************/
164

165
ZMQ_EXPORT void *zmq_init (int io_threads);
Martin Sustrik's avatar
Martin Sustrik committed
166
ZMQ_EXPORT int zmq_term (void *context);
Martin Sustrik's avatar
Martin Sustrik committed
167

168 169 170
/******************************************************************************/
/*  0MQ socket definition.                                                    */
/******************************************************************************/
171

Martin Sustrik's avatar
Martin Sustrik committed
172
/*  Socket types.                                                             */ 
173 174 175 176 177 178 179 180 181
#define ZMQ_PAIR 0
#define ZMQ_PUB 1
#define ZMQ_SUB 2
#define ZMQ_REQ 3
#define ZMQ_REP 4
#define ZMQ_XREQ 5
#define ZMQ_XREP 6
#define ZMQ_PULL 7
#define ZMQ_PUSH 8
182 183
#define ZMQ_XPUB 9
#define ZMQ_XSUB 10
184 185
#define ZMQ_UPSTREAM ZMQ_PULL      /*  Old alias, remove in 3.x               */
#define ZMQ_DOWNSTREAM ZMQ_PUSH    /*  Old alias, remove in 3.x               */
186

187
/*  Socket options.                                                           */
188 189 190 191 192 193 194
#define ZMQ_HWM 1
#define ZMQ_SWAP 3
#define ZMQ_AFFINITY 4
#define ZMQ_IDENTITY 5
#define ZMQ_SUBSCRIBE 6
#define ZMQ_UNSUBSCRIBE 7
#define ZMQ_RATE 8
195
#define ZMQ_RECOVERY_IVL 9
196 197 198 199 200 201
#define ZMQ_MCAST_LOOP 10
#define ZMQ_SNDBUF 11
#define ZMQ_RCVBUF 12
#define ZMQ_RCVMORE 13
#define ZMQ_FD 14
#define ZMQ_EVENTS 15
202
#define ZMQ_TYPE 16
203
#define ZMQ_LINGER 17
204
#define ZMQ_RECONNECT_IVL 18
205
#define ZMQ_BACKLOG 19
206
#define ZMQ_RECOVERY_IVL_MSEC 20   /*  opt. recovery time, reconcile in 3.x   */
207
#define ZMQ_RECONNECT_IVL_MAX 21
208
#define ZMQ_MAXMSGSIZE 22
209
    
210
/*  Send/recv options.                                                        */
211 212
#define ZMQ_NOBLOCK 1
#define ZMQ_SNDMORE 2
213 214 215

ZMQ_EXPORT void *zmq_socket (void *context, int type);
ZMQ_EXPORT int zmq_close (void *s);
216 217
ZMQ_EXPORT int zmq_setsockopt (void *s, int option, const void *optval,
    size_t optvallen); 
218 219
ZMQ_EXPORT int zmq_getsockopt (void *s, int option, void *optval,
    size_t *optvallen);
220 221
ZMQ_EXPORT int zmq_bind (void *s, const char *addr);
ZMQ_EXPORT int zmq_connect (void *s, const char *addr);
222 223
ZMQ_EXPORT int zmq_send (void *s, zmq_msg_t *msg, int flags);
ZMQ_EXPORT int zmq_recv (void *s, zmq_msg_t *msg, int flags);
Martin Sustrik's avatar
Martin Sustrik committed
224

225 226 227
/******************************************************************************/
/*  I/O multiplexing.                                                         */
/******************************************************************************/
228

229 230 231
#define ZMQ_POLLIN 1
#define ZMQ_POLLOUT 2
#define ZMQ_POLLERR 4
232 233 234 235

typedef struct
{
    void *socket;
236 237 238
#if defined _WIN32
    SOCKET fd;
#else
239
    int fd;
240
#endif
241 242 243 244
    short events;
    short revents;
} zmq_pollitem_t;

245
ZMQ_EXPORT int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);
246

247
/******************************************************************************/
248
/*  Devices - Experimental.                                                   */
249
/******************************************************************************/
250

251 252 253
#define ZMQ_STREAMER 1
#define ZMQ_FORWARDER 2
#define ZMQ_QUEUE 3
254 255 256

ZMQ_EXPORT int zmq_device (int device, void * insocket, void* outsocket);

257 258
#undef ZMQ_EXPORT

Martin Sustrik's avatar
Martin Sustrik committed
259 260 261 262 263
#ifdef __cplusplus
}
#endif

#endif
264