rabbitmq-c
C AMQP Client library for RabbitMQ
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
amqp.h
Go to the documentation of this file.
1 /* vim:set ft=c ts=2 sw=2 sts=2 et cindent: */
3 /*
4  * ***** BEGIN LICENSE BLOCK *****
5  * Version: MIT
6  *
7  * Portions created by Alan Antonuk are Copyright (c) 2012-2013
8  * Alan Antonuk. All Rights Reserved.
9  *
10  * Portions created by VMware are Copyright (c) 2007-2012 VMware, Inc.
11  * All Rights Reserved.
12  *
13  * Portions created by Tony Garnock-Jones are Copyright (c) 2009-2010
14  * VMware, Inc. and Tony Garnock-Jones. All Rights Reserved.
15  *
16  * Permission is hereby granted, free of charge, to any person
17  * obtaining a copy of this software and associated documentation
18  * files (the "Software"), to deal in the Software without
19  * restriction, including without limitation the rights to use, copy,
20  * modify, merge, publish, distribute, sublicense, and/or sell copies
21  * of the Software, and to permit persons to whom the Software is
22  * furnished to do so, subject to the following conditions:
23  *
24  * The above copyright notice and this permission notice shall be
25  * included in all copies or substantial portions of the Software.
26  *
27  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
28  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
29  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
30  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
31  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
32  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
33  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
34  * SOFTWARE.
35  * ***** END LICENSE BLOCK *****
36  */
37 
38 #ifndef AMQP_H
39 #define AMQP_H
40 
43 #ifdef __cplusplus
44 #define AMQP_BEGIN_DECLS extern "C" {
45 #define AMQP_END_DECLS }
46 #else
47 #define AMQP_BEGIN_DECLS
48 #define AMQP_END_DECLS
49 #endif
50 
51 
52 
53 /*
54  * \internal
55  * Important API decorators:
56  * AMQP_PUBLIC_FUNCTION - a public API function
57  * AMQP_PUBLIC_VARIABLE - a public API external variable
58  * AMQP_CALL - calling convension (used on Win32)
59  */
60 
61 #if defined(_WIN32) && defined(_MSC_VER)
62 # if defined(AMQP_BUILD) && !defined(AMQP_STATIC)
63 # define AMQP_PUBLIC_FUNCTION __declspec(dllexport)
64 # define AMQP_PUBLIC_VARIABLE __declspec(dllexport) extern
65 # else
66 # define AMQP_PUBLIC_FUNCTION
67 # if !defined(AMQP_STATIC)
68 # define AMQP_PUBLIC_VARIABLE __declspec(dllimport) extern
69 # else
70 # define AMQP_PUBLIC_VARIABLE extern
71 # endif
72 # endif
73 # define AMQP_CALL __cdecl
74 
75 #elif defined(_WIN32) && defined(__BORLANDC__)
76 # if defined(AMQP_BUILD) && !defined(AMQP_STATIC)
77 # define AMQP_PUBLIC_FUNCTION __declspec(dllexport)
78 # define AMQP_PUBLIC_VARIABLE __declspec(dllexport) extern
79 # else
80 # define AMQP_PUBLIC_FUNCTION
81 # if !defined(AMQP_STATIC)
82 # define AMQP_PUBLIC_VARIABLE __declspec(dllimport) extern
83 # else
84 # define AMQP_PUBLIC_VARIABLE extern
85 # endif
86 # endif
87 # define AMQP_CALL __cdecl
88 
89 #elif defined(_WIN32) && defined(__MINGW32__)
90 # if defined(AMQP_BUILD) && !defined(AMQP_STATIC)
91 # define AMQP_PUBLIC_FUNCTION __declspec(dllexport)
92 # define AMQP_PUBLIC_VARIABLE __declspec(dllexport) extern
93 # else
94 # define AMQP_PUBLIC_FUNCTION
95 # if !defined(AMQP_STATIC)
96 # define AMQP_PUBLIC_VARIABLE __declspec(dllimport) extern
97 # else
98 # define AMQP_PUBLIC_VARIABLE extern
99 # endif
100 # endif
101 # define AMQP_CALL __cdecl
102 
103 #elif defined(_WIN32) && defined(__CYGWIN__)
104 # if defined(AMQP_BUILD) && !defined(AMQP_STATIC)
105 # define AMQP_PUBLIC_FUNCTION __declspec(dllexport)
106 # define AMQP_PUBLIC_VARIABLE __declspec(dllexport)
107 # else
108 # define AMQP_PUBLIC_FUNCTION
109 # if !defined(AMQP_STATIC)
110 # define AMQP_PUBLIC_VARIABLE __declspec(dllimport) extern
111 # else
112 # define AMQP_PUBLIC_VARIABLE extern
113 # endif
114 # endif
115 # define AMQP_CALL __cdecl
116 
117 #elif defined(__GNUC__) && __GNUC__ >= 4
118 # include <sys/uio.h>
119 # define AMQP_PUBLIC_FUNCTION \
120  __attribute__ ((visibility ("default")))
121 # define AMQP_PUBLIC_VARIABLE \
122  __attribute__ ((visibility ("default"))) extern
123 # define AMQP_CALL
124 #else
125 # define AMQP_PUBLIC_FUNCTION
126 # define AMQP_PUBLIC_VARIABLE extern
127 # define AMQP_CALL
128 #endif
129 
130 #if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)
131 # define AMQP_DEPRECATED(function) \
132  function __attribute__ ((__deprecated__))
133 #elif defined(_MSC_VER)
134 # define AMQP_DEPRECATED(function) \
135  __declspec(deprecated) function
136 #else
137 # define AMQP_DEPRECATED(function)
138 #endif
139 
140 /* Define ssize_t on Win32/64 platforms
141  See: http://lists.cs.uiuc.edu/pipermail/llvmdev/2010-April/030649.html for details
142  */
143 #if !defined(_W64)
144 #if !defined(__midl) && (defined(_X86_) || defined(_M_IX86)) && _MSC_VER >= 1300
145 #define _W64 __w64
146 #else
147 #define _W64
148 #endif
149 #endif
150 
151 #ifdef _MSC_VER
152 #ifdef _WIN64
153 typedef __int64 ssize_t;
154 #else
155 typedef _W64 int ssize_t;
156 #endif
157 #endif
158 
161 #include <stddef.h>
162 #include <stdint.h>
163 
164 struct timeval;
165 
166 AMQP_BEGIN_DECLS
167 
219 /*
220  * Developer note: when changing these, be sure to update SOVERSION constants
221  * in CMakeLists.txt and configure.ac
222  */
223 
224 #define AMQP_VERSION_MAJOR 0
225 #define AMQP_VERSION_MINOR 4
226 #define AMQP_VERSION_PATCH 0
227 #define AMQP_VERSION_IS_RELEASE 0
228 
229 
248 #define AMQP_VERSION ((AMQP_VERSION_MAJOR << 24) | \
249  (AMQP_VERSION_MINOR << 16) | \
250  (AMQP_VERSION_PATCH << 8) | \
251  (AMQP_VERSION_IS_RELEASE))
252 
254 #define AMQ_STRINGIFY(s) AMQ_STRINGIFY_HELPER(s)
255 #define AMQ_STRINGIFY_HELPER(s) #s
256 
257 #define AMQ_VERSION_STRING AMQ_STRINGIFY(AMQP_VERSION_MAJOR) "." \
258  AMQ_STRINGIFY(AMQP_VERSION_MINOR) "." \
259  AMQ_STRINGIFY(AMQP_VERSION_PATCH)
260 
274 #if AMQP_VERSION_IS_RELEASE
275 # define AMQP_VERSION_STRING AMQ_VERSION_STRING
276 #else
277 # define AMQP_VERSION_STRING AMQ_VERSION_STRING "-pre"
278 #endif
279 
280 
292 AMQP_PUBLIC_FUNCTION
293 uint32_t
294 AMQP_CALL amqp_version_number(void);
295 
307 AMQP_PUBLIC_FUNCTION
308 char const *
309 AMQP_CALL amqp_version(void);
310 
320 #define AMQP_DEFAULT_FRAME_SIZE 131072
321 
331 #define AMQP_DEFAULT_MAX_CHANNELS 0
332 
342 #define AMQP_DEFAULT_HEARTBEAT 0
343 
349 typedef int amqp_boolean_t;
350 
356 typedef uint32_t amqp_method_number_t;
357 
363 typedef uint32_t amqp_flags_t;
364 
370 typedef uint16_t amqp_channel_t;
371 
377 typedef struct amqp_bytes_t_ {
378  size_t len;
379  void *bytes;
380 } amqp_bytes_t;
381 
387 typedef struct amqp_decimal_t_ {
388  uint8_t decimals;
389  uint32_t value;
391 
404 typedef struct amqp_table_t_ {
406  struct amqp_table_entry_t_ *entries;
407 } amqp_table_t;
408 
416 typedef struct amqp_array_t_ {
418  struct amqp_field_value_t_ *entries;
419 } amqp_array_t;
420 
421 /*
422  0-9 0-9-1 Qpid/Rabbit Type Remarks
423 ---------------------------------------------------------------------------
424  t t Boolean
425  b b Signed 8-bit
426  B Unsigned 8-bit
427  U s Signed 16-bit (A1)
428  u Unsigned 16-bit
429  I I I Signed 32-bit
430  i Unsigned 32-bit
431  L l Signed 64-bit (B)
432  l Unsigned 64-bit
433  f f 32-bit float
434  d d 64-bit float
435  D D D Decimal
436  s Short string (A2)
437  S S S Long string
438  A Nested Array
439  T T T Timestamp (u64)
440  F F F Nested Table
441  V V V Void
442  x Byte array
443 
444 Remarks:
445 
446  A1, A2: Notice how the types **CONFLICT** here. In Qpid and Rabbit,
447  's' means a signed 16-bit integer; in 0-9-1, it means a
448  short string.
449 
450  B: Notice how the signednesses **CONFLICT** here. In Qpid and Rabbit,
451  'l' means a signed 64-bit integer; in 0-9-1, it means an unsigned
452  64-bit integer.
453 
454 I'm going with the Qpid/Rabbit types, where there's a conflict, and
455 the 0-9-1 types otherwise. 0-8 is a subset of 0-9, which is a subset
456 of the other two, so this will work for both 0-8 and 0-9-1 branches of
457 the code.
458 */
459 
465 typedef struct amqp_field_value_t_ {
466  uint8_t kind;
467  union {
469  int8_t i8;
470  uint8_t u8;
471  int16_t i16;
472  uint16_t u16;
473  int32_t i32;
474  uint32_t u32;
475  int64_t i64;
476  uint64_t u64;
477  float f32;
478  double f64;
483  } value;
485 
493 typedef struct amqp_table_entry_t_ {
498 
504 typedef enum {
524 
530 typedef struct amqp_pool_blocklist_t_ {
532  void **blocklist;
534 
540 typedef struct amqp_pool_t_ {
541  size_t pagesize;
550  int next_page;
551  char *alloc_block;
552  size_t alloc_used;
553 } amqp_pool_t;
554 
560 typedef struct amqp_method_t_ {
562  void *decoded;
564 } amqp_method_t;
565 
571 typedef struct amqp_frame_t_ {
572  uint8_t frame_type;
578  union {
580  struct {
581  uint16_t class_id;
582  uint64_t body_size;
583  void *decoded;
585  } properties;
588  struct {
589  uint8_t transport_high;
590  uint8_t transport_low;
591  uint8_t protocol_version_major;
592  uint8_t protocol_version_minor;
593  } protocol_header;
595  } payload;
596 } amqp_frame_t;
597 
603 typedef enum amqp_response_type_enum_ {
609 
615 typedef struct amqp_rpc_reply_t_ {
629 
635 typedef enum amqp_sasl_method_enum_ {
638 
644 typedef struct amqp_connection_state_t_ *amqp_connection_state_t;
645 
651 typedef struct amqp_socket_t_ amqp_socket_t;
652 
658 typedef enum amqp_status_enum_
659 {
717 
718 AMQP_END_DECLS
719 
720 #include <amqp_framing.h>
721 
722 AMQP_BEGIN_DECLS
723 
729 AMQP_PUBLIC_VARIABLE const amqp_bytes_t amqp_empty_bytes;
730 
736 AMQP_PUBLIC_VARIABLE const amqp_table_t amqp_empty_table;
737 
743 AMQP_PUBLIC_VARIABLE const amqp_array_t amqp_empty_array;
744 
745 /* Compatibility macros for the above, to avoid the need to update
746  code written against earlier versions of librabbitmq. */
747 
757 #define AMQP_EMPTY_BYTES amqp_empty_bytes
758 
768 #define AMQP_EMPTY_TABLE amqp_empty_table
769 
779 #define AMQP_EMPTY_ARRAY amqp_empty_array
780 
802 AMQP_PUBLIC_FUNCTION
803 void
804 AMQP_CALL init_amqp_pool(amqp_pool_t *pool, size_t pagesize);
805 
826 AMQP_PUBLIC_FUNCTION
827 void
828 AMQP_CALL recycle_amqp_pool(amqp_pool_t *pool);
829 
839 AMQP_PUBLIC_FUNCTION
840 void
841 AMQP_CALL empty_amqp_pool(amqp_pool_t *pool);
842 
859 AMQP_PUBLIC_FUNCTION
860 void *
861 AMQP_CALL amqp_pool_alloc(amqp_pool_t *pool, size_t amount);
862 
882 AMQP_PUBLIC_FUNCTION
883 void
884 AMQP_CALL amqp_pool_alloc_bytes(amqp_pool_t *pool, size_t amount, amqp_bytes_t *output);
885 
904 AMQP_PUBLIC_FUNCTION
906 AMQP_CALL amqp_cstring_bytes(char const *cstr);
907 
924 AMQP_PUBLIC_FUNCTION
926 AMQP_CALL amqp_bytes_malloc_dup(amqp_bytes_t src);
927 
942 AMQP_PUBLIC_FUNCTION
944 AMQP_CALL amqp_bytes_malloc(size_t amount);
945 
960 AMQP_PUBLIC_FUNCTION
961 void
962 AMQP_CALL amqp_bytes_free(amqp_bytes_t bytes);
963 
976 AMQP_PUBLIC_FUNCTION
978 AMQP_CALL amqp_new_connection(void);
979 
997 AMQP_PUBLIC_FUNCTION
998 int
1000 
1001 
1019 AMQP_DEPRECATED(
1020  AMQP_PUBLIC_FUNCTION
1021  void
1022  AMQP_CALL amqp_set_sockfd(amqp_connection_state_t state, int sockfd)
1023 );
1024 
1025 
1058 AMQP_PUBLIC_FUNCTION
1059 int
1061  int channel_max,
1062  int frame_max,
1063  int heartbeat);
1064 
1076 AMQP_PUBLIC_FUNCTION
1077 int
1079 
1097 AMQP_PUBLIC_FUNCTION
1098 int
1100 
1142 AMQP_PUBLIC_FUNCTION
1143 int
1145  amqp_bytes_t received_data,
1146  amqp_frame_t *decoded_frame);
1147 
1165 AMQP_PUBLIC_FUNCTION
1168 
1193 AMQP_PUBLIC_FUNCTION
1194 void
1196 
1214 AMQP_PUBLIC_FUNCTION
1215 void
1217 
1238 AMQP_PUBLIC_FUNCTION
1239 void
1241  amqp_channel_t channel);
1242 
1264 AMQP_PUBLIC_FUNCTION
1265 int
1266 AMQP_CALL amqp_send_frame(amqp_connection_state_t state, amqp_frame_t const *frame);
1267 
1279 AMQP_PUBLIC_FUNCTION
1280 int
1281 AMQP_CALL amqp_table_entry_cmp(void const *entry1, void const *entry2);
1282 
1310 AMQP_PUBLIC_FUNCTION
1311 int
1312 AMQP_CALL amqp_open_socket(char const *hostname, int portnumber);
1313 
1335 AMQP_PUBLIC_FUNCTION
1336 int
1337 AMQP_CALL amqp_send_header(amqp_connection_state_t state);
1338 
1355 AMQP_PUBLIC_FUNCTION
1358 
1410 AMQP_PUBLIC_FUNCTION
1411 int
1413  amqp_frame_t *decoded_frame);
1414 
1476 AMQP_PUBLIC_FUNCTION
1477 int
1479  amqp_frame_t *decoded_frame,
1480  struct timeval *tv);
1481 
1522 AMQP_PUBLIC_FUNCTION
1523 int
1525  amqp_channel_t expected_channel,
1526  amqp_method_number_t expected_method,
1527  amqp_method_t *output);
1528 
1555 AMQP_PUBLIC_FUNCTION
1556 int
1558  amqp_channel_t channel,
1560  void *decoded);
1561 
1594 AMQP_PUBLIC_FUNCTION
1597  amqp_channel_t channel,
1598  amqp_method_number_t request_id,
1599  amqp_method_number_t *expected_reply_ids,
1600  void *decoded_request_method);
1601 
1616 AMQP_PUBLIC_FUNCTION
1617 void *
1619  amqp_channel_t channel,
1620  amqp_method_number_t request_id,
1621  amqp_method_number_t reply_id,
1622  void *decoded_request_method);
1623 
1663 AMQP_PUBLIC_FUNCTION
1666 
1717 AMQP_PUBLIC_FUNCTION
1719 AMQP_CALL amqp_login(amqp_connection_state_t state, char const *vhost,
1720  int channel_max, int frame_max, int heartbeat,
1721  amqp_sasl_method_enum sasl_method, ...);
1722 
1775 AMQP_PUBLIC_FUNCTION
1777 AMQP_CALL amqp_login_with_properties(amqp_connection_state_t state, char const *vhost,
1778  int channel_max, int frame_max, int heartbeat,
1779  const amqp_table_t *properties, amqp_sasl_method_enum sasl_method, ...);
1780 
1781 struct amqp_basic_properties_t_;
1782 
1829 AMQP_PUBLIC_FUNCTION
1830 int
1832  amqp_bytes_t exchange, amqp_bytes_t routing_key,
1833  amqp_boolean_t mandatory, amqp_boolean_t immediate,
1834  struct amqp_basic_properties_t_ const *properties,
1835  amqp_bytes_t body);
1836 
1847 AMQP_PUBLIC_FUNCTION
1850  int code);
1851 
1865 AMQP_PUBLIC_FUNCTION
1867 AMQP_CALL amqp_connection_close(amqp_connection_state_t state, int code);
1868 
1884 AMQP_PUBLIC_FUNCTION
1885 int
1886 AMQP_CALL amqp_basic_ack(amqp_connection_state_t state, amqp_channel_t channel,
1887  uint64_t delivery_tag, amqp_boolean_t multiple);
1888 
1905 AMQP_PUBLIC_FUNCTION
1907 AMQP_CALL amqp_basic_get(amqp_connection_state_t state, amqp_channel_t channel,
1908  amqp_bytes_t queue, amqp_boolean_t no_ack);
1909 
1925 AMQP_PUBLIC_FUNCTION
1926 int
1928  uint64_t delivery_tag, amqp_boolean_t requeue);
1929 
1942 AMQP_PUBLIC_FUNCTION
1945 
1961 AMQP_DEPRECATED(
1962  AMQP_PUBLIC_FUNCTION
1963  char *
1964  AMQP_CALL amqp_error_string(int err)
1965 );
1966 
1967 
1979 AMQP_PUBLIC_FUNCTION
1980 const char *
1981 AMQP_CALL amqp_error_string2(int err);
1982 
1983 
2004 AMQP_PUBLIC_FUNCTION
2005 int
2006 AMQP_CALL amqp_decode_table(amqp_bytes_t encoded, amqp_pool_t *pool,
2007  amqp_table_t *output, size_t *offset);
2008 
2028 AMQP_PUBLIC_FUNCTION
2029 int
2030 AMQP_CALL amqp_encode_table(amqp_bytes_t encoded, amqp_table_t *input, size_t *offset);
2031 
2032 
2051 AMQP_PUBLIC_FUNCTION
2052 int
2053 AMQP_CALL amqp_table_clone(amqp_table_t *original, amqp_table_t *clone, amqp_pool_t *pool);
2054 
2060 typedef struct amqp_message_t_ {
2064 } amqp_message_t;
2065 
2084 AMQP_PUBLIC_FUNCTION
2087  amqp_channel_t channel,
2088  amqp_message_t *message, int flags);
2089 
2097 AMQP_PUBLIC_FUNCTION
2098 void
2099 AMQP_CALL amqp_destroy_message(amqp_message_t *message);
2100 
2106 typedef struct amqp_envelope_t_ {
2109  uint64_t delivery_tag;
2114 } amqp_envelope_t;
2115 
2146 AMQP_PUBLIC_FUNCTION
2149  amqp_envelope_t *envelope,
2150  struct timeval *timeout, int flags);
2151 
2159 AMQP_PUBLIC_FUNCTION
2160 void
2161 AMQP_CALL amqp_destroy_envelope(amqp_envelope_t *envelope);
2162 
2163 
2170  char *user;
2171  char *password;
2172  char *host;
2173  char *vhost;
2174  int port;
2175  amqp_boolean_t ssl;
2176 };
2177 
2192 AMQP_PUBLIC_FUNCTION
2193 void
2194 AMQP_CALL amqp_default_connection_info(struct amqp_connection_info *parsed);
2195 
2218 AMQP_PUBLIC_FUNCTION
2219 int
2220 AMQP_CALL amqp_parse_url(char *url, struct amqp_connection_info *parsed);
2221 
2222 /* socket API */
2223 
2240 AMQP_PUBLIC_FUNCTION
2241 int
2242 AMQP_CALL
2243 amqp_socket_open(amqp_socket_t *self, const char *host, int port);
2244 
2262 AMQP_PUBLIC_FUNCTION
2263 int
2264 AMQP_CALL
2265 amqp_socket_open_noblock(amqp_socket_t *self, const char *host, int port, struct timeval *timeout);
2266 
2282 AMQP_PUBLIC_FUNCTION
2283 int
2284 AMQP_CALL
2285 amqp_socket_get_sockfd(amqp_socket_t *self);
2286 
2295 AMQP_PUBLIC_FUNCTION
2296 amqp_socket_t *
2298 
2299 AMQP_END_DECLS
2300 
2301 
2302 #endif /* AMQP_H */