Annotation of win32/rabbitmq/include/rabbitmq-c/amqp.h, revision 1.1
1.1 ! moko 1: // Copyright 2007 - 2021, Alan Antonuk and the rabbitmq-c contributors.
! 2: // SPDX-License-Identifier: mit
! 3:
! 4: /** \file */
! 5:
! 6: #include <rabbitmq-c/export.h>
! 7:
! 8: #ifndef RABBITMQ_C_RABBITMQ_C_H
! 9: #define RABBITMQ_C_RABBITMQ_C_H
! 10:
! 11: /** \cond HIDE_FROM_DOXYGEN */
! 12:
! 13: #ifdef __cplusplus
! 14: #define AMQP_BEGIN_DECLS extern "C" {
! 15: #define AMQP_END_DECLS }
! 16: #else
! 17: #define AMQP_BEGIN_DECLS
! 18: #define AMQP_END_DECLS
! 19: #endif
! 20:
! 21: /*
! 22: * \internal
! 23: * AMQP_CALL - calling convension (used on Win32)
! 24: */
! 25: #ifdef _WIN32
! 26: #define AMQP_CALL __cdecl
! 27: #else
! 28: #define AMQP_CALL
! 29: #endif
! 30:
! 31: /* Define ssize_t on Win32/64 platforms
! 32: See: http://lists.cs.uiuc.edu/pipermail/llvmdev/2010-April/030649.html for
! 33: details
! 34: */
! 35: #if !defined(_W64)
! 36: #if !defined(__midl) && (defined(_X86_) || defined(_M_IX86)) && _MSC_VER >= 1300
! 37: #define _W64 __w64
! 38: #else
! 39: #define _W64
! 40: #endif
! 41: #endif
! 42:
! 43: #if defined(_MSC_VER) || (defined(__BORLANDC__) && (__BORLANDC__ <= 0x0564))
! 44: #ifdef _WIN64
! 45: typedef __int64 ssize_t;
! 46: #else
! 47: typedef _W64 int ssize_t;
! 48: #endif
! 49: #endif
! 50:
! 51: #if defined(_WIN32) && defined(__MINGW32__)
! 52: #include <sys/types.h>
! 53: #endif
! 54:
! 55: /** \endcond */
! 56:
! 57: #include <stddef.h>
! 58: #include <stdint.h>
! 59:
! 60: struct timeval;
! 61:
! 62: AMQP_BEGIN_DECLS
! 63:
! 64: /**
! 65: * \def AMQP_VERSION_MAJOR
! 66: *
! 67: * Major library version number compile-time constant
! 68: *
! 69: * The major version is incremented when backwards incompatible API changes
! 70: * are made.
! 71: *
! 72: * \sa AMQP_VERSION, AMQP_VERSION_STRING
! 73: *
! 74: * \since v0.4.0
! 75: */
! 76:
! 77: /**
! 78: * \def AMQP_VERSION_MINOR
! 79: *
! 80: * Minor library version number compile-time constant
! 81: *
! 82: * The minor version is incremented when new APIs are added. Existing APIs
! 83: * are left alone.
! 84: *
! 85: * \sa AMQP_VERSION, AMQP_VERSION_STRING
! 86: *
! 87: * \since v0.4.0
! 88: */
! 89:
! 90: /**
! 91: * \def AMQP_VERSION_PATCH
! 92: *
! 93: * Patch library version number compile-time constant
! 94: *
! 95: * The patch version is incremented when library code changes, but the API
! 96: * is not changed.
! 97: *
! 98: * \sa AMQP_VERSION, AMQP_VERSION_STRING
! 99: *
! 100: * \since v0.4.0
! 101: */
! 102:
! 103: /**
! 104: * \def AMQP_VERSION_IS_RELEASE
! 105: *
! 106: * Version constant set to 1 for tagged release, 0 otherwise
! 107: *
! 108: * NOTE: versions that are not tagged releases are not guaranteed to be API/ABI
! 109: * compatible with older releases, and may change commit-to-commit.
! 110: *
! 111: * \sa AMQP_VERSION, AMQP_VERSION_STRING
! 112: *
! 113: * \since v0.4.0
! 114: */
! 115: /*
! 116: * Developer note: when changing these, be sure to update SOVERSION constants
! 117: * in CMakeLists.txt and configure.ac
! 118: */
! 119:
! 120: #define AMQP_VERSION_MAJOR 0
! 121: #define AMQP_VERSION_MINOR 17
! 122: #define AMQP_VERSION_PATCH 0
! 123: #define AMQP_VERSION_IS_RELEASE 1
! 124:
! 125: /**
! 126: * \def AMQP_VERSION_CODE
! 127: *
! 128: * Helper macro to geneate a packed version code suitable for
! 129: * comparison with AMQP_VERSION.
! 130: *
! 131: * \sa amqp_version_number() AMQP_VERSION_MAJOR, AMQP_VERSION_MINOR,
! 132: * AMQP_VERSION_PATCH, AMQP_VERSION_IS_RELEASE, AMQP_VERSION
! 133: *
! 134: * \since v0.6.1
! 135: */
! 136: #define AMQP_VERSION_CODE(major, minor, patch, release) \
! 137: ((major << 24) | (minor << 16) | (patch << 8) | (release))
! 138:
! 139: /**
! 140: * \def AMQP_VERSION
! 141: *
! 142: * Packed version number
! 143: *
! 144: * AMQP_VERSION is a 4-byte unsigned integer with the most significant byte
! 145: * set to AMQP_VERSION_MAJOR, the second most significant byte set to
! 146: * AMQP_VERSION_MINOR, third most significant byte set to AMQP_VERSION_PATCH,
! 147: * and the lowest byte set to AMQP_VERSION_IS_RELEASE.
! 148: *
! 149: * For example version 2.3.4 which is released version would be encoded as
! 150: * 0x02030401
! 151: *
! 152: * \sa amqp_version_number() AMQP_VERSION_MAJOR, AMQP_VERSION_MINOR,
! 153: * AMQP_VERSION_PATCH, AMQP_VERSION_IS_RELEASE, AMQP_VERSION_CODE
! 154: *
! 155: * \since v0.4.0
! 156: */
! 157: #define AMQP_VERSION \
! 158: AMQP_VERSION_CODE(AMQP_VERSION_MAJOR, AMQP_VERSION_MINOR, \
! 159: AMQP_VERSION_PATCH, AMQP_VERSION_IS_RELEASE)
! 160:
! 161: /** \cond HIDE_FROM_DOXYGEN */
! 162: #define AMQ_STRINGIFY(s) AMQ_STRINGIFY_HELPER(s)
! 163: #define AMQ_STRINGIFY_HELPER(s) #s
! 164:
! 165: #define AMQ_VERSION_STRING \
! 166: AMQ_STRINGIFY(AMQP_VERSION_MAJOR) \
! 167: "." AMQ_STRINGIFY(AMQP_VERSION_MINOR) "." AMQ_STRINGIFY(AMQP_VERSION_PATCH)
! 168: /** \endcond */
! 169:
! 170: /**
! 171: * \def AMQP_VERSION_STRING
! 172: *
! 173: * Version string compile-time constant
! 174: *
! 175: * Non-released versions of the library will have "-pre" appended to the
! 176: * version string
! 177: *
! 178: * \sa amqp_version()
! 179: *
! 180: * \since v0.4.0
! 181: */
! 182: #if AMQP_VERSION_IS_RELEASE
! 183: #define AMQP_VERSION_STRING AMQ_VERSION_STRING
! 184: #else
! 185: #define AMQP_VERSION_STRING AMQ_VERSION_STRING "-pre"
! 186: #endif
! 187:
! 188: /**
! 189: * Returns the rabbitmq-c version as a packed integer.
! 190: *
! 191: * See \ref AMQP_VERSION
! 192: *
! 193: * \return packed 32-bit integer representing version of library at runtime
! 194: *
! 195: * \sa AMQP_VERSION, amqp_version()
! 196: *
! 197: * \since v0.4.0
! 198: */
! 199: AMQP_EXPORT
! 200: uint32_t AMQP_CALL amqp_version_number(void);
! 201:
! 202: /**
! 203: * Returns the rabbitmq-c version as a string.
! 204: *
! 205: * See \ref AMQP_VERSION_STRING
! 206: *
! 207: * \return a statically allocated string describing the version of rabbitmq-c.
! 208: *
! 209: * \sa amqp_version_number(), AMQP_VERSION_STRING, AMQP_VERSION
! 210: *
! 211: * \since v0.1
! 212: */
! 213: AMQP_EXPORT
! 214: char const *AMQP_CALL amqp_version(void);
! 215:
! 216: /**
! 217: * \def AMQP_DEFAULT_FRAME_SIZE
! 218: *
! 219: * Default frame size (128Kb)
! 220: *
! 221: * \sa amqp_login(), amqp_login_with_properties()
! 222: *
! 223: * \since v0.4.0
! 224: */
! 225: #define AMQP_DEFAULT_FRAME_SIZE 131072
! 226:
! 227: /**
! 228: * \def AMQP_DEFAULT_MAX_CHANNELS
! 229: *
! 230: * Default maximum number of channels (2047, RabbitMQ default limit of 2048,
! 231: * minus 1 for channel 0). RabbitMQ set a default limit of 2048 channels per
! 232: * connection in v3.7.5 to prevent broken clients from leaking too many
! 233: * channels.
! 234: *
! 235: * \sa amqp_login(), amqp_login_with_properties()
! 236: *
! 237: * \since v0.4.0
! 238: */
! 239: #define AMQP_DEFAULT_MAX_CHANNELS 2047
! 240:
! 241: /**
! 242: * \def AMQP_DEFAULT_HEARTBEAT
! 243: *
! 244: * Default heartbeat interval (0, heartbeat disabled)
! 245: *
! 246: * \sa amqp_login(), amqp_login_with_properties()
! 247: *
! 248: * \since v0.4.0
! 249: */
! 250: #define AMQP_DEFAULT_HEARTBEAT 0
! 251:
! 252: /**
! 253: * \def AMQP_DEFAULT_VHOST
! 254: *
! 255: * Default RabbitMQ vhost: "/"
! 256: *
! 257: * \sa amqp_login(), amqp_login_with_properties()
! 258: *
! 259: * \since v0.9.0
! 260: */
! 261: #define AMQP_DEFAULT_VHOST "/"
! 262:
! 263: /**
! 264: * boolean type 0 = false, true otherwise
! 265: *
! 266: * \since v0.1
! 267: */
! 268: typedef int amqp_boolean_t;
! 269:
! 270: /**
! 271: * Method number
! 272: *
! 273: * \since v0.1
! 274: */
! 275: typedef uint32_t amqp_method_number_t;
! 276:
! 277: /**
! 278: * Bitmask for flags
! 279: *
! 280: * \since v0.1
! 281: */
! 282: typedef uint32_t amqp_flags_t;
! 283:
! 284: /**
! 285: * Channel type
! 286: *
! 287: * \since v0.1
! 288: */
! 289: typedef uint16_t amqp_channel_t;
! 290:
! 291: /**
! 292: * Buffer descriptor
! 293: *
! 294: * \since v0.1
! 295: */
! 296: typedef struct amqp_bytes_t_ {
! 297: size_t len; /**< length of the buffer in bytes */
! 298: void *bytes; /**< pointer to the beginning of the buffer */
! 299: } amqp_bytes_t;
! 300:
! 301: /**
! 302: * Decimal data type
! 303: *
! 304: * \since v0.1
! 305: */
! 306: typedef struct amqp_decimal_t_ {
! 307: uint8_t decimals; /**< the location of the decimal point */
! 308: uint32_t value; /**< the value before the decimal point is applied */
! 309: } amqp_decimal_t;
! 310:
! 311: /**
! 312: * AMQP field table
! 313: *
! 314: * An AMQP field table is a set of key-value pairs.
! 315: * A key is a UTF-8 encoded string up to 128 bytes long, and are not null
! 316: * terminated.
! 317: * A value can be one of several different datatypes. \sa
! 318: * amqp_field_value_kind_t
! 319: *
! 320: * \sa amqp_table_entry_t
! 321: *
! 322: * \since v0.1
! 323: */
! 324: typedef struct amqp_table_t_ {
! 325: int num_entries; /**< length of entries array */
! 326: struct amqp_table_entry_t_ *entries; /**< an array of table entries */
! 327: } amqp_table_t;
! 328:
! 329: /**
! 330: * An AMQP Field Array
! 331: *
! 332: * A repeated set of field values, all must be of the same type
! 333: *
! 334: * \since v0.1
! 335: */
! 336: typedef struct amqp_array_t_ {
! 337: int num_entries; /**< Number of entries in the table */
! 338: struct amqp_field_value_t_ *entries; /**< linked list of field values */
! 339: } amqp_array_t;
! 340:
! 341: /*
! 342: 0-9 0-9-1 Qpid/Rabbit Type Remarks
! 343: ---------------------------------------------------------------------------
! 344: t t Boolean
! 345: b b Signed 8-bit
! 346: B Unsigned 8-bit
! 347: U s Signed 16-bit (A1)
! 348: u Unsigned 16-bit
! 349: I I I Signed 32-bit
! 350: i Unsigned 32-bit
! 351: L l Signed 64-bit (B)
! 352: l Unsigned 64-bit
! 353: f f 32-bit float
! 354: d d 64-bit float
! 355: D D D Decimal
! 356: s Short string (A2)
! 357: S S S Long string
! 358: A Nested Array
! 359: T T T Timestamp (u64)
! 360: F F F Nested Table
! 361: V V V Void
! 362: x Byte array
! 363:
! 364: Remarks:
! 365:
! 366: A1, A2: Notice how the types **CONFLICT** here. In Qpid and Rabbit,
! 367: 's' means a signed 16-bit integer; in 0-9-1, it means a
! 368: short string.
! 369:
! 370: B: Notice how the signednesses **CONFLICT** here. In Qpid and Rabbit,
! 371: 'l' means a signed 64-bit integer; in 0-9-1, it means an unsigned
! 372: 64-bit integer.
! 373:
! 374: I'm going with the Qpid/Rabbit types, where there's a conflict, and
! 375: the 0-9-1 types otherwise. 0-8 is a subset of 0-9, which is a subset
! 376: of the other two, so this will work for both 0-8 and 0-9-1 branches of
! 377: the code.
! 378: */
! 379:
! 380: /**
! 381: * A field table value
! 382: *
! 383: * \since v0.1
! 384: */
! 385: typedef struct amqp_field_value_t_ {
! 386: uint8_t kind; /**< the type of the entry /sa amqp_field_value_kind_t */
! 387: union {
! 388: amqp_boolean_t boolean; /**< boolean type AMQP_FIELD_KIND_BOOLEAN */
! 389: int8_t i8; /**< int8_t type AMQP_FIELD_KIND_I8 */
! 390: uint8_t u8; /**< uint8_t type AMQP_FIELD_KIND_U8 */
! 391: int16_t i16; /**< int16_t type AMQP_FIELD_KIND_I16 */
! 392: uint16_t u16; /**< uint16_t type AMQP_FIELD_KIND_U16 */
! 393: int32_t i32; /**< int32_t type AMQP_FIELD_KIND_I32 */
! 394: uint32_t u32; /**< uint32_t type AMQP_FIELD_KIND_U32 */
! 395: int64_t i64; /**< int64_t type AMQP_FIELD_KIND_I64 */
! 396: uint64_t u64; /**< uint64_t type AMQP_FIELD_KIND_U64,
! 397: AMQP_FIELD_KIND_TIMESTAMP */
! 398: float f32; /**< float type AMQP_FIELD_KIND_F32 */
! 399: double f64; /**< double type AMQP_FIELD_KIND_F64 */
! 400: amqp_decimal_t decimal; /**< amqp_decimal_t AMQP_FIELD_KIND_DECIMAL */
! 401: amqp_bytes_t bytes; /**< amqp_bytes_t type AMQP_FIELD_KIND_UTF8,
! 402: AMQP_FIELD_KIND_BYTES */
! 403: amqp_table_t table; /**< amqp_table_t type AMQP_FIELD_KIND_TABLE */
! 404: amqp_array_t array; /**< amqp_array_t type AMQP_FIELD_KIND_ARRAY */
! 405: } value; /**< a union of the value */
! 406: } amqp_field_value_t;
! 407:
! 408: /**
! 409: * An entry in a field-table
! 410: *
! 411: * \sa amqp_table_encode(), amqp_table_decode(), amqp_table_clone()
! 412: *
! 413: * \since v0.1
! 414: */
! 415: typedef struct amqp_table_entry_t_ {
! 416: amqp_bytes_t key; /**< the table entry key. Its a null-terminated UTF-8
! 417: * string, with a maximum size of 128 bytes */
! 418: amqp_field_value_t value; /**< the table entry values */
! 419: } amqp_table_entry_t;
! 420:
! 421: /**
! 422: * Field value types
! 423: *
! 424: * \since v0.1
! 425: */
! 426: typedef enum {
! 427: AMQP_FIELD_KIND_BOOLEAN =
! 428: 't', /**< boolean type. 0 = false, 1 = true @see amqp_boolean_t */
! 429: AMQP_FIELD_KIND_I8 = 'b', /**< 8-bit signed integer, datatype: int8_t */
! 430: AMQP_FIELD_KIND_U8 = 'B', /**< 8-bit unsigned integer, datatype: uint8_t */
! 431: AMQP_FIELD_KIND_I16 = 's', /**< 16-bit signed integer, datatype: int16_t */
! 432: AMQP_FIELD_KIND_U16 = 'u', /**< 16-bit unsigned integer, datatype: uint16_t */
! 433: AMQP_FIELD_KIND_I32 = 'I', /**< 32-bit signed integer, datatype: int32_t */
! 434: AMQP_FIELD_KIND_U32 = 'i', /**< 32-bit unsigned integer, datatype: uint32_t */
! 435: AMQP_FIELD_KIND_I64 = 'l', /**< 64-bit signed integer, datatype: int64_t */
! 436: AMQP_FIELD_KIND_U64 = 'L', /**< 64-bit unsigned integer, datatype: uint64_t */
! 437: AMQP_FIELD_KIND_F32 =
! 438: 'f', /**< single-precision floating point value, datatype: float */
! 439: AMQP_FIELD_KIND_F64 =
! 440: 'd', /**< double-precision floating point value, datatype: double */
! 441: AMQP_FIELD_KIND_DECIMAL =
! 442: 'D', /**< amqp-decimal value, datatype: amqp_decimal_t */
! 443: AMQP_FIELD_KIND_UTF8 = 'S', /**< UTF-8 null-terminated character string,
! 444: datatype: amqp_bytes_t */
! 445: AMQP_FIELD_KIND_ARRAY = 'A', /**< field array (repeated values of another
! 446: datatype. datatype: amqp_array_t */
! 447: AMQP_FIELD_KIND_TIMESTAMP = 'T', /**< 64-bit timestamp. datatype uint64_t */
! 448: AMQP_FIELD_KIND_TABLE = 'F', /**< field table. encapsulates a table inside a
! 449: table entry. datatype: amqp_table_t */
! 450: AMQP_FIELD_KIND_VOID = 'V', /**< empty entry */
! 451: AMQP_FIELD_KIND_BYTES =
! 452: 'x' /**< unformatted byte string, datatype: amqp_bytes_t */
! 453: } amqp_field_value_kind_t;
! 454:
! 455: /**
! 456: * A list of allocation blocks
! 457: *
! 458: * \since v0.1
! 459: */
! 460: typedef struct amqp_pool_blocklist_t_ {
! 461: int num_blocks; /**< Number of blocks in the block list */
! 462: void **blocklist; /**< Array of memory blocks */
! 463: } amqp_pool_blocklist_t;
! 464:
! 465: /**
! 466: * A memory pool
! 467: *
! 468: * \since v0.1
! 469: */
! 470: typedef struct amqp_pool_t_ {
! 471: size_t pagesize; /**< the size of the page in bytes. Allocations less than or
! 472: * equal to this size are allocated in the pages block list.
! 473: * Allocations greater than this are allocated in their own
! 474: * own block in the large_blocks block list */
! 475:
! 476: amqp_pool_blocklist_t pages; /**< blocks that are the size of pagesize */
! 477: amqp_pool_blocklist_t large_blocks; /**< allocations larger than the pagesize
! 478: */
! 479:
! 480: int next_page; /**< an index to the next unused page block */
! 481: char *alloc_block; /**< pointer to the current allocation block */
! 482: size_t alloc_used; /**< number of bytes in the current allocation block that
! 483: has been used */
! 484: } amqp_pool_t;
! 485:
! 486: /**
! 487: * An amqp method
! 488: *
! 489: * \since v0.1
! 490: */
! 491: typedef struct amqp_method_t_ {
! 492: amqp_method_number_t id; /**< the method id number */
! 493: void *decoded; /**< pointer to the decoded method,
! 494: * cast to the appropriate type to use */
! 495: } amqp_method_t;
! 496:
! 497: /**
! 498: * An AMQP frame
! 499: *
! 500: * \since v0.1
! 501: */
! 502: typedef struct amqp_frame_t_ {
! 503: uint8_t frame_type; /**< frame type. The types:
! 504: * - AMQP_FRAME_METHOD - use the method union member
! 505: * - AMQP_FRAME_HEADER - use the properties union member
! 506: * - AMQP_FRAME_BODY - use the body_fragment union member
! 507: */
! 508: amqp_channel_t channel; /**< the channel the frame was received on */
! 509: union {
! 510: amqp_method_t method; /**< a method, use if frame_type == AMQP_FRAME_METHOD
! 511: */
! 512: struct {
! 513: uint16_t class_id; /**< the class for the properties */
! 514: uint64_t body_size; /**< size of the body in bytes */
! 515: void *decoded; /**< the decoded properties */
! 516: amqp_bytes_t raw; /**< amqp-encoded properties structure */
! 517: } properties; /**< message header, a.k.a., properties,
! 518: use if frame_type == AMQP_FRAME_HEADER */
! 519: amqp_bytes_t body_fragment; /**< a body fragment, use if frame_type ==
! 520: AMQP_FRAME_BODY */
! 521: struct {
! 522: uint8_t transport_high; /**< @internal first byte of handshake */
! 523: uint8_t transport_low; /**< @internal second byte of handshake */
! 524: uint8_t protocol_version_major; /**< @internal third byte of handshake */
! 525: uint8_t protocol_version_minor; /**< @internal fourth byte of handshake */
! 526: } protocol_header; /**< Used only when doing the initial handshake with the
! 527: broker, don't use otherwise */
! 528: } payload; /**< the payload of the frame */
! 529: } amqp_frame_t;
! 530:
! 531: /**
! 532: * Response type
! 533: *
! 534: * \since v0.1
! 535: */
! 536: typedef enum amqp_response_type_enum_ {
! 537: AMQP_RESPONSE_NONE = 0, /**< the library got an EOF from the socket */
! 538: AMQP_RESPONSE_NORMAL, /**< response normal, the RPC completed successfully */
! 539: AMQP_RESPONSE_LIBRARY_EXCEPTION, /**< library error, an error occurred in the
! 540: library, examine the library_error */
! 541: AMQP_RESPONSE_SERVER_EXCEPTION /**< server exception, the broker returned an
! 542: error, check replay */
! 543: } amqp_response_type_enum;
! 544:
! 545: /**
! 546: * Reply from a RPC method on the broker
! 547: *
! 548: * \since v0.1
! 549: */
! 550: typedef struct amqp_rpc_reply_t_ {
! 551: amqp_response_type_enum reply_type; /**< the reply type:
! 552: * - AMQP_RESPONSE_NORMAL - the RPC
! 553: * completed successfully
! 554: * - AMQP_RESPONSE_SERVER_EXCEPTION - the
! 555: * broker returned
! 556: * an exception, check the reply field
! 557: * - AMQP_RESPONSE_LIBRARY_EXCEPTION - the
! 558: * library
! 559: * encountered an error, check the
! 560: * library_error field
! 561: */
! 562: amqp_method_t reply; /**< in case of AMQP_RESPONSE_SERVER_EXCEPTION this
! 563: * field will be set to the method returned from the
! 564: * broker */
! 565: int library_error; /**< in case of AMQP_RESPONSE_LIBRARY_EXCEPTION this
! 566: * field will be set to an error code. An error
! 567: * string can be retrieved using amqp_error_string */
! 568: } amqp_rpc_reply_t;
! 569:
! 570: /**
! 571: * SASL method type
! 572: *
! 573: * \since v0.1
! 574: */
! 575: typedef enum amqp_sasl_method_enum_ {
! 576: AMQP_SASL_METHOD_UNDEFINED = -1, /**< Invalid SASL method */
! 577: AMQP_SASL_METHOD_PLAIN =
! 578: 0, /**< the PLAIN SASL method for authentication to the broker */
! 579: AMQP_SASL_METHOD_EXTERNAL =
! 580: 1 /**< the EXTERNAL SASL method for authentication to the broker */
! 581: } amqp_sasl_method_enum;
! 582:
! 583: /**
! 584: * connection state object
! 585: *
! 586: * \since v0.1
! 587: */
! 588: typedef struct amqp_connection_state_t_ *amqp_connection_state_t;
! 589:
! 590: /**
! 591: * Socket object
! 592: *
! 593: * \since v0.4.0
! 594: */
! 595: typedef struct amqp_socket_t_ amqp_socket_t;
! 596:
! 597: /**
! 598: * Status codes
! 599: *
! 600: * \since v0.4.0
! 601: */
! 602: /* NOTE: When updating this enum, update the strings in librabbitmq/amqp_api.c
! 603: */
! 604: typedef enum amqp_status_enum_ {
! 605: AMQP_STATUS_OK = 0x0, /**< Operation successful */
! 606: AMQP_STATUS_NO_MEMORY = -0x0001, /**< Memory allocation
! 607: failed */
! 608: AMQP_STATUS_BAD_AMQP_DATA = -0x0002, /**< Incorrect or corrupt
! 609: data was received from
! 610: the broker. This is a
! 611: protocol error. */
! 612: AMQP_STATUS_UNKNOWN_CLASS = -0x0003, /**< An unknown AMQP class
! 613: was received. This is
! 614: a protocol error. */
! 615: AMQP_STATUS_UNKNOWN_METHOD = -0x0004, /**< An unknown AMQP method
! 616: was received. This is
! 617: a protocol error. */
! 618: AMQP_STATUS_HOSTNAME_RESOLUTION_FAILED = -0x0005, /**< Unable to resolve the
! 619: * hostname */
! 620: AMQP_STATUS_INCOMPATIBLE_AMQP_VERSION = -0x0006, /**< The broker advertised
! 621: an incompaible AMQP
! 622: version */
! 623: AMQP_STATUS_CONNECTION_CLOSED = -0x0007, /**< The connection to the
! 624: broker has been closed
! 625: */
! 626: AMQP_STATUS_BAD_URL = -0x0008, /**< malformed AMQP URL */
! 627: AMQP_STATUS_SOCKET_ERROR = -0x0009, /**< A socket error
! 628: occurred */
! 629: AMQP_STATUS_INVALID_PARAMETER = -0x000A, /**< An invalid parameter
! 630: was passed into the
! 631: function */
! 632: AMQP_STATUS_TABLE_TOO_BIG = -0x000B, /**< The amqp_table_t object
! 633: cannot be serialized
! 634: because the output
! 635: buffer is too small */
! 636: AMQP_STATUS_WRONG_METHOD = -0x000C, /**< The wrong method was
! 637: received */
! 638: AMQP_STATUS_TIMEOUT = -0x000D, /**< Operation timed out */
! 639: AMQP_STATUS_TIMER_FAILURE = -0x000E, /**< The underlying system
! 640: timer facility failed */
! 641: AMQP_STATUS_HEARTBEAT_TIMEOUT = -0x000F, /**< Timed out waiting for
! 642: heartbeat */
! 643: AMQP_STATUS_UNEXPECTED_STATE = -0x0010, /**< Unexpected protocol
! 644: state */
! 645: AMQP_STATUS_SOCKET_CLOSED = -0x0011, /**< Underlying socket is
! 646: closed */
! 647: AMQP_STATUS_SOCKET_INUSE = -0x0012, /**< Underlying socket is
! 648: already open */
! 649: AMQP_STATUS_BROKER_UNSUPPORTED_SASL_METHOD = -0x0013, /**< Broker does not
! 650: support the requested
! 651: SASL mechanism */
! 652: AMQP_STATUS_UNSUPPORTED = -0x0014, /**< Parameter is unsupported
! 653: in this version */
! 654: _AMQP_STATUS_NEXT_VALUE = -0x0015, /**< Internal value */
! 655:
! 656: AMQP_STATUS_TCP_ERROR = -0x0100, /**< A generic TCP error
! 657: occurred */
! 658: AMQP_STATUS_TCP_SOCKETLIB_INIT_ERROR = -0x0101, /**< An error occurred trying
! 659: to initialize the
! 660: socket library*/
! 661: _AMQP_STATUS_TCP_NEXT_VALUE = -0x0102, /**< Internal value */
! 662:
! 663: AMQP_STATUS_SSL_ERROR = -0x0200, /**< A generic SSL error
! 664: occurred. */
! 665: AMQP_STATUS_SSL_HOSTNAME_VERIFY_FAILED = -0x0201, /**< SSL validation of
! 666: hostname against
! 667: peer certificate
! 668: failed */
! 669: AMQP_STATUS_SSL_PEER_VERIFY_FAILED = -0x0202, /**< SSL validation of peer
! 670: certificate failed. */
! 671: AMQP_STATUS_SSL_CONNECTION_FAILED = -0x0203, /**< SSL handshake failed. */
! 672: AMQP_STATUS_SSL_SET_ENGINE_FAILED = -0x0204, /**< SSL setting engine failed */
! 673: AMQP_STATUS_SSL_UNIMPLEMENTED = -0x0205, /**< SSL API is not implemented. */
! 674: _AMQP_STATUS_SSL_NEXT_VALUE = -0x0206 /**< Internal value */
! 675: } amqp_status_enum;
! 676:
! 677: /**
! 678: * AMQP delivery modes.
! 679: * Use these values for the #amqp_basic_properties_t::delivery_mode field.
! 680: *
! 681: * \since v0.5
! 682: */
! 683: typedef enum {
! 684: AMQP_DELIVERY_NONPERSISTENT = 1, /**< Non-persistent message */
! 685: AMQP_DELIVERY_PERSISTENT = 2 /**< Persistent message */
! 686: } amqp_delivery_mode_enum;
! 687:
! 688: AMQP_END_DECLS
! 689:
! 690: #include <rabbitmq-c/framing.h>
! 691:
! 692: AMQP_BEGIN_DECLS
! 693:
! 694: /**
! 695: * Empty bytes structure
! 696: *
! 697: * \since v0.2
! 698: */
! 699: AMQP_EXPORT extern const amqp_bytes_t amqp_empty_bytes;
! 700:
! 701: /**
! 702: * Empty table structure
! 703: *
! 704: * \since v0.2
! 705: */
! 706: AMQP_EXPORT extern const amqp_table_t amqp_empty_table;
! 707:
! 708: /**
! 709: * Empty table array structure
! 710: *
! 711: * \since v0.2
! 712: */
! 713: AMQP_EXPORT extern const amqp_array_t amqp_empty_array;
! 714:
! 715: /* Compatibility macros for the above, to avoid the need to update
! 716: code written against earlier versions of librabbitmq. */
! 717:
! 718: /**
! 719: * \def AMQP_EMPTY_BYTES
! 720: *
! 721: * Deprecated, use \ref amqp_empty_bytes instead
! 722: *
! 723: * \deprecated use \ref amqp_empty_bytes instead
! 724: *
! 725: * \since v0.1
! 726: */
! 727: #define AMQP_EMPTY_BYTES amqp_empty_bytes
! 728:
! 729: /**
! 730: * \def AMQP_EMPTY_TABLE
! 731: *
! 732: * Deprecated, use \ref amqp_empty_table instead
! 733: *
! 734: * \deprecated use \ref amqp_empty_table instead
! 735: *
! 736: * \since v0.1
! 737: */
! 738: #define AMQP_EMPTY_TABLE amqp_empty_table
! 739:
! 740: /**
! 741: * \def AMQP_EMPTY_ARRAY
! 742: *
! 743: * Deprecated, use \ref amqp_empty_array instead
! 744: *
! 745: * \deprecated use \ref amqp_empty_array instead
! 746: *
! 747: * \since v0.1
! 748: */
! 749: #define AMQP_EMPTY_ARRAY amqp_empty_array
! 750:
! 751: /**
! 752: * Initializes an amqp_pool_t memory allocation pool for use
! 753: *
! 754: * Readies an allocation pool for use. An amqp_pool_t
! 755: * must be initialized before use
! 756: *
! 757: * \param [in] pool the amqp_pool_t structure to initialize.
! 758: * Calling this function on a pool a pool that has
! 759: * already been initialized will result in undefined
! 760: * behavior
! 761: * \param [in] pagesize the unit size that the pool will allocate
! 762: * memory chunks in. Anything allocated against the pool
! 763: * with a requested size will be carved out of a block
! 764: * this size. Allocations larger than this will be
! 765: * allocated individually
! 766: *
! 767: * \sa recycle_amqp_pool(), empty_amqp_pool(), amqp_pool_alloc(),
! 768: * amqp_pool_alloc_bytes(), amqp_pool_t
! 769: *
! 770: * \since v0.1
! 771: */
! 772: AMQP_EXPORT
! 773: void AMQP_CALL init_amqp_pool(amqp_pool_t *pool, size_t pagesize);
! 774:
! 775: /**
! 776: * Recycles an amqp_pool_t memory allocation pool
! 777: *
! 778: * Recycles the space allocate by the pool
! 779: *
! 780: * This invalidates all allocations made against the pool before this call is
! 781: * made, any use of any allocations made before recycle_amqp_pool() is called
! 782: * will result in undefined behavior.
! 783: *
! 784: * Note: this may or may not release memory, to force memory to be released
! 785: * call empty_amqp_pool().
! 786: *
! 787: * \param [in] pool the amqp_pool_t to recycle
! 788: *
! 789: * \sa recycle_amqp_pool(), empty_amqp_pool(), amqp_pool_alloc(),
! 790: * amqp_pool_alloc_bytes()
! 791: *
! 792: * \since v0.1
! 793: *
! 794: */
! 795: AMQP_EXPORT
! 796: void AMQP_CALL recycle_amqp_pool(amqp_pool_t *pool);
! 797:
! 798: /**
! 799: * Empties an amqp memory pool
! 800: *
! 801: * Releases all memory associated with an allocation pool
! 802: *
! 803: * \param [in] pool the amqp_pool_t to empty
! 804: *
! 805: * \since v0.1
! 806: */
! 807: AMQP_EXPORT
! 808: void AMQP_CALL empty_amqp_pool(amqp_pool_t *pool);
! 809:
! 810: /**
! 811: * Allocates a block of memory from an amqp_pool_t memory pool
! 812: *
! 813: * Memory will be aligned on a 8-byte boundary. If a 0-length allocation is
! 814: * requested, a NULL pointer will be returned.
! 815: *
! 816: * \param [in] pool the allocation pool to allocate the memory from
! 817: * \param [in] amount the size of the allocation in bytes.
! 818: * \return a pointer to the memory block, or NULL if the allocation cannot
! 819: * be satisfied.
! 820: *
! 821: * \sa init_amqp_pool(), recycle_amqp_pool(), empty_amqp_pool(),
! 822: * amqp_pool_alloc_bytes()
! 823: *
! 824: * \since v0.1
! 825: */
! 826: AMQP_EXPORT
! 827: void *AMQP_CALL amqp_pool_alloc(amqp_pool_t *pool, size_t amount);
! 828:
! 829: /**
! 830: * Allocates a block of memory from an amqp_pool_t to an amqp_bytes_t
! 831: *
! 832: * Memory will be aligned on a 8-byte boundary. If a 0-length allocation is
! 833: * requested, output.bytes = NULL.
! 834: *
! 835: * \param [in] pool the allocation pool to allocate the memory from
! 836: * \param [in] amount the size of the allocation in bytes
! 837: * \param [in] output the location to store the pointer. On success
! 838: * output.bytes will be set to the beginning of the buffer
! 839: * output.len will be set to amount
! 840: * On error output.bytes will be set to NULL and output.len
! 841: * set to 0
! 842: *
! 843: * \sa init_amqp_pool(), recycle_amqp_pool(), empty_amqp_pool(),
! 844: * amqp_pool_alloc()
! 845: *
! 846: * \since v0.1
! 847: */
! 848: AMQP_EXPORT
! 849: void AMQP_CALL amqp_pool_alloc_bytes(amqp_pool_t *pool, size_t amount,
! 850: amqp_bytes_t *output);
! 851:
! 852: /**
! 853: * Wraps a c string literal in an amqp_bytes_t
! 854: *
! 855: * Takes a string literal, calculates its length and creates an
! 856: * amqp_bytes_t that points to it. The string literal is not duplicated.
! 857: *
! 858: * For a given input str, The amqp_bytes_t output.bytes is the
! 859: * same as str, output.len is the length of the string literal not including
! 860: * the \0 terminator
! 861: *
! 862: * \param [in] str the c string literal to wrap
! 863: * \return an amqp_bytes_t that describes the string literal
! 864: *
! 865: * \since v0.15
! 866: */
! 867: #define amqp_literal_bytes(str) (amqp_bytes_t){sizeof(str) - 1, (void *)str}
! 868:
! 869: /**
! 870: * Wraps a c string in an amqp_bytes_t
! 871: *
! 872: * Takes a string, calculates its length and creates an
! 873: * amqp_bytes_t that points to it. The string is not duplicated.
! 874: *
! 875: * For a given input cstr, The amqp_bytes_t output.bytes is the
! 876: * same as cstr, output.len is the length of the string not including
! 877: * the \0 terminator
! 878: *
! 879: * This function uses strlen() internally so cstr must be properly
! 880: * terminated
! 881: *
! 882: * \param [in] cstr the c string to wrap
! 883: * \return an amqp_bytes_t that describes the string
! 884: *
! 885: * \since v0.1
! 886: */
! 887: AMQP_EXPORT
! 888: amqp_bytes_t AMQP_CALL amqp_cstring_bytes(char const *cstr);
! 889:
! 890: /**
! 891: * Wraps a string of bytes in an amqp_bytes_t
! 892: *
! 893: * Takes a string of bytes and its length and creates an
! 894: * amqp_bytes_t that points to it. The input is not duplicated.
! 895: *
! 896: * \param [in] ptr the string of bytes to wrap
! 897: * \param [in] length the length of the string
! 898: * \return an amqp_bytes_t that describes the string
! 899: *
! 900: * \since v0.16
! 901: */
! 902: #define amqp_bytes_from_buffer(ptr, length) (amqp_bytes_t){length, (void *)ptr}
! 903:
! 904: /**
! 905: * Duplicates an amqp_bytes_t buffer.
! 906: *
! 907: * The buffer is cloned and the contents copied.
! 908: *
! 909: * The memory associated with the output is allocated
! 910: * with amqp_bytes_malloc() and should be freed with
! 911: * amqp_bytes_free()
! 912: *
! 913: * \param [in] src
! 914: * \return a clone of the src
! 915: *
! 916: * \sa amqp_bytes_free(), amqp_bytes_malloc()
! 917: *
! 918: * \since v0.1
! 919: */
! 920: AMQP_EXPORT
! 921: amqp_bytes_t AMQP_CALL amqp_bytes_malloc_dup(amqp_bytes_t src);
! 922:
! 923: /**
! 924: * Allocates a amqp_bytes_t buffer
! 925: *
! 926: * Creates an amqp_bytes_t buffer of the specified amount, the buffer should be
! 927: * freed using amqp_bytes_free()
! 928: *
! 929: * \param [in] amount the size of the buffer in bytes
! 930: * \returns an amqp_bytes_t with amount bytes allocated.
! 931: * output.bytes will be set to NULL on error
! 932: *
! 933: * \sa amqp_bytes_free(), amqp_bytes_malloc_dup()
! 934: *
! 935: * \since v0.1
! 936: */
! 937: AMQP_EXPORT
! 938: amqp_bytes_t AMQP_CALL amqp_bytes_malloc(size_t amount);
! 939:
! 940: /**
! 941: * Frees an amqp_bytes_t buffer
! 942: *
! 943: * Frees a buffer allocated with amqp_bytes_malloc() or amqp_bytes_malloc_dup()
! 944: *
! 945: * Calling amqp_bytes_free on buffers not allocated with one
! 946: * of those two functions will result in undefined behavior
! 947: *
! 948: * \param [in] bytes the buffer to free
! 949: *
! 950: * \sa amqp_bytes_malloc(), amqp_bytes_malloc_dup()
! 951: *
! 952: * \since v0.1
! 953: */
! 954: AMQP_EXPORT
! 955: void AMQP_CALL amqp_bytes_free(amqp_bytes_t bytes);
! 956:
! 957: /**
! 958: * Allocate and initialize a new amqp_connection_state_t object
! 959: *
! 960: * amqp_connection_state_t objects created with this function
! 961: * should be freed with amqp_destroy_connection()
! 962: *
! 963: * \returns an opaque pointer on success, NULL or 0 on failure.
! 964: *
! 965: * \sa amqp_destroy_connection()
! 966: *
! 967: * \since v0.1
! 968: */
! 969: AMQP_EXPORT
! 970: amqp_connection_state_t AMQP_CALL amqp_new_connection(void);
! 971:
! 972: /**
! 973: * Get the underlying socket descriptor for the connection
! 974: *
! 975: * \warning Use the socket returned from this function carefully, incorrect use
! 976: * of the socket outside of the library will lead to undefined behavior.
! 977: * Additionally rabbitmq-c may use the socket differently version-to-version,
! 978: * what may work in one version, may break in the next version. Be sure to
! 979: * thoroughly test any applications that use the socket returned by this
! 980: * function especially when using a newer version of rabbitmq-c
! 981: *
! 982: * \param [in] state the connection object
! 983: * \returns the socket descriptor if one has been set, -1 otherwise
! 984: *
! 985: * \sa amqp_tcp_socket_new(), amqp_ssl_socket_new(), amqp_socket_open()
! 986: *
! 987: * \since v0.1
! 988: */
! 989: AMQP_EXPORT
! 990: int AMQP_CALL amqp_get_sockfd(amqp_connection_state_t state);
! 991:
! 992: /**
! 993: * Deprecated, use amqp_tcp_socket_new() or amqp_ssl_socket_new()
! 994: *
! 995: * \deprecated Use amqp_tcp_socket_new() or amqp_ssl_socket_new()
! 996: *
! 997: * Sets the socket descriptor associated with the connection. The socket
! 998: * should be connected to a broker, and should not be read to or written from
! 999: * before calling this function. A socket descriptor can be created and opened
! 1000: * using amqp_open_socket()
! 1001: *
! 1002: * \param [in] state the connection object
! 1003: * \param [in] sockfd the socket
! 1004: *
! 1005: * \sa amqp_open_socket(), amqp_tcp_socket_new(), amqp_ssl_socket_new()
! 1006: *
! 1007: * \since v0.1
! 1008: */
! 1009: AMQP_DEPRECATED_EXPORT void AMQP_CALL
! 1010: amqp_set_sockfd(amqp_connection_state_t state, int sockfd);
! 1011:
! 1012: /**
! 1013: * Tune client side parameters
! 1014: *
! 1015: * \warning This function may call abort() if the connection is in a certain
! 1016: * state. As such it should probably not be called code outside the library.
! 1017: * connection parameters should be specified when calling amqp_login() or
! 1018: * amqp_login_with_properties()
! 1019: *
! 1020: * This function changes channel_max, frame_max, and heartbeat parameters, on
! 1021: * the client side only. It does not try to renegotiate these parameters with
! 1022: * the broker. Using this function will lead to unexpected results.
! 1023: *
! 1024: * \param [in] state the connection object
! 1025: * \param [in] channel_max the maximum number of channels.
! 1026: * The largest this can be is 65535
! 1027: * \param [in] frame_max the maximum size of an frame.
! 1028: * The smallest this can be is 4096
! 1029: * The largest this can be is 2147483647
! 1030: * Unless you know what you're doing the recommended
! 1031: * size is 131072 or 128KB
! 1032: * \param [in] heartbeat the number of seconds between heartbeats
! 1033: *
! 1034: * \return AMQP_STATUS_OK on success, an amqp_status_enum value otherwise.
! 1035: * Possible error codes include:
! 1036: * - AMQP_STATUS_NO_MEMORY memory allocation failed.
! 1037: * - AMQP_STATUS_TIMER_FAILURE the underlying system timer indicated it
! 1038: * failed.
! 1039: *
! 1040: * \sa amqp_login(), amqp_login_with_properties()
! 1041: *
! 1042: * \since v0.1
! 1043: */
! 1044: AMQP_EXPORT
! 1045: int AMQP_CALL amqp_tune_connection(amqp_connection_state_t state,
! 1046: int channel_max, int frame_max,
! 1047: int heartbeat);
! 1048:
! 1049: /**
! 1050: * Get the maximum number of channels the connection can handle
! 1051: *
! 1052: * The maximum number of channels is set when connection negotiation takes
! 1053: * place in amqp_login() or amqp_login_with_properties().
! 1054: *
! 1055: * \param [in] state the connection object
! 1056: * \return the maximum number of channels. 0 if there is no limit
! 1057: *
! 1058: * \since v0.1
! 1059: */
! 1060: AMQP_EXPORT
! 1061: int AMQP_CALL amqp_get_channel_max(amqp_connection_state_t state);
! 1062:
! 1063: /**
! 1064: * Get the maximum size of an frame the connection can handle
! 1065: *
! 1066: * The maximum size of an frame is set when connection negotiation takes
! 1067: * place in amqp_login() or amqp_login_with_properties().
! 1068: *
! 1069: * \param [in] state the connection object
! 1070: * \return the maximum size of an frame.
! 1071: *
! 1072: * \since v0.6
! 1073: */
! 1074: AMQP_EXPORT
! 1075: int AMQP_CALL amqp_get_frame_max(amqp_connection_state_t state);
! 1076:
! 1077: /**
! 1078: * Get the number of seconds between heartbeats of the connection
! 1079: *
! 1080: * The number of seconds between heartbeats is set when connection
! 1081: * negotiation takes place in amqp_login() or amqp_login_with_properties().
! 1082: *
! 1083: * \param [in] state the connection object
! 1084: * \return the number of seconds between heartbeats.
! 1085: *
! 1086: * \since v0.6
! 1087: */
! 1088: AMQP_EXPORT
! 1089: int AMQP_CALL amqp_get_heartbeat(amqp_connection_state_t state);
! 1090:
! 1091: /**
! 1092: * Destroys an amqp_connection_state_t object
! 1093: *
! 1094: * Destroys a amqp_connection_state_t object that was created with
! 1095: * amqp_new_connection(). If the connection with the broker is open, it will be
! 1096: * implicitly closed with a reply code of 200 (success). Any memory that
! 1097: * would be freed with amqp_maybe_release_buffers() or
! 1098: * amqp_maybe_release_buffers_on_channel() will be freed, and use of that
! 1099: * memory will caused undefined behavior.
! 1100: *
! 1101: * \param [in] state the connection object
! 1102: * \return AMQP_STATUS_OK on success. amqp_status_enum value failure
! 1103: *
! 1104: * \sa amqp_new_connection()
! 1105: *
! 1106: * \since v0.1
! 1107: */
! 1108: AMQP_EXPORT
! 1109: int AMQP_CALL amqp_destroy_connection(amqp_connection_state_t state);
! 1110:
! 1111: /**
! 1112: * Process incoming data
! 1113: *
! 1114: * \warning This is a low-level function intended for those who want to
! 1115: * have greater control over input and output over the socket from the
! 1116: * broker. Correctly using this function requires in-depth knowledge of AMQP
! 1117: * and rabbitmq-c.
! 1118: *
! 1119: * For a given buffer of data received from the broker, decode the first
! 1120: * frame in the buffer. If more than one frame is contained in the input buffer
! 1121: * the return value will be less than the received_data size, the caller should
! 1122: * adjust received_data buffer descriptor to point to the beginning of the
! 1123: * buffer + the return value.
! 1124: *
! 1125: * \param [in] state the connection object
! 1126: * \param [in] received_data a buffer of data received from the broker. The
! 1127: * function will return the number of bytes of the buffer it used. The
! 1128: * function copies these bytes to an internal buffer: this part of the buffer
! 1129: * may be reused after this function successfully completes.
! 1130: * \param [in,out] decoded_frame caller should pass in a pointer to an
! 1131: * amqp_frame_t struct. If there is enough data in received_data for a
! 1132: * complete frame, decoded_frame->frame_type will be set to something OTHER
! 1133: * than 0. decoded_frame may contain members pointing to memory owned by
! 1134: * the state object. This memory can be recycled with
! 1135: * amqp_maybe_release_buffers() or amqp_maybe_release_buffers_on_channel().
! 1136: * \return number of bytes consumed from received_data or 0 if a 0-length
! 1137: * buffer was passed. A negative return value indicates failure. Possible
! 1138: * errors:
! 1139: * - AMQP_STATUS_NO_MEMORY failure in allocating memory. The library is likely
! 1140: * in an indeterminate state making recovery unlikely. Client should note the
! 1141: * error and terminate the application
! 1142: * - AMQP_STATUS_BAD_AMQP_DATA bad AMQP data was received. The connection
! 1143: * should be shutdown immediately
! 1144: * - AMQP_STATUS_UNKNOWN_METHOD: an unknown method was received from the
! 1145: * broker. This is likely a protocol error and the connection should be
! 1146: * shutdown immediately
! 1147: * - AMQP_STATUS_UNKNOWN_CLASS: a properties frame with an unknown class
! 1148: * was received from the broker. This is likely a protocol error and the
! 1149: * connection should be shutdown immediately
! 1150: *
! 1151: * \since v0.1
! 1152: */
! 1153: AMQP_EXPORT
! 1154: int AMQP_CALL amqp_handle_input(amqp_connection_state_t state,
! 1155: amqp_bytes_t received_data,
! 1156: amqp_frame_t *decoded_frame);
! 1157:
! 1158: /**
! 1159: * Check to see if connection memory can be released
! 1160: *
! 1161: * \deprecated This function is deprecated in favor of
! 1162: * amqp_maybe_release_buffers() or amqp_maybe_release_buffers_on_channel()
! 1163: *
! 1164: * Checks the state of an amqp_connection_state_t object to see if
! 1165: * amqp_release_buffers() can be called successfully.
! 1166: *
! 1167: * \param [in] state the connection object
! 1168: * \returns TRUE if the buffers can be released FALSE otherwise
! 1169: *
! 1170: * \sa amqp_release_buffers() amqp_maybe_release_buffers()
! 1171: * amqp_maybe_release_buffers_on_channel()
! 1172: *
! 1173: * \since v0.1
! 1174: */
! 1175: AMQP_EXPORT
! 1176: amqp_boolean_t AMQP_CALL amqp_release_buffers_ok(amqp_connection_state_t state);
! 1177:
! 1178: /**
! 1179: * Release amqp_connection_state_t owned memory
! 1180: *
! 1181: * \deprecated This function is deprecated in favor of
! 1182: * amqp_maybe_release_buffers() or amqp_maybe_release_buffers_on_channel()
! 1183: *
! 1184: * \warning caller should ensure amqp_release_buffers_ok() returns true before
! 1185: * calling this function. Failure to do so may result in abort() being called.
! 1186: *
! 1187: * Release memory owned by the amqp_connection_state_t for reuse by the
! 1188: * library. Use of any memory returned by the library before this function is
! 1189: * called will result in undefined behavior.
! 1190: *
! 1191: * \note internally rabbitmq-c tries to reuse memory when possible. As a result
! 1192: * its possible calling this function may not have a noticeable effect on
! 1193: * memory usage.
! 1194: *
! 1195: * \param [in] state the connection object
! 1196: *
! 1197: * \sa amqp_release_buffers_ok() amqp_maybe_release_buffers()
! 1198: * amqp_maybe_release_buffers_on_channel()
! 1199: *
! 1200: * \since v0.1
! 1201: */
! 1202: AMQP_EXPORT
! 1203: void AMQP_CALL amqp_release_buffers(amqp_connection_state_t state);
! 1204:
! 1205: /**
! 1206: * Release amqp_connection_state_t owned memory
! 1207: *
! 1208: * Release memory owned by the amqp_connection_state_t object related to any
! 1209: * channel, allowing reuse by the library. Use of any memory returned by the
! 1210: * library before this function is called with result in undefined behavior.
! 1211: *
! 1212: * \note internally rabbitmq-c tries to reuse memory when possible. As a result
! 1213: * its possible calling this function may not have a noticeable effect on
! 1214: * memory usage.
! 1215: *
! 1216: * \param [in] state the connection object
! 1217: *
! 1218: * \sa amqp_maybe_release_buffers_on_channel()
! 1219: *
! 1220: * \since v0.1
! 1221: */
! 1222: AMQP_EXPORT
! 1223: void AMQP_CALL amqp_maybe_release_buffers(amqp_connection_state_t state);
! 1224:
! 1225: /**
! 1226: * Release amqp_connection_state_t owned memory related to a channel
! 1227: *
! 1228: * Release memory owned by the amqp_connection_state_t object related to the
! 1229: * specified channel, allowing reuse by the library. Use of any memory returned
! 1230: * the library for a specific channel will result in undefined behavior.
! 1231: *
! 1232: * \note internally rabbitmq-c tries to reuse memory when possible. As a result
! 1233: * its possible calling this function may not have a noticeable effect on
! 1234: * memory usage.
! 1235: *
! 1236: * \param [in] state the connection object
! 1237: * \param [in] channel the channel specifier for which memory should be
! 1238: * released. Note that the library does not care about the state of the
! 1239: * channel when calling this function
! 1240: *
! 1241: * \sa amqp_maybe_release_buffers()
! 1242: *
! 1243: * \since v0.4.0
! 1244: */
! 1245: AMQP_EXPORT
! 1246: void AMQP_CALL amqp_maybe_release_buffers_on_channel(
! 1247: amqp_connection_state_t state, amqp_channel_t channel);
! 1248:
! 1249: /**
! 1250: * Send a frame to the broker
! 1251: *
! 1252: * \param [in] state the connection object
! 1253: * \param [in] frame the frame to send to the broker
! 1254: * \return AMQP_STATUS_OK on success, an amqp_status_enum value on error.
! 1255: * Possible error codes:
! 1256: * - AMQP_STATUS_BAD_AMQP_DATA the serialized form of the method or
! 1257: * properties was too large to fit in a single AMQP frame, or the
! 1258: * method contains an invalid value. The frame was not sent.
! 1259: * - AMQP_STATUS_TABLE_TOO_BIG the serialized form of an amqp_table_t is
! 1260: * too large to fit in a single AMQP frame. Frame was not sent.
! 1261: * - AMQP_STATUS_UNKNOWN_METHOD an invalid method type was passed in
! 1262: * - AMQP_STATUS_UNKNOWN_CLASS an invalid properties type was passed in
! 1263: * - AMQP_STATUS_TIMER_FAILURE system timer indicated failure. The frame
! 1264: * was sent
! 1265: * - AMQP_STATUS_SOCKET_ERROR
! 1266: * - AMQP_STATUS_SSL_ERROR
! 1267: *
! 1268: * \since v0.1
! 1269: */
! 1270: AMQP_EXPORT
! 1271: int AMQP_CALL amqp_send_frame(amqp_connection_state_t state,
! 1272: amqp_frame_t const *frame);
! 1273:
! 1274: /**
! 1275: * Compare two table entries
! 1276: *
! 1277: * Works just like strcmp(), comparing two the table keys, datatype, then values
! 1278: *
! 1279: * \param [in] entry1 the entry on the left
! 1280: * \param [in] entry2 the entry on the right
! 1281: * \return 0 if entries are equal, 0 < if left is greater, 0 > if right is
! 1282: * greater
! 1283: *
! 1284: * \since v0.1
! 1285: */
! 1286: AMQP_EXPORT
! 1287: int AMQP_CALL amqp_table_entry_cmp(void const *entry1, void const *entry2);
! 1288:
! 1289: /**
! 1290: * Open a socket to a remote host
! 1291: *
! 1292: * \deprecated This function is deprecated in favor of amqp_socket_open()
! 1293: *
! 1294: * Looks up the hostname, then attempts to open a socket to the host using
! 1295: * the specified portnumber. It also sets various options on the socket to
! 1296: * improve performance and correctness.
! 1297: *
! 1298: * \param [in] hostname this can be a hostname or IP address.
! 1299: * Both IPv4 and IPv6 are acceptable
! 1300: * \param [in] portnumber the port to connect on. RabbitMQ brokers
! 1301: * listen on port 5672, and 5671 for SSL
! 1302: * \return a positive value indicates success and is the sockfd. A negative
! 1303: * value (see amqp_status_enum)is returned on failure. Possible error codes:
! 1304: * - AMQP_STATUS_TCP_SOCKETLIB_INIT_ERROR Initialization of underlying socket
! 1305: * library failed.
! 1306: * - AMQP_STATUS_HOSTNAME_RESOLUTION_FAILED hostname lookup failed.
! 1307: * - AMQP_STATUS_SOCKET_ERROR a socket error occurred. errno or
! 1308: * WSAGetLastError() may return more useful information.
! 1309: *
! 1310: * \note IPv6 support was added in v0.3
! 1311: *
! 1312: * \sa amqp_socket_open() amqp_set_sockfd()
! 1313: *
! 1314: * \since v0.1
! 1315: */
! 1316: AMQP_EXPORT
! 1317: int AMQP_CALL amqp_open_socket(char const *hostname, int portnumber);
! 1318:
! 1319: /**
! 1320: * Send initial AMQP header to the broker
! 1321: *
! 1322: * \warning this is a low level function intended for those who want to
! 1323: * interact with the broker at a very low level. Use of this function without
! 1324: * understanding what it does will result in AMQP protocol errors.
! 1325: *
! 1326: * This function sends the AMQP protocol header to the broker.
! 1327: *
! 1328: * \param [in] state the connection object
! 1329: * \return AMQP_STATUS_OK on success, a negative value on failure. Possible
! 1330: * error codes:
! 1331: * - AMQP_STATUS_CONNECTION_CLOSED the connection to the broker was closed.
! 1332: * - AMQP_STATUS_SOCKET_ERROR a socket error occurred. It is likely the
! 1333: * underlying socket has been closed. errno or WSAGetLastError() may provide
! 1334: * further information.
! 1335: * - AMQP_STATUS_SSL_ERROR a SSL error occurred. The connection to the broker
! 1336: * was closed.
! 1337: *
! 1338: * \since v0.1
! 1339: */
! 1340: AMQP_EXPORT
! 1341: int AMQP_CALL amqp_send_header(amqp_connection_state_t state);
! 1342:
! 1343: /**
! 1344: * Checks to see if there are any incoming frames ready to be read
! 1345: *
! 1346: * Checks to see if there are any amqp_frame_t objects buffered by the
! 1347: * amqp_connection_state_t object. Having one or more frames buffered means
! 1348: * that amqp_simple_wait_frame() or amqp_simple_wait_frame_noblock() will
! 1349: * return a frame without potentially blocking on a read() call.
! 1350: *
! 1351: * \param [in] state the connection object
! 1352: * \return TRUE if there are frames enqueued, FALSE otherwise
! 1353: *
! 1354: * \sa amqp_simple_wait_frame() amqp_simple_wait_frame_noblock()
! 1355: * amqp_data_in_buffer()
! 1356: *
! 1357: * \since v0.1
! 1358: */
! 1359: AMQP_EXPORT
! 1360: amqp_boolean_t AMQP_CALL amqp_frames_enqueued(amqp_connection_state_t state);
! 1361:
! 1362: /**
! 1363: * Read a single amqp_frame_t
! 1364: *
! 1365: * Waits for the next amqp_frame_t frame to be read from the broker.
! 1366: * This function has the potential to block for a long time in the case of
! 1367: * waiting for a basic.deliver method frame from the broker.
! 1368: *
! 1369: * The library may buffer frames. When an amqp_connection_state_t object
! 1370: * has frames buffered calling amqp_simple_wait_frame() will return an
! 1371: * amqp_frame_t without entering a blocking read(). You can test to see if
! 1372: * an amqp_connection_state_t object has frames buffered by calling the
! 1373: * amqp_frames_enqueued() function.
! 1374: *
! 1375: * The library has a socket read buffer. When there is data in an
! 1376: * amqp_connection_state_t read buffer, amqp_simple_wait_frame() may return an
! 1377: * amqp_frame_t without entering a blocking read(). You can test to see if an
! 1378: * amqp_connection_state_t object has data in its read buffer by calling the
! 1379: * amqp_data_in_buffer() function.
! 1380: *
! 1381: * \param [in] state the connection object
! 1382: * \param [out] decoded_frame the frame
! 1383: * \return AMQP_STATUS_OK on success, an amqp_status_enum value
! 1384: * is returned otherwise. Possible errors include:
! 1385: * - AMQP_STATUS_NO_MEMORY failure in allocating memory. The library is likely
! 1386: * in an indeterminate state making recovery unlikely. Client should note the
! 1387: * error and terminate the application
! 1388: * - AMQP_STATUS_BAD_AMQP_DATA bad AMQP data was received. The connection
! 1389: * should be shutdown immediately
! 1390: * - AMQP_STATUS_UNKNOWN_METHOD: an unknown method was received from the
! 1391: * broker. This is likely a protocol error and the connection should be
! 1392: * shutdown immediately
! 1393: * - AMQP_STATUS_UNKNOWN_CLASS: a properties frame with an unknown class
! 1394: * was received from the broker. This is likely a protocol error and the
! 1395: * connection should be shutdown immediately
! 1396: * - AMQP_STATUS_HEARTBEAT_TIMEOUT timed out while waiting for heartbeat
! 1397: * from the broker. The connection has been closed.
! 1398: * - AMQP_STATUS_TIMER_FAILURE system timer indicated failure.
! 1399: * - AMQP_STATUS_SOCKET_ERROR a socket error occurred. The connection has
! 1400: * been closed
! 1401: * - AMQP_STATUS_SSL_ERROR a SSL socket error occurred. The connection has
! 1402: * been closed.
! 1403: *
! 1404: * \sa amqp_simple_wait_frame_noblock() amqp_frames_enqueued()
! 1405: * amqp_data_in_buffer()
! 1406: *
! 1407: * \note as of v0.4.0 this function will no longer return heartbeat frames
! 1408: * when enabled by specifying a non-zero heartbeat value in amqp_login().
! 1409: * Heartbeating is handled internally by the library.
! 1410: *
! 1411: * \since v0.1
! 1412: */
! 1413: AMQP_EXPORT
! 1414: int AMQP_CALL amqp_simple_wait_frame(amqp_connection_state_t state,
! 1415: amqp_frame_t *decoded_frame);
! 1416:
! 1417: /**
! 1418: * Read a single amqp_frame_t with a timeout.
! 1419: *
! 1420: * Waits for the next amqp_frame_t frame to be read from the broker, up to
! 1421: * a timespan specified by tv. The function will return AMQP_STATUS_TIMEOUT
! 1422: * if the timeout is reached. The tv value is not modified by the function.
! 1423: *
! 1424: * If a 0 timeval is specified, the function behaves as if its non-blocking: it
! 1425: * will test to see if a frame can be read from the broker, and return
! 1426: * immediately.
! 1427: *
! 1428: * If NULL is passed in for tv, the function will behave like
! 1429: * amqp_simple_wait_frame() and block until a frame is received from the broker
! 1430: *
! 1431: * The library may buffer frames. When an amqp_connection_state_t object
! 1432: * has frames buffered calling amqp_simple_wait_frame_noblock() will return an
! 1433: * amqp_frame_t without entering a blocking read(). You can test to see if an
! 1434: * amqp_connection_state_t object has frames buffered by calling the
! 1435: * amqp_frames_enqueued() function.
! 1436: *
! 1437: * The library has a socket read buffer. When there is data in an
! 1438: * amqp_connection_state_t read buffer, amqp_simple_wait_frame_noblock() may
! 1439: * return
! 1440: * an amqp_frame_t without entering a blocking read(). You can test to see if an
! 1441: * amqp_connection_state_t object has data in its read buffer by calling the
! 1442: * amqp_data_in_buffer() function.
! 1443: *
! 1444: * \note This function does not return heartbeat frames. When enabled,
! 1445: * heartbeating is handled internally by the library.
! 1446: *
! 1447: * \param [in,out] state the connection object
! 1448: * \param [out] decoded_frame the frame
! 1449: * \param [in] tv the maximum time to wait for a frame to be read. Setting
! 1450: * tv->tv_sec = 0 and tv->tv_usec = 0 will do a non-blocking read. Specifying
! 1451: * NULL for tv will make the function block until a frame is read.
! 1452: * \return AMQP_STATUS_OK on success. An amqp_status_enum value is returned
! 1453: * otherwise. Possible errors include:
! 1454: * - AMQP_STATUS_TIMEOUT the timeout was reached while waiting for a frame
! 1455: * from the broker.
! 1456: * - AMQP_STATUS_INVALID_PARAMETER the tv parameter contains an invalid value.
! 1457: * - AMQP_STATUS_NO_MEMORY failure in allocating memory. The library is likely
! 1458: * in an indeterminate state making recovery unlikely. Client should note the
! 1459: * error and terminate the application
! 1460: * - AMQP_STATUS_BAD_AMQP_DATA bad AMQP data was received. The connection
! 1461: * should be shutdown immediately
! 1462: * - AMQP_STATUS_UNKNOWN_METHOD: an unknown method was received from the
! 1463: * broker. This is likely a protocol error and the connection should be
! 1464: * shutdown immediately
! 1465: * - AMQP_STATUS_UNKNOWN_CLASS: a properties frame with an unknown class
! 1466: * was received from the broker. This is likely a protocol error and the
! 1467: * connection should be shutdown immediately
! 1468: * - AMQP_STATUS_HEARTBEAT_TIMEOUT timed out while waiting for heartbeat
! 1469: * from the broker. The connection has been closed.
! 1470: * - AMQP_STATUS_TIMER_FAILURE system timer indicated failure.
! 1471: * - AMQP_STATUS_SOCKET_ERROR a socket error occurred. The connection has
! 1472: * been closed
! 1473: * - AMQP_STATUS_SSL_ERROR a SSL socket error occurred. The connection has
! 1474: * been closed.
! 1475: *
! 1476: * \sa amqp_simple_wait_frame() amqp_frames_enqueued() amqp_data_in_buffer()
! 1477: *
! 1478: * \since v0.4.0
! 1479: */
! 1480: AMQP_EXPORT
! 1481: int AMQP_CALL amqp_simple_wait_frame_noblock(amqp_connection_state_t state,
! 1482: amqp_frame_t *decoded_frame,
! 1483: const struct timeval *tv);
! 1484:
! 1485: /**
! 1486: * Waits for a specific method from the broker
! 1487: *
! 1488: * \warning You probably don't want to use this function. If this function
! 1489: * doesn't receive exactly the frame requested it closes the whole connection.
! 1490: *
! 1491: * Waits for a single method on a channel from the broker.
! 1492: * If a frame is received that does not match expected_channel
! 1493: * or expected_method the program will abort
! 1494: *
! 1495: * \param [in] state the connection object
! 1496: * \param [in] expected_channel the channel that the method should be delivered
! 1497: * on
! 1498: * \param [in] expected_method the method to wait for
! 1499: * \param [out] output the method
! 1500: * \returns AMQP_STATUS_OK on success. An amqp_status_enum value is returned
! 1501: * otherwise. Possible errors include:
! 1502: * - AMQP_STATUS_WRONG_METHOD a frame containing the wrong method, wrong frame
! 1503: * type or wrong channel was received. The connection is closed.
! 1504: * - AMQP_STATUS_NO_MEMORY failure in allocating memory. The library is likely
! 1505: * in an indeterminate state making recovery unlikely. Client should note the
! 1506: * error and terminate the application
! 1507: * - AMQP_STATUS_BAD_AMQP_DATA bad AMQP data was received. The connection
! 1508: * should be shutdown immediately
! 1509: * - AMQP_STATUS_UNKNOWN_METHOD: an unknown method was received from the
! 1510: * broker. This is likely a protocol error and the connection should be
! 1511: * shutdown immediately
! 1512: * - AMQP_STATUS_UNKNOWN_CLASS: a properties frame with an unknown class
! 1513: * was received from the broker. This is likely a protocol error and the
! 1514: * connection should be shutdown immediately
! 1515: * - AMQP_STATUS_HEARTBEAT_TIMEOUT timed out while waiting for heartbeat
! 1516: * from the broker. The connection has been closed.
! 1517: * - AMQP_STATUS_TIMER_FAILURE system timer indicated failure.
! 1518: * - AMQP_STATUS_SOCKET_ERROR a socket error occurred. The connection has
! 1519: * been closed
! 1520: * - AMQP_STATUS_SSL_ERROR a SSL socket error occurred. The connection has
! 1521: * been closed.
! 1522: *
! 1523: * \since v0.1
! 1524: */
! 1525:
! 1526: AMQP_EXPORT
! 1527: int AMQP_CALL amqp_simple_wait_method(amqp_connection_state_t state,
! 1528: amqp_channel_t expected_channel,
! 1529: amqp_method_number_t expected_method,
! 1530: amqp_method_t *output);
! 1531:
! 1532: /**
! 1533: * Sends a method to the broker
! 1534: *
! 1535: * This is a thin wrapper around amqp_send_frame(), providing a way to send
! 1536: * a method to the broker on a specified channel.
! 1537: *
! 1538: * \param [in] state the connection object
! 1539: * \param [in] channel the channel object
! 1540: * \param [in] id the method number
! 1541: * \param [in] decoded the method object
! 1542: * \returns AMQP_STATUS_OK on success, an amqp_status_enum value otherwise.
! 1543: * Possible errors include:
! 1544: * - AMQP_STATUS_BAD_AMQP_DATA the serialized form of the method or
! 1545: * properties was too large to fit in a single AMQP frame, or the
! 1546: * method contains an invalid value. The frame was not sent.
! 1547: * - AMQP_STATUS_TABLE_TOO_BIG the serialized form of an amqp_table_t is
! 1548: * too large to fit in a single AMQP frame. Frame was not sent.
! 1549: * - AMQP_STATUS_UNKNOWN_METHOD an invalid method type was passed in
! 1550: * - AMQP_STATUS_UNKNOWN_CLASS an invalid properties type was passed in
! 1551: * - AMQP_STATUS_TIMER_FAILURE system timer indicated failure. The frame
! 1552: * was sent
! 1553: * - AMQP_STATUS_SOCKET_ERROR
! 1554: * - AMQP_STATUS_SSL_ERROR
! 1555: *
! 1556: * \since v0.1
! 1557: */
! 1558: AMQP_EXPORT
! 1559: int AMQP_CALL amqp_send_method(amqp_connection_state_t state,
! 1560: amqp_channel_t channel, amqp_method_number_t id,
! 1561: void *decoded);
! 1562:
! 1563: /**
! 1564: * Sends a method to the broker and waits for a method response
! 1565: *
! 1566: * \param [in] state the connection object
! 1567: * \param [in] channel the channel object
! 1568: * \param [in] request_id the method number of the request
! 1569: * \param [in] expected_reply_ids a 0 terminated array of expected response
! 1570: * method numbers
! 1571: * \param [in] decoded_request_method the method to be sent to the broker
! 1572: * \return a amqp_rpc_reply_t:
! 1573: * - r.reply_type == AMQP_RESPONSE_NORMAL. RPC completed successfully
! 1574: * - r.reply_type == AMQP_RESPONSE_SERVER_EXCEPTION. The broker returned an
! 1575: * exception:
! 1576: * - If r.reply.id == AMQP_CHANNEL_CLOSE_METHOD a channel exception
! 1577: * occurred, cast r.reply.decoded to amqp_channel_close_t* to see details
! 1578: * of the exception. The client should amqp_send_method() a
! 1579: * amqp_channel_close_ok_t. The channel must be re-opened before it
! 1580: * can be used again. Any resources associated with the channel
! 1581: * (auto-delete exchanges, auto-delete queues, consumers) are invalid
! 1582: * and must be recreated before attempting to use them again.
! 1583: * - If r.reply.id == AMQP_CONNECTION_CLOSE_METHOD a connection exception
! 1584: * occurred, cast r.reply.decoded to amqp_connection_close_t* to see
! 1585: * details of the exception. The client amqp_send_method() a
! 1586: * amqp_connection_close_ok_t and disconnect from the broker.
! 1587: * - r.reply_type == AMQP_RESPONSE_LIBRARY_EXCEPTION. An exception occurred
! 1588: * within the library. Examine r.library_error and compare it against
! 1589: * amqp_status_enum values to determine the error.
! 1590: *
! 1591: * \sa amqp_simple_rpc_decoded()
! 1592: *
! 1593: * \since v0.1
! 1594: */
! 1595: AMQP_EXPORT
! 1596: amqp_rpc_reply_t AMQP_CALL amqp_simple_rpc(
! 1597: amqp_connection_state_t state, amqp_channel_t channel,
! 1598: amqp_method_number_t request_id, amqp_method_number_t *expected_reply_ids,
! 1599: void *decoded_request_method);
! 1600:
! 1601: /**
! 1602: * Sends a method to the broker and waits for a method response
! 1603: *
! 1604: * \param [in] state the connection object
! 1605: * \param [in] channel the channel object
! 1606: * \param [in] request_id the method number of the request
! 1607: * \param [in] reply_id the method number expected in response
! 1608: * \param [in] decoded_request_method the request method
! 1609: * \return a pointer to the method returned from the broker, or NULL on error.
! 1610: * On error amqp_get_rpc_reply() will return an amqp_rpc_reply_t with
! 1611: * details on the error that occurred.
! 1612: *
! 1613: * \since v0.1
! 1614: */
! 1615: AMQP_EXPORT
! 1616: void *AMQP_CALL amqp_simple_rpc_decoded(amqp_connection_state_t state,
! 1617: amqp_channel_t channel,
! 1618: amqp_method_number_t request_id,
! 1619: amqp_method_number_t reply_id,
! 1620: void *decoded_request_method);
! 1621:
! 1622: /**
! 1623: * Get the last global amqp_rpc_reply
! 1624: *
! 1625: * The API methods corresponding to most synchronous AMQP methods
! 1626: * return a pointer to the decoded method result. Upon error, they
! 1627: * return NULL, and we need some way of discovering what, if anything,
! 1628: * went wrong. amqp_get_rpc_reply() returns the most recent
! 1629: * amqp_rpc_reply_t instance corresponding to such an API operation
! 1630: * for the given connection.
! 1631: *
! 1632: * Only use it for operations that do not themselves return
! 1633: * amqp_rpc_reply_t; operations that do return amqp_rpc_reply_t
! 1634: * generally do NOT update this per-connection-global amqp_rpc_reply_t
! 1635: * instance.
! 1636: *
! 1637: * \param [in] state the connection object
! 1638: * \return the most recent amqp_rpc_reply_t:
! 1639: * - r.reply_type == AMQP_RESPONSE_NORMAL. RPC completed successfully
! 1640: * - r.reply_type == AMQP_RESPONSE_SERVER_EXCEPTION. The broker returned an
! 1641: * exception:
! 1642: * - If r.reply.id == AMQP_CHANNEL_CLOSE_METHOD a channel exception
! 1643: * occurred, cast r.reply.decoded to amqp_channel_close_t* to see details
! 1644: * of the exception. The client should amqp_send_method() a
! 1645: * amqp_channel_close_ok_t. The channel must be re-opened before it
! 1646: * can be used again. Any resources associated with the channel
! 1647: * (auto-delete exchanges, auto-delete queues, consumers) are invalid
! 1648: * and must be recreated before attempting to use them again.
! 1649: * - If r.reply.id == AMQP_CONNECTION_CLOSE_METHOD a connection exception
! 1650: * occurred, cast r.reply.decoded to amqp_connection_close_t* to see
! 1651: * details of the exception. The client amqp_send_method() a
! 1652: * amqp_connection_close_ok_t and disconnect from the broker.
! 1653: * - r.reply_type == AMQP_RESPONSE_LIBRARY_EXCEPTION. An exception occurred
! 1654: * within the library. Examine r.library_error and compare it against
! 1655: * amqp_status_enum values to determine the error.
! 1656: *
! 1657: * \sa amqp_simple_rpc_decoded()
! 1658: *
! 1659: * \since v0.1
! 1660: */
! 1661: AMQP_EXPORT
! 1662: amqp_rpc_reply_t AMQP_CALL amqp_get_rpc_reply(amqp_connection_state_t state);
! 1663:
! 1664: /**
! 1665: * Login to the broker
! 1666: *
! 1667: * After using amqp_open_socket and amqp_set_sockfd, call
! 1668: * amqp_login to complete connecting to the broker
! 1669: *
! 1670: * \param [in] state the connection object
! 1671: * \param [in] vhost the virtual host to connect to on the broker. The default
! 1672: * on most brokers is "/"
! 1673: * \param [in] channel_max the limit for number of channels for the connection.
! 1674: * 0 means no limit, and is a good default
! 1675: * (AMQP_DEFAULT_MAX_CHANNELS)
! 1676: * Note that the maximum number of channels the protocol supports
! 1677: * is 65535 (2^16, with the 0-channel reserved). The server can
! 1678: * set a lower channel_max and then the client will use the lowest
! 1679: * of the two
! 1680: * \param [in] frame_max the maximum size of an AMQP frame on the wire to
! 1681: * request of the broker for this connection. 4096 is the minimum
! 1682: * size, 2^31-1 is the maximum, a good default is 131072 (128KB),
! 1683: * or AMQP_DEFAULT_FRAME_SIZE
! 1684: * \param [in] heartbeat the number of seconds between heartbeat frames to
! 1685: * request of the broker. A value of 0 disables heartbeats.
! 1686: * Note rabbitmq-c only has partial support for heartbeats, as of
! 1687: * v0.4.0 they are only serviced during amqp_basic_publish() and
! 1688: * amqp_simple_wait_frame()/amqp_simple_wait_frame_noblock()
! 1689: * \param [in] sasl_method the SASL method to authenticate with the broker.
! 1690: * followed by the authentication information. The following SASL
! 1691: * methods are implemented:
! 1692: * - AMQP_SASL_METHOD_PLAIN, the AMQP_SASL_METHOD_PLAIN argument
! 1693: * should be followed by two arguments in this order:
! 1694: * const char* username, and const char* password.
! 1695: * - AMQP_SASL_METHOD_EXTERNAL, the AMQP_SASL_METHOD_EXTERNAL
! 1696: * argument should be followed one argument:
! 1697: * const char* identity.
! 1698: * \return amqp_rpc_reply_t indicating success or failure.
! 1699: * - r.reply_type == AMQP_RESPONSE_NORMAL. Login completed successfully
! 1700: * - r.reply_type == AMQP_RESPONSE_LIBRARY_EXCEPTION. In most cases errors
! 1701: * from the broker when logging in will be represented by the broker closing
! 1702: * the socket. In this case r.library_error will be set to
! 1703: * AMQP_STATUS_CONNECTION_CLOSED. This error can represent a number of
! 1704: * error conditions including: invalid vhost, authentication failure.
! 1705: * - r.reply_type == AMQP_RESPONSE_SERVER_EXCEPTION. The broker returned an
! 1706: * exception:
! 1707: * - If r.reply.id == AMQP_CHANNEL_CLOSE_METHOD a channel exception
! 1708: * occurred, cast r.reply.decoded to amqp_channel_close_t* to see details
! 1709: * of the exception. The client should amqp_send_method() a
! 1710: * amqp_channel_close_ok_t. The channel must be re-opened before it
! 1711: * can be used again. Any resources associated with the channel
! 1712: * (auto-delete exchanges, auto-delete queues, consumers) are invalid
! 1713: * and must be recreated before attempting to use them again.
! 1714: * - If r.reply.id == AMQP_CONNECTION_CLOSE_METHOD a connection exception
! 1715: * occurred, cast r.reply.decoded to amqp_connection_close_t* to see
! 1716: * details of the exception. The client amqp_send_method() a
! 1717: * amqp_connection_close_ok_t and disconnect from the broker.
! 1718: *
! 1719: * \since v0.1
! 1720: */
! 1721: AMQP_EXPORT
! 1722: amqp_rpc_reply_t AMQP_CALL amqp_login(amqp_connection_state_t state,
! 1723: char const *vhost, int channel_max,
! 1724: int frame_max, int heartbeat,
! 1725: amqp_sasl_method_enum sasl_method, ...);
! 1726:
! 1727: /**
! 1728: * Login to the broker passing a properties table
! 1729: *
! 1730: * This function is similar to amqp_login() and differs in that it provides a
! 1731: * way to pass client properties to the broker. This is commonly used to
! 1732: * negotiate newer protocol features as they are supported by the broker.
! 1733: *
! 1734: * \param [in] state the connection object
! 1735: * \param [in] vhost the virtual host to connect to on the broker. The default
! 1736: * on most brokers is "/"
! 1737: * \param [in] channel_max the limit for the number of channels for the
! 1738: * connection.
! 1739: * 0 means no limit, and is a good default
! 1740: * (AMQP_DEFAULT_MAX_CHANNELS)
! 1741: * Note that the maximum number of channels the protocol supports
! 1742: * is 65535 (2^16, with the 0-channel reserved). The server can
! 1743: * set a lower channel_max and then the client will use the lowest
! 1744: * of the two
! 1745: * \param [in] frame_max the maximum size of an AMQP frame ont he wire to
! 1746: * request of the broker for this connection. 4096 is the minimum
! 1747: * size, 2^31-1 is the maximum, a good default is 131072 (128KB),
! 1748: * or AMQP_DEFAULT_FRAME_SIZE
! 1749: * \param [in] heartbeat the number of seconds between heartbeat frame to
! 1750: * request of the broker. A value of 0 disables heartbeats.
! 1751: * Note rabbitmq-c only has partial support for hearts, as of
! 1752: * v0.4.0 heartbeats are only serviced during amqp_basic_publish(),
! 1753: * and amqp_simple_wait_frame()/amqp_simple_wait_frame_noblock()
! 1754: * \param [in] properties a table of properties to send the broker.
! 1755: * \param [in] sasl_method the SASL method to authenticate with the broker
! 1756: * followed by the authentication information. The following SASL
! 1757: * methods are implemented:
! 1758: * - AMQP_SASL_METHOD_PLAIN, the AMQP_SASL_METHOD_PLAIN argument
! 1759: * should be followed by two arguments in this order:
! 1760: * const char* username, and const char* password.
! 1761: * - AMQP_SASL_METHOD_EXTERNAL, the AMQP_SASL_METHOD_EXTERNAL
! 1762: * argument should be followed one argument:
! 1763: * const char* identity.
! 1764: * \return amqp_rpc_reply_t indicating success or failure.
! 1765: * - r.reply_type == AMQP_RESPONSE_NORMAL. Login completed successfully
! 1766: * - r.reply_type == AMQP_RESPONSE_LIBRARY_EXCEPTION. In most cases errors
! 1767: * from the broker when logging in will be represented by the broker closing
! 1768: * the socket. In this case r.library_error will be set to
! 1769: * AMQP_STATUS_CONNECTION_CLOSED. This error can represent a number of
! 1770: * error conditions including: invalid vhost, authentication failure.
! 1771: * - r.reply_type == AMQP_RESPONSE_SERVER_EXCEPTION. The broker returned an
! 1772: * exception:
! 1773: * - If r.reply.id == AMQP_CHANNEL_CLOSE_METHOD a channel exception
! 1774: * occurred, cast r.reply.decoded to amqp_channel_close_t* to see details
! 1775: * of the exception. The client should amqp_send_method() a
! 1776: * amqp_channel_close_ok_t. The channel must be re-opened before it
! 1777: * can be used again. Any resources associated with the channel
! 1778: * (auto-delete exchanges, auto-delete queues, consumers) are invalid
! 1779: * and must be recreated before attempting to use them again.
! 1780: * - If r.reply.id == AMQP_CONNECTION_CLOSE_METHOD a connection exception
! 1781: * occurred, cast r.reply.decoded to amqp_connection_close_t* to see
! 1782: * details of the exception. The client amqp_send_method() a
! 1783: * amqp_connection_close_ok_t and disconnect from the broker.
! 1784: *
! 1785: * \since v0.4.0
! 1786: */
! 1787: AMQP_EXPORT
! 1788: amqp_rpc_reply_t AMQP_CALL amqp_login_with_properties(
! 1789: amqp_connection_state_t state, char const *vhost, int channel_max,
! 1790: int frame_max, int heartbeat, const amqp_table_t *properties,
! 1791: amqp_sasl_method_enum sasl_method, ...);
! 1792:
! 1793: struct amqp_basic_properties_t_;
! 1794:
! 1795: /**
! 1796: * Publish a message to the broker
! 1797: *
! 1798: * Publish a message on an exchange with a routing key.
! 1799: *
! 1800: * Note that at the AMQ protocol level basic.publish is an async method:
! 1801: * this means error conditions that occur on the broker (such as publishing to
! 1802: * a non-existent exchange) will not be reflected in the return value of this
! 1803: * function.
! 1804: *
! 1805: * \param [in] state the connection object
! 1806: * \param [in] channel the channel identifier
! 1807: * \param [in] exchange the exchange on the broker to publish to
! 1808: * \param [in] routing_key the routing key to use when publishing the message
! 1809: * \param [in] mandatory indicate to the broker that the message MUST be routed
! 1810: * to a queue. If the broker cannot do this it should respond with
! 1811: * a basic.return method.
! 1812: * \param [in] immediate indicate to the broker that the message MUST be
! 1813: * delivered to a consumer immediately. If the broker cannot do this
! 1814: * it should respond with a basic.return method.
! 1815: * \param [in] properties the properties associated with the message
! 1816: * \param [in] body the message body
! 1817: * \return AMQP_STATUS_OK on success, amqp_status_enum value on failure. Note
! 1818: * that basic.publish is an async method, the return value from this
! 1819: * function only indicates that the message data was successfully
! 1820: * transmitted to the broker. It does not indicate failures that occur
! 1821: * on the broker, such as publishing to a non-existent exchange.
! 1822: * Possible error values:
! 1823: * - AMQP_STATUS_TIMER_FAILURE: system timer facility returned an error
! 1824: * the message was not sent.
! 1825: * - AMQP_STATUS_HEARTBEAT_TIMEOUT: connection timed out waiting for a
! 1826: * heartbeat from the broker. The message was not sent.
! 1827: * - AMQP_STATUS_NO_MEMORY: memory allocation failed. The message was
! 1828: * not sent.
! 1829: * - AMQP_STATUS_TABLE_TOO_BIG: a table in the properties was too large
! 1830: * to fit in a single frame. Message was not sent.
! 1831: * - AMQP_STATUS_CONNECTION_CLOSED: the connection was closed.
! 1832: * - AMQP_STATUS_SSL_ERROR: a SSL error occurred.
! 1833: * - AMQP_STATUS_TCP_ERROR: a TCP error occurred. errno or
! 1834: * WSAGetLastError() may provide more information
! 1835: *
! 1836: * Note: this function does heartbeat processing as of v0.4.0
! 1837: *
! 1838: * \since v0.1
! 1839: */
! 1840: AMQP_EXPORT
! 1841: int AMQP_CALL amqp_basic_publish(
! 1842: amqp_connection_state_t state, amqp_channel_t channel,
! 1843: amqp_bytes_t exchange, amqp_bytes_t routing_key, amqp_boolean_t mandatory,
! 1844: amqp_boolean_t immediate, struct amqp_basic_properties_t_ const *properties,
! 1845: amqp_bytes_t body);
! 1846:
! 1847: /**
! 1848: * Closes an channel
! 1849: *
! 1850: * \param [in] state the connection object
! 1851: * \param [in] channel the channel identifier
! 1852: * \param [in] code the reason for closing the channel, AMQP_REPLY_SUCCESS is a
! 1853: * good default
! 1854: * \return amqp_rpc_reply_t indicating success or failure
! 1855: *
! 1856: * \since v0.1
! 1857: */
! 1858: AMQP_EXPORT
! 1859: amqp_rpc_reply_t AMQP_CALL amqp_channel_close(amqp_connection_state_t state,
! 1860: amqp_channel_t channel, int code);
! 1861:
! 1862: /**
! 1863: * Closes the entire connection
! 1864: *
! 1865: * Implicitly closes all channels and informs the broker the connection
! 1866: * is being closed, after receiving acknowledgment from the broker it closes
! 1867: * the socket.
! 1868: *
! 1869: * \param [in] state the connection object
! 1870: * \param [in] code the reason code for closing the connection.
! 1871: * AMQP_REPLY_SUCCESS is a good default.
! 1872: * \return amqp_rpc_reply_t indicating the result
! 1873: *
! 1874: * \since v0.1
! 1875: */
! 1876: AMQP_EXPORT
! 1877: amqp_rpc_reply_t AMQP_CALL amqp_connection_close(amqp_connection_state_t state,
! 1878: int code);
! 1879:
! 1880: /**
! 1881: * Acknowledges a message
! 1882: *
! 1883: * Does a basic.ack on a received message
! 1884: *
! 1885: * \param [in] state the connection object
! 1886: * \param [in] channel the channel identifier
! 1887: * \param [in] delivery_tag the delivery tag of the message to be ack'd
! 1888: * \param [in] multiple if true, ack all messages up to this delivery tag, if
! 1889: * false ack only this delivery tag
! 1890: * \return 0 on success, 0 > on failing to send the ack to the broker.
! 1891: * this will not indicate failure if something goes wrong on the
! 1892: * broker
! 1893: *
! 1894: * \since v0.1
! 1895: */
! 1896: AMQP_EXPORT
! 1897: int AMQP_CALL amqp_basic_ack(amqp_connection_state_t state,
! 1898: amqp_channel_t channel, uint64_t delivery_tag,
! 1899: amqp_boolean_t multiple);
! 1900:
! 1901: /**
! 1902: * Do a basic.get
! 1903: *
! 1904: * Synchonously polls the broker for a message in a queue, and
! 1905: * retrieves the message if a message is in the queue.
! 1906: *
! 1907: * \param [in] state the connection object
! 1908: * \param [in] channel the channel identifier to use
! 1909: * \param [in] queue the queue name to retrieve from
! 1910: * \param [in] no_ack if true the message is automatically ack'ed
! 1911: * if false amqp_basic_ack should be called once the message
! 1912: * retrieved has been processed
! 1913: * \return amqp_rpc_reply indicating success or failure
! 1914: *
! 1915: * \since v0.1
! 1916: */
! 1917: AMQP_EXPORT
! 1918: amqp_rpc_reply_t AMQP_CALL amqp_basic_get(amqp_connection_state_t state,
! 1919: amqp_channel_t channel,
! 1920: amqp_bytes_t queue,
! 1921: amqp_boolean_t no_ack);
! 1922:
! 1923: /**
! 1924: * Do a basic.reject
! 1925: *
! 1926: * Actively reject a message that has been delivered
! 1927: *
! 1928: * \param [in] state the connection object
! 1929: * \param [in] channel the channel identifier
! 1930: * \param [in] delivery_tag the delivery tag of the message to reject
! 1931: * \param [in] requeue indicate to the broker whether it should requeue the
! 1932: * message or just discard it.
! 1933: * \return 0 on success, 0 > on failing to send the reject method to the broker.
! 1934: * This will not indicate failure if something goes wrong on the
! 1935: * broker.
! 1936: *
! 1937: * \since v0.1
! 1938: */
! 1939: AMQP_EXPORT
! 1940: int AMQP_CALL amqp_basic_reject(amqp_connection_state_t state,
! 1941: amqp_channel_t channel, uint64_t delivery_tag,
! 1942: amqp_boolean_t requeue);
! 1943:
! 1944: /**
! 1945: * Do a basic.nack
! 1946: *
! 1947: * Actively reject a message, this has the same effect as amqp_basic_reject()
! 1948: * however, amqp_basic_nack() can negatively acknowledge multiple messages with
! 1949: * one call much like amqp_basic_ack() can acknowledge mutliple messages with
! 1950: * one call.
! 1951: *
! 1952: * \param [in] state the connection object
! 1953: * \param [in] channel the channel identifier
! 1954: * \param [in] delivery_tag the delivery tag of the message to reject
! 1955: * \param [in] multiple if set to 1 negatively acknowledge all unacknowledged
! 1956: * messages on this channel.
! 1957: * \param [in] requeue indicate to the broker whether it should requeue the
! 1958: * message or dead-letter it.
! 1959: * \return AMQP_STATUS_OK on success, an amqp_status_enum value otherwise.
! 1960: *
! 1961: * \since v0.5.0
! 1962: */
! 1963: AMQP_EXPORT
! 1964: int AMQP_CALL amqp_basic_nack(amqp_connection_state_t state,
! 1965: amqp_channel_t channel, uint64_t delivery_tag,
! 1966: amqp_boolean_t multiple, amqp_boolean_t requeue);
! 1967: /**
! 1968: * Check to see if there is data left in the receive buffer
! 1969: *
! 1970: * Can be used to see if there is data still in the buffer, if so
! 1971: * calling amqp_simple_wait_frame will not immediately enter a
! 1972: * blocking read.
! 1973: *
! 1974: * \param [in] state the connection object
! 1975: * \return true if there is data in the recieve buffer, false otherwise
! 1976: *
! 1977: * \since v0.1
! 1978: */
! 1979: AMQP_EXPORT
! 1980: amqp_boolean_t AMQP_CALL amqp_data_in_buffer(amqp_connection_state_t state);
! 1981:
! 1982: /**
! 1983: * Get the error string for the given error code.
! 1984: *
! 1985: * \deprecated This function has been deprecated in favor of
! 1986: * \ref amqp_error_string2() which returns statically allocated
! 1987: * string which do not need to be freed by the caller.
! 1988: *
! 1989: * The returned string resides on the heap; the caller is responsible
! 1990: * for freeing it.
! 1991: *
! 1992: * \param [in] err return error code
! 1993: * \return the error string
! 1994: *
! 1995: * \since v0.1
! 1996: */
! 1997: AMQP_DEPRECATED_EXPORT char *AMQP_CALL amqp_error_string(int err);
! 1998:
! 1999: /**
! 2000: * Get the error string for the given error code.
! 2001: *
! 2002: * Get an error string associated with an error code. The string is statically
! 2003: * allocated and does not need to be freed
! 2004: *
! 2005: * \param [in] err the error code
! 2006: * \return the error string
! 2007: *
! 2008: * \since v0.4.0
! 2009: */
! 2010: AMQP_EXPORT
! 2011: const char *AMQP_CALL amqp_error_string2(int err);
! 2012:
! 2013: /**
! 2014: * Deserialize an amqp_table_t from AMQP wireformat
! 2015: *
! 2016: * This is an internal function and is not typically used by
! 2017: * client applications
! 2018: *
! 2019: * \warning The decoded table entries contain direct references (pointers) into
! 2020: * the \p encoded buffer rather than independent copies. The \p encoded buffer
! 2021: * **must** remain valid and unmodified for as long as the decoded table (or
! 2022: * any data derived from it) is in use. Freeing or modifying \p encoded while
! 2023: * the table is still live will result in use-after-free. Use
! 2024: * amqp_table_clone() if you need a fully independent copy of the table.
! 2025: *
! 2026: * \param [in] encoded the buffer containing the serialized data. Must outlive
! 2027: * the decoded \p output table.
! 2028: * \param [in] pool memory pool used to allocate the table entries from
! 2029: * \param [in] output the amqp_table_t structure to fill in. Any existing
! 2030: * entries will be erased
! 2031: * \param [in,out] offset The offset into the encoded buffer to start
! 2032: * reading the serialized table. It will be updated
! 2033: * by this function to end of the table
! 2034: * \return AMQP_STATUS_OK on success, an amqp_status_enum value on failure
! 2035: * Possible error codes:
! 2036: * - AMQP_STATUS_NO_MEMORY out of memory
! 2037: * - AMQP_STATUS_BAD_AMQP_DATA invalid wireformat
! 2038: *
! 2039: * \since v0.1
! 2040: */
! 2041: AMQP_EXPORT
! 2042: int AMQP_CALL amqp_decode_table(amqp_bytes_t encoded, amqp_pool_t *pool,
! 2043: amqp_table_t *output, size_t *offset);
! 2044:
! 2045: /**
! 2046: * Serializes an amqp_table_t to the AMQP wireformat
! 2047: *
! 2048: * This is an internal function and is not typically used by
! 2049: * client applications
! 2050: *
! 2051: * \param [in] encoded the buffer where to serialize the table to
! 2052: * \param [in] input the amqp_table_t to serialize
! 2053: * \param [in,out] offset The offset into the encoded buffer to start
! 2054: * writing the serialized table. It will be updated
! 2055: * by this function to where writing left off
! 2056: * \return AMQP_STATUS_OK on success, an amqp_status_enum value on failure
! 2057: * Possible error codes:
! 2058: * - AMQP_STATUS_TABLE_TOO_BIG the serialized form is too large for the
! 2059: * buffer
! 2060: * - AMQP_STATUS_BAD_AMQP_DATA invalid table
! 2061: *
! 2062: * \since v0.1
! 2063: */
! 2064: AMQP_EXPORT
! 2065: int AMQP_CALL amqp_encode_table(amqp_bytes_t encoded, amqp_table_t *input,
! 2066: size_t *offset);
! 2067:
! 2068: /**
! 2069: * Create a deep-copy of an amqp_table_t object
! 2070: *
! 2071: * Creates a deep-copy of an amqp_table_t object, using the provided pool
! 2072: * object to allocate the necessary memory. This memory can be freed later by
! 2073: * call recycle_amqp_pool(), or empty_amqp_pool()
! 2074: *
! 2075: * \param [in] original the table to copy
! 2076: * \param [in,out] clone the table to copy to
! 2077: * \param [in] pool the initialized memory pool to do allocations for the table
! 2078: * from
! 2079: * \return AMQP_STATUS_OK on success, amqp_status_enum value on failure.
! 2080: * Possible error values:
! 2081: * - AMQP_STATUS_NO_MEMORY - memory allocation failure.
! 2082: * - AMQP_STATUS_INVALID_PARAMETER - invalid table (e.g., no key name)
! 2083: *
! 2084: * \since v0.4.0
! 2085: */
! 2086: AMQP_EXPORT
! 2087: int AMQP_CALL amqp_table_clone(const amqp_table_t *original,
! 2088: amqp_table_t *clone, amqp_pool_t *pool);
! 2089:
! 2090: /**
! 2091: * A message object
! 2092: *
! 2093: * \since v0.4.0
! 2094: */
! 2095: typedef struct amqp_message_t_ {
! 2096: amqp_basic_properties_t properties; /**< message properties */
! 2097: amqp_bytes_t body; /**< message body */
! 2098: amqp_pool_t pool; /**< pool used to allocate properties */
! 2099: } amqp_message_t;
! 2100:
! 2101: /**
! 2102: * Reads the next message on a channel
! 2103: *
! 2104: * Reads a complete message (header + body) on a specified channel. This
! 2105: * function is intended to be used with amqp_basic_get() or when an
! 2106: * AMQP_BASIC_DELIVERY_METHOD method is received.
! 2107: *
! 2108: * \param [in,out] state the connection object
! 2109: * \param [in] channel the channel on which to read the message from
! 2110: * \param [in,out] message a pointer to a amqp_message_t object. Caller should
! 2111: * call amqp_message_destroy() when it is done using the
! 2112: * fields in the message object. The caller is responsible for
! 2113: * allocating/destroying the amqp_message_t object itself.
! 2114: * \param [in] flags pass in 0. Currently unused.
! 2115: * \returns a amqp_rpc_reply_t object. ret.reply_type == AMQP_RESPONSE_NORMAL on
! 2116: * success.
! 2117: *
! 2118: * \since v0.4.0
! 2119: */
! 2120: AMQP_EXPORT
! 2121: amqp_rpc_reply_t AMQP_CALL amqp_read_message(amqp_connection_state_t state,
! 2122: amqp_channel_t channel,
! 2123: amqp_message_t *message,
! 2124: int flags);
! 2125:
! 2126: /**
! 2127: * Frees memory associated with a amqp_message_t allocated in amqp_read_message
! 2128: *
! 2129: * \param [in] message
! 2130: *
! 2131: * \since v0.4.0
! 2132: */
! 2133: AMQP_EXPORT
! 2134: void AMQP_CALL amqp_destroy_message(amqp_message_t *message);
! 2135:
! 2136: /**
! 2137: * Envelope object
! 2138: *
! 2139: * \since v0.4.0
! 2140: */
! 2141: typedef struct amqp_envelope_t_ {
! 2142: amqp_channel_t channel; /**< channel message was delivered on */
! 2143: amqp_bytes_t consumer_tag; /**< the consumer tag the message was delivered to
! 2144: */
! 2145: uint64_t delivery_tag; /**< the messages delivery tag */
! 2146: amqp_boolean_t redelivered; /**< flag indicating whether this message is being
! 2147: redelivered */
! 2148: amqp_bytes_t exchange; /**< exchange this message was published to */
! 2149: amqp_bytes_t routing_key; /**< the routing key this message was published with
! 2150: */
! 2151: amqp_message_t message; /**< the message */
! 2152: } amqp_envelope_t;
! 2153:
! 2154: /**
! 2155: * Wait for and consume a message
! 2156: *
! 2157: * Waits for a basic.deliver method on any channel, upon receipt of
! 2158: * basic.deliver it reads that message, and returns. If any other method is
! 2159: * received before basic.deliver, this function will return an amqp_rpc_reply_t
! 2160: * with ret.reply_type == AMQP_RESPONSE_LIBRARY_EXCEPTION, and
! 2161: * ret.library_error == AMQP_STATUS_UNEXPECTED_STATE. The caller should then
! 2162: * call amqp_simple_wait_frame() to read this frame and take appropriate action.
! 2163: *
! 2164: * This function should be used after starting a consumer with the
! 2165: * amqp_basic_consume() function
! 2166: *
! 2167: * \param [in,out] state the connection object
! 2168: * \param [in,out] envelope a pointer to a amqp_envelope_t object. Caller
! 2169: * should call #amqp_destroy_envelope() when it is done using
! 2170: * the fields in the envelope object. The caller is responsible
! 2171: * for allocating/destroying the amqp_envelope_t object itself.
! 2172: * \param [in] timeout a timeout to wait for a message delivery. Passing in
! 2173: * NULL will result in blocking behavior.
! 2174: * \param [in] flags pass in 0. Currently unused.
! 2175: * \returns a amqp_rpc_reply_t object. ret.reply_type == AMQP_RESPONSE_NORMAL
! 2176: * on success. If ret.reply_type == AMQP_RESPONSE_LIBRARY_EXCEPTION,
! 2177: * and ret.library_error == AMQP_STATUS_UNEXPECTED_STATE, a frame other
! 2178: * than AMQP_BASIC_DELIVER_METHOD was received, the caller should call
! 2179: * amqp_simple_wait_frame() to read this frame and take appropriate
! 2180: * action.
! 2181: *
! 2182: * \since v0.4.0
! 2183: */
! 2184: AMQP_EXPORT
! 2185: amqp_rpc_reply_t AMQP_CALL amqp_consume_message(amqp_connection_state_t state,
! 2186: amqp_envelope_t *envelope,
! 2187: const struct timeval *timeout,
! 2188: int flags);
! 2189:
! 2190: /**
! 2191: * Frees memory associated with a amqp_envelope_t allocated in
! 2192: * amqp_consume_message()
! 2193: *
! 2194: * \param [in] envelope
! 2195: *
! 2196: * \since v0.4.0
! 2197: */
! 2198: AMQP_EXPORT
! 2199: void AMQP_CALL amqp_destroy_envelope(amqp_envelope_t *envelope);
! 2200:
! 2201: /**
! 2202: * Parameters used to connect to the RabbitMQ broker
! 2203: *
! 2204: * \since v0.2
! 2205: */
! 2206: struct amqp_connection_info {
! 2207: char *user; /**< the username to authenticate with the broker, default on most
! 2208: broker is 'guest' */
! 2209: char *password; /**< the password to authenticate with the broker, default on
! 2210: most brokers is 'guest' */
! 2211: char *host; /**< the hostname of the broker */
! 2212: char *vhost; /**< the virtual host on the broker to connect to, a good default
! 2213: is "/" */
! 2214: int port; /**< the port that the broker is listening on, default on most
! 2215: brokers is 5672 */
! 2216: amqp_boolean_t ssl;
! 2217: };
! 2218:
! 2219: /**
! 2220: * Initialze an amqp_connection_info to default values
! 2221: *
! 2222: * The default values are:
! 2223: * - user: "guest"
! 2224: * - password: "guest"
! 2225: * - host: "localhost"
! 2226: * - vhost: "/"
! 2227: * - port: 5672
! 2228: *
! 2229: * \param [out] parsed the connection info to set defaults on
! 2230: *
! 2231: * \since v0.2
! 2232: */
! 2233: AMQP_EXPORT
! 2234: void AMQP_CALL
! 2235: amqp_default_connection_info(struct amqp_connection_info *parsed);
! 2236:
! 2237: /**
! 2238: * Parse a connection URL
! 2239: *
! 2240: * An amqp connection url takes the form:
! 2241: *
! 2242: * amqp://[$USERNAME[:$PASSWORD]\@]$HOST[:$PORT]/[$VHOST]
! 2243: *
! 2244: * Examples:
! 2245: * amqp://guest:guest\@localhost:5672//
! 2246: * amqp://guest:guest\@localhost/myvhost
! 2247: *
! 2248: * Any missing parts of the URL will be set to the defaults specified in
! 2249: * amqp_default_connection_info. For amqps: URLs the default port will be set
! 2250: * to 5671 instead of 5672 for non-SSL URLs.
! 2251: *
! 2252: * \note This function modifies url parameter.
! 2253: *
! 2254: * \param [in] url URI to parse, note that this parameter is modified by the
! 2255: * function.
! 2256: * \param [out] parsed the connection info gleaned from the URI. The char*
! 2257: * members will point to parts of the url input parameter.
! 2258: * Memory management will depend on how the url is allocated.
! 2259: * \returns AMQP_STATUS_OK on success, AMQP_STATUS_BAD_URL on failure
! 2260: *
! 2261: * \since v0.2
! 2262: */
! 2263: AMQP_EXPORT
! 2264: int AMQP_CALL amqp_parse_url(char *url, struct amqp_connection_info *parsed);
! 2265:
! 2266: /* socket API */
! 2267:
! 2268: /**
! 2269: * Open a socket connection.
! 2270: *
! 2271: * This function opens a socket connection returned from amqp_tcp_socket_new()
! 2272: * or amqp_ssl_socket_new(). This function should be called after setting
! 2273: * socket options and prior to assigning the socket to an AMQP connection with
! 2274: * amqp_set_socket().
! 2275: *
! 2276: * \param [in,out] self A socket object.
! 2277: * \param [in] host Connect to this host.
! 2278: * \param [in] port Connect on this remote port.
! 2279: *
! 2280: * \return AMQP_STATUS_OK on success, an amqp_status_enum on failure
! 2281: *
! 2282: * \since v0.4.0
! 2283: */
! 2284: AMQP_EXPORT
! 2285: int AMQP_CALL amqp_socket_open(amqp_socket_t *self, const char *host, int port);
! 2286:
! 2287: /**
! 2288: * Open a socket connection.
! 2289: *
! 2290: * This function opens a socket connection returned from amqp_tcp_socket_new()
! 2291: * or amqp_ssl_socket_new(). This function should be called after setting
! 2292: * socket options and prior to assigning the socket to an AMQP connection with
! 2293: * amqp_set_socket().
! 2294: *
! 2295: * \param [in,out] self A socket object.
! 2296: * \param [in] host Connect to this host.
! 2297: * \param [in] port Connect on this remote port.
! 2298: * \param [in] timeout Max allowed time to spent on opening. If NULL - run in
! 2299: * blocking mode
! 2300: *
! 2301: * \return AMQP_STATUS_OK on success, an amqp_status_enum on failure.
! 2302: *
! 2303: * \since v0.4.0
! 2304: */
! 2305: AMQP_EXPORT
! 2306: int AMQP_CALL amqp_socket_open_noblock(amqp_socket_t *self, const char *host,
! 2307: int port, const struct timeval *timeout);
! 2308:
! 2309: /**
! 2310: * Get the socket descriptor in use by a socket object.
! 2311: *
! 2312: * Retrieve the underlying socket descriptor. This function can be used to
! 2313: * perform low-level socket operations that aren't supported by the socket
! 2314: * interface. Use with caution!
! 2315: *
! 2316: * \param [in,out] self A socket object.
! 2317: *
! 2318: * \return The underlying socket descriptor, or -1 if there is no socket
! 2319: * descriptor associated with
! 2320: *
! 2321: * \since v0.4.0
! 2322: */
! 2323: AMQP_EXPORT
! 2324: int AMQP_CALL amqp_socket_get_sockfd(amqp_socket_t *self);
! 2325:
! 2326: /**
! 2327: * Get the socket object associated with a amqp_connection_state_t
! 2328: *
! 2329: * \param [in] state the connection object to get the socket from
! 2330: * \return a pointer to the socket object, or NULL if one has not been assigned
! 2331: *
! 2332: * \since v0.4.0
! 2333: */
! 2334: AMQP_EXPORT
! 2335: amqp_socket_t *AMQP_CALL amqp_get_socket(amqp_connection_state_t state);
! 2336:
! 2337: /**
! 2338: * Get the broker properties table
! 2339: *
! 2340: * \param [in] state the connection object
! 2341: * \return a pointer to an amqp_table_t containing the properties advertised
! 2342: * by the broker on connection. The connection object owns the table, it
! 2343: * should not be modified.
! 2344: *
! 2345: * \since v0.5.0
! 2346: */
! 2347: AMQP_EXPORT
! 2348: amqp_table_t *AMQP_CALL
! 2349: amqp_get_server_properties(amqp_connection_state_t state);
! 2350:
! 2351: /**
! 2352: * Get the client properties table
! 2353: *
! 2354: * Get the properties that were passed to the broker on connection.
! 2355: *
! 2356: * \param [in] state the connection object
! 2357: * \return a pointer to an amqp_table_t containing the properties advertised
! 2358: * by the client on connection. The connection object owns the table, it
! 2359: * should not be modified.
! 2360: *
! 2361: * \since v0.7.0
! 2362: */
! 2363: AMQP_EXPORT
! 2364: amqp_table_t *AMQP_CALL
! 2365: amqp_get_client_properties(amqp_connection_state_t state);
! 2366:
! 2367: /**
! 2368: * Get the login handshake timeout.
! 2369: *
! 2370: * amqp_login and amqp_login_with_properties perform the login handshake with
! 2371: * the broker. This function returns the timeout associated with completing
! 2372: * this operation from the client side. This value can be set by using the
! 2373: * amqp_set_handshake_timeout.
! 2374: *
! 2375: * Note that the RabbitMQ broker has configurable timeout for completing the
! 2376: * login handshake, the default is 10 seconds. rabbitmq-c has a default of 12
! 2377: * seconds.
! 2378: *
! 2379: * \param [in] state the connection object
! 2380: * \return a struct timeval representing the current login timeout for the state
! 2381: * object. A NULL value represents an infinite timeout. The memory returned is
! 2382: * owned by the connection object.
! 2383: *
! 2384: * \since v0.9.0
! 2385: */
! 2386: AMQP_EXPORT
! 2387: struct timeval *AMQP_CALL
! 2388: amqp_get_handshake_timeout(amqp_connection_state_t state);
! 2389:
! 2390: /**
! 2391: * Set the login handshake timeout.
! 2392: *
! 2393: * amqp_login and amqp_login_with_properties perform the login handshake with
! 2394: * the broker. This function sets the timeout associated with completing this
! 2395: * operation from the client side.
! 2396: *
! 2397: * The timeout must be set before amqp_login or amqp_login_with_properties is
! 2398: * called to change from the default timeout.
! 2399: *
! 2400: * Note that the RabbitMQ broker has a configurable timeout for completing the
! 2401: * login handshake, the default is 10 seconds. rabbitmq-c has a default of 12
! 2402: * seconds.
! 2403: *
! 2404: * \param [in] state the connection object
! 2405: * \param [in] timeout a struct timeval* representing new login timeout for the
! 2406: * state object. NULL represents an infinite timeout. The value of timeout is
! 2407: * copied internally, the caller is responsible for ownership of the passed in
! 2408: * pointer, it does not need to remain valid after this function is called.
! 2409: * \return AMQP_STATUS_OK on success.
! 2410: *
! 2411: * \since v0.9.0
! 2412: */
! 2413: AMQP_EXPORT
! 2414: int AMQP_CALL amqp_set_handshake_timeout(amqp_connection_state_t state,
! 2415: const struct timeval *timeout);
! 2416:
! 2417: /**
! 2418: * Get the RPC timeout
! 2419: *
! 2420: * Gets the timeout for any RPC-style AMQP command (e.g., amqp_queue_declare).
! 2421: * This timeout may be changed at any time by calling \amqp_set_rpc_timeout
! 2422: * function with a new timeout. The timeout applies individually to each RPC
! 2423: * that is made.
! 2424: *
! 2425: * The default value is NULL, or an infinite timeout.
! 2426: *
! 2427: * When an RPC times out, the function will return an error AMQP_STATUS_TIMEOUT,
! 2428: * and the connection will be closed.
! 2429: *
! 2430: *\warning RPC-timeouts are an advanced feature intended to be used to detect
! 2431: * dead connections quickly when the rabbitmq-c implementation of heartbeats
! 2432: * does not work. Do not use RPC timeouts unless you understand the implications
! 2433: * of doing so.
! 2434: *
! 2435: * \param [in] state the connection object
! 2436: * \return a struct timeval representing the current RPC timeout for the state
! 2437: * object. A NULL value represents an infinite timeout. The memory returned is
! 2438: * owned by the connection object.
! 2439: *
! 2440: * \since v0.9.0
! 2441: */
! 2442: AMQP_EXPORT
! 2443: struct timeval *AMQP_CALL amqp_get_rpc_timeout(amqp_connection_state_t state);
! 2444:
! 2445: /**
! 2446: * Set the RPC timeout
! 2447: *
! 2448: * Sets the timeout for any RPC-style AMQP command (e.g., amqp_queue_declare).
! 2449: * This timeout may be changed at any time by calling this function with a new
! 2450: * timeout. The timeout applies individually to each RPC that is made.
! 2451: *
! 2452: * The default value is NULL, or an infinite timeout.
! 2453: *
! 2454: * When an RPC times out, the function will return an error AMQP_STATUS_TIMEOUT,
! 2455: * and the connection will be closed.
! 2456: *
! 2457: *\warning RPC-timeouts are an advanced feature intended to be used to detect
! 2458: * dead connections quickly when the rabbitmq-c implementation of heartbeats
! 2459: * does not work. Do not use RPC timeouts unless you understand the implications
! 2460: * of doing so.
! 2461: *
! 2462: * \param [in] state the connection object
! 2463: * \param [in] timeout a struct timeval* representing new RPC timeout for the
! 2464: * state object. NULL represents an infinite timeout. The value of timeout is
! 2465: * copied internally, the caller is responsible for ownership of the passed
! 2466: * pointer, it does not need to remain valid after this function is called.
! 2467: * \return AMQP_STATUS_SUCCESS on success.
! 2468: *
! 2469: * \since v0.9.0
! 2470: */
! 2471: AMQP_EXPORT
! 2472: int AMQP_CALL amqp_set_rpc_timeout(amqp_connection_state_t state,
! 2473: const struct timeval *timeout);
! 2474:
! 2475: /**
! 2476: * Possible payload permutations for publisher confirms.
! 2477: **/
! 2478: typedef union amqp_publisher_confirm_payload_t_ {
! 2479: amqp_basic_ack_t ack; /* basic.ack */
! 2480: amqp_basic_nack_t nack; /* basic.nack */
! 2481: amqp_basic_reject_t reject; /* basic.reject */
! 2482: } amqp_publisher_confirm_payload_t;
! 2483:
! 2484: /**
! 2485: * Return information from publisher confirm wait
! 2486: **/
! 2487: typedef struct amqp_publisher_confirm_t_ {
! 2488: amqp_publisher_confirm_payload_t payload; /* The response payload; check the `method` value to see which value you should use in the union */
! 2489: amqp_channel_t channel; /* The channel where the confirmation was received */
! 2490: amqp_method_number_t method; /* The method which was received */
! 2491: } amqp_publisher_confirm_t;
! 2492:
! 2493: /**
! 2494: * amqp_publisher_confirm_wait
! 2495: *
! 2496: * Wait for a publisher confirm when one or more channel is in select mode.
! 2497: * If the response has a `reply_type` of `AMQP_RESPONSE_LIBRARY_EXCEPTION` _and_
! 2498: * the `library_error` is `AMQP_STATUS_UNEXPECTED_STATE`, then the frame
! 2499: * received was not an ack.
! 2500: *
! 2501: * In the event that there are no publisher confirms received during the
! 2502: * allotted time, `reply_type` will be `AMQP_RESPONSE_LIBRARY_EXCEPTION`
! 2503: * and the `library_error` will be `AMQP_STATUS_TIMEOUT`.
! 2504: *
! 2505: * When a publisher confirm is received, `reply_type` will equal
! 2506: * `AMQP_RESPONSE_NORMAL`, and the `result` out parameter will
! 2507: * contain all of the information you need:
! 2508: *
! 2509: * - The `channel` will identify which channel the publisher confirm was received on
! 2510: * - The `method` will tell you whether this is an `ack`, `nack`, or `reject`
! 2511: * - The `payload` is a union, and based on the `method` it will use one of `amqp_basic_ack_t`, `amqp_basic_nack_t`, or `amqp_basic_reject_t`
! 2512: *
! 2513: * \param [in] state connection state
! 2514: * \param [in] timeout when waiting for the frame. Passing NULL will result in
! 2515: * blocking behavior
! 2516: * \param [out] The result of the publisher confirm wait.
! 2517: */
! 2518: AMQP_EXPORT
! 2519: amqp_rpc_reply_t AMQP_CALL amqp_publisher_confirm_wait(
! 2520: amqp_connection_state_t state, const struct timeval *timeout,
! 2521: amqp_publisher_confirm_t *result);
! 2522:
! 2523: AMQP_END_DECLS
! 2524:
! 2525: #endif /* RABBITMQ_C_RABBITMQ_C_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to amqp.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / rabbitmq / include / rabbitmq-c