|
Packit Service |
64969d |
# RabbitMQ C AMQP client library
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
[![Build Status](https://secure.travis-ci.org/alanxz/rabbitmq-c.png?branch=master)](http://travis-ci.org/alanxz/rabbitmq-c)
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
[![Coverage Status](https://coveralls.io/repos/github/alanxz/rabbitmq-c/badge.svg?branch=master)](https://coveralls.io/github/alanxz/rabbitmq-c?branch=master)
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
## Introduction
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
This is a C-language AMQP client library for use with v2.0+ of the
|
|
Packit Service |
64969d |
[RabbitMQ](http://www.rabbitmq.com/) broker.
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
- <http://github.com/alanxz/rabbitmq-c>
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
Announcements regarding the library are periodically made on the
|
|
Packit Service |
64969d |
rabbitmq-c-users and cross-posted to rabbitmq-users.
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
- <https://groups.google.com/forum/#!forum/rabbitmq-c-users>
|
|
Packit Service |
64969d |
- <https://groups.google.com/forum/#!forum/rabbitmq-users>
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
## Latest Stable Version
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
The latest stable release of rabbitmq-c can be found at:
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
- <https://github.com/alanxz/rabbitmq-c/releases/latest>
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
## Documentation
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
API documentation for v0.8.0+ can viewed from:
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
<http://alanxz.github.io/rabbitmq-c/docs/0.8.0/>
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
## Getting started
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
### Building and installing
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
#### Prereqs:
|
|
Packit Service |
64969d |
- [CMake v2.6 or better](http://www.cmake.org/)
|
|
Packit Service |
64969d |
- A C compiler (GCC 4.4+, clang, and MSVC are test. Other compilers may also
|
|
Packit Service |
64969d |
work)
|
|
Packit Service |
64969d |
- *Optionally* [OpenSSL](http://www.openssl.org/) v0.9.8+ to enable support for
|
|
Packit Service |
64969d |
connecting to RabbitMQ over SSL/TLS
|
|
Packit Service |
64969d |
- *Optionally* [POpt](http://freecode.com/projects/popt) to build some handy
|
|
Packit Service |
64969d |
command-line tools.
|
|
Packit Service |
64969d |
- *Optionally* [XmlTo](https://fedorahosted.org/xmlto/) to build man pages for
|
|
Packit Service |
64969d |
the handy command-line tools
|
|
Packit Service |
64969d |
- *Optionally* [Doxygen](http://www.stack.nl/~dimitri/doxygen/) to build
|
|
Packit Service |
64969d |
developer API documentation.
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
After downloading and extracting the source from a tarball to a directory
|
|
Packit Service |
64969d |
([see above](#latest-stable-version)), the commands to build rabbitmq-c on most
|
|
Packit Service |
64969d |
systems are:
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
mkdir build && cd build
|
|
Packit Service |
64969d |
cmake ..
|
|
Packit Service |
64969d |
cmake --build [--config Release] .
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
The --config Release flag should be used in multi-configuration generators e.g.,
|
|
Packit Service |
64969d |
Visual Studio or XCode.
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
It is also possible to point the CMake GUI tool at the CMakeLists.txt in the root of
|
|
Packit Service |
64969d |
the source tree and generate build projects or IDE workspace
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
Installing the library and optionally specifying a prefix can be done with:
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
|
|
Packit Service |
64969d |
cmake --build . [--config Release] --target install
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
More information on CMake can be found on its FAQ (http://www.cmake.org/Wiki/CMake_FAQ)
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
Other interesting flags that can be passed to CMake:
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
* `BUILD_EXAMPLES=ON/OFF` toggles building the examples. ON by default.
|
|
Packit Service |
64969d |
* `BUILD_SHARED_LIBS=ON/OFF` toggles building rabbitmq-c as a shared library.
|
|
Packit Service |
64969d |
ON by default.
|
|
Packit Service |
64969d |
* `BUILD_STATIC_LIBS=ON/OFF` toggles building rabbitmq-c as a static library.
|
|
Packit Service |
64969d |
OFF by default.
|
|
Packit Service |
64969d |
* `BUILD_TESTS=ON/OFF` toggles building test code. ON by default.
|
|
Packit Service |
64969d |
* `BUILD_TOOLS=ON/OFF` toggles building the command line tools. By default
|
|
Packit Service |
64969d |
this is ON if the build system can find the POpt header and library.
|
|
Packit Service |
64969d |
* `BUILD_TOOLS_DOCS=ON/OFF` toggles building the man pages for the command line
|
|
Packit Service |
64969d |
tools. By default this is ON if BUILD_TOOLS is ON and the build system can
|
|
Packit Service |
64969d |
find the XmlTo utility.
|
|
Packit Service |
64969d |
* `ENABLE_SSL_SUPPORT=ON/OFF` toggles building rabbitmq-c with SSL support. By
|
|
Packit Service |
64969d |
default this is ON if the OpenSSL headers and library can be found.
|
|
Packit Service |
64969d |
* `BUILD_API_DOCS=ON/OFF` - toggles building the Doxygen API documentation, by
|
|
Packit Service |
64969d |
default this is OFF
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
## Running the examples
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
Arrange for a RabbitMQ or other AMQP server to be running on
|
|
Packit Service |
64969d |
`localhost` at TCP port number 5672.
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
In one terminal, run
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
./examples/amqp_listen localhost 5672 amq.direct test
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
In another terminal,
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
./examples/amqp_sendstring localhost 5672 amq.direct test "hello world"
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
You should see output similar to the following in the listener's
|
|
Packit Service |
64969d |
terminal window:
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
Delivery 1, exchange amq.direct routingkey test
|
|
Packit Service |
64969d |
Content-type: text/plain
|
|
Packit Service |
64969d |
----
|
|
Packit Service |
64969d |
00000000: 68 65 6C 6C 6F 20 77 6F : 72 6C 64 hello world
|
|
Packit Service |
64969d |
0000000B:
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
## Writing applications using `librabbitmq`
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
Please see the `examples` directory for short examples of the use of
|
|
Packit Service |
64969d |
the `librabbitmq` library.
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
### Threading
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
You cannot share a socket, an `amqp_connection_state_t`, or a channel
|
|
Packit Service |
64969d |
between threads using `librabbitmq`. The `librabbitmq` library is
|
|
Packit Service |
64969d |
built with event-driven, single-threaded applications in mind, and
|
|
Packit Service |
64969d |
does not yet cater to any of the requirements of `pthread`ed
|
|
Packit Service |
64969d |
applications.
|
|
Packit Service |
64969d |
|
|
Packit Service |
64969d |
Your applications instead should open an AMQP connection (and an
|
|
Packit Service |
64969d |
associated socket, of course) per thread. If your program needs to
|
|
Packit Service |
64969d |
access an AMQP connection or any of its channels from more than one
|
|
Packit Service |
64969d |
thread, it is entirely responsible for designing and implementing an
|
|
Packit Service |
64969d |
appropriate locking scheme. It will generally be much simpler to have
|
|
Packit Service |
64969d |
a connection exclusive to each thread that needs AMQP service.
|