nats.c-main.zip

# NATS & NATS Streaming - C Client A C client for the [NATS messaging system](https://nats.io). Go [here](http://nats-io.github.io/nats.c) for the online documentation, and check the [frequently asked questions](https://github.com/nats-io/nats.c#faq). This NATS Client implementation is heavily based on the [NATS GO Client](https://github.com/nats-io/nats.go). There is support for Mac OS/X, Linux and Windows (although we don't have specific platform support matrix). [](https://www.apache.org/licenses/LICENSE-2.0) [](https://travis-ci.com/github/nats-io/nats.c) [](https://coveralls.io/github/nats-io/nats.c?branch=main) [](https://github.com/nats-io/nats.c/releases/tag/v3.8.2) [](http://nats-io.github.io/nats.c) # Table of Contents - [Installing](#installing) - [Building](#building) * [TLS Support](#tls-support) * [Link statically](#link-statically) * [Building with Streaming](#building-with-streaming) * [Building with Libsodium](#building-with-libsodium) * [Testing](#testing) - [Documentation](#documentation) - [NATS Client](#nats-client) * [Important Changes](#important-changes) * [JetStream](#jetstream) * [JetStream Basic Usage](#jetstream-basic-usage) * [JetStream Basic Management](#jetstream-basic-usage) * [KeyValue](#keyvalue) * [KeyValue Management](#keyvalue-management) * [KeyValue APIs](#keyvalue-apis) * [Getting Started](#getting-started) * [Basic Usage](#basic-usage) * [Headers](#headers) * [Wildcard Subscriptions](#wildcard-subscriptions) * [Queue Groups](#queue-groups) * [TLS](#tls) * [New Authentication (Nkeys and User Credentials)](#new-authentication-nkeys-and-user-credentials) * [Advanced Usage](#advanced-usage) * [Clustered Usage](#clustered-usage) * [Using an Event Loop Library](#using-an-event-loop-library) * [FAQ](#faq) - [NATS Streaming Client](#nats-streaming-client) * [Streaming Basic Usage](#streaming-basic-usage) * [Streaming Subscriptions](#streaming-subscriptions) * [Streaming Durable Subscriptions](#streaming-durable-subscriptions) * [Streaming Queue Groups](#streaming-queue-groups) * [Creating a Queue Group](#creating-a-queue-group) * [Start Position](#start-position) * [Leaving the Group](#leaving-the-group) * [Closing a Queue Group](#closing-a-queue-group) * [Streaming Durable Queue Groups](#streaming-durable-queue-groups) * [Creating a Durable Queue Group](#creating-a-durable-queue-group) * [Start Position of the Durable Queue Group](#start-position-of-the-durable-queue-group) * [Leaving the Durable Queue Group](#leaving-the-durable-queue-group) * [Closing the Durable Queue Group](#closing-the-durable-queue-group) * [Streaming Wildcard Subscriptions](#streaming-wildcard-subscriptions) * [Streaming Advanced Usage](#streaming-advanced-usage) * [Connection Status](#connection-status) * [Asynchronous Publishing](#asynchronous-publishing) * [Message Acknowledgments and Redelivery](#message-acknowledgments-and-redelivery) * [Rate limiting/matching](#rate-limitingmatching) * [Publisher Rate Limiting](#publisher-rate-limiting) * [Subscriber Rate Limiting](#subscriber-rate-limiting) - [License](#license) ## Installing There are several package managers with NATS C client library available. If you know one that is not in this list, please submit a PR to add it! - [conan](https://conan.io/center) The "cnats" recipe is [here](https://github.com/conan-io/conan-center-index/tree/master/recipes/cnats) - [Homebrew](https://github.com/Homebrew/homebrew-core) The "cnats" formula is [here](https://github.com/Homebrew/homebrew-core/blob/master/Formula/c/cnats.rb) - [vcpkg](https://vcpkg.io) The "cnats" port is [here](https://github.com/microsoft/vcpkg/tree/master/ports/cnats) ## Building First, download the source code: ``` git clone git@github.com:nats-io/nats.c.git . ``` To build the library, use [CMake](https://cmake.org/download/). Note that by default the NATS Streaming API will be built and included in the NATS library. See below if you do not want to build the Streaming related APIs. Make sure that CMake is added to your path. If building on Windows, open a command shell from the Visual Studio Tools menu, and select the appropriate command shell (x64 or x86 for 64 or 32 bit builds respectively). You will also probably need to run this with administrator privileges. Create a `build` directory (any name would work) from the root source tree, and `cd` into it. Then issue this command for the first time: ``` cmake .. ``` In some architectures, you may experience a compilation error for `mutex.c.o` because there is no support for the assembler instruction that we use to yield when spinning trying to acquire a lock. You may get this sort of build error: ``` /tmp/cc1Yp7sD.s: Assembler messages: /tmp/cc1Yp7sD.s:302: Error: selected processor does not support ARM mode `yield' src/CMakeFiles/nats_static.dir/build.make:542: recipe for target 'src/CMakeFiles/nats_static.dir/unix/mutex.c.o' failed ``` If that's the case, you can solve this by enabling the `NATS_BUILD_NO_SPIN` flag (or use `-DNATS_NO_SPIN` if you compile without CMake): ``` cmake .. -DNATS_BUILD_NO_SPIN=ON ``` If you had previously built the library, you may need to do a `make clean`, or simply delete and re-create the build directory before executing the cmake command. To build on Windows, you would need to select the build generator. For instance, to select `nmake`, you would run: ``` cmake .. -G "NMake Makefiles" ``` Running `cmake -h` would give you the list of possible options and all the generator names. Alternatively, you can run the GUI version. From that same *build* command shell, start the GUI: ``` c:\program files (x86)\CMake\bin\cmake-gui.exe ``` If you started with an empty build directory, you would need to select the source and build directory, then click `Configure`. Here, you will be able to select from the drop-down box the name of the build generator. When done, click `Generate`. Then you can go back to your command shell, or Visual Studio and build. To modify some of the build options, you need to edit the cache and rebuild. ``` make edit_cache ``` Note that if you build on Windows and have selected "NMake Makefiles", replace all following references to `make` with `nmake`. Editing the cache allows you to select the build type (Debug, Release, etc), the architecture (64 or 32bit), and so on. The default target will build everything, that is, the static and shared NATS libraries and also the examples and the test program. Each are located in their respective directories under your build directory: `src`, `examples` and `test`. ``` make install ``` Will copy both the static and shared libraries in the folder `install/lib` and the public headers in `install/include`. ## TLS Support By default, the library is built with TLS support. You can disable this from the cmake gui `make edit_cache` and switch the `NATS_BUILD_WITH_TLS` option to `OFF`, or pass the option directly to the `cmake` command: ``` cmake .. -DNATS_BUILD_WITH_TLS=OFF ``` Starting `2.0.0`, when building with TLS/SSL support, the server certificate's expected hostname is always verified. It means that the hostname provided in the URL(s) or through the option `natsOptions_SetExpectedHostname()` will be used to check the hostname present in the certificate. Prior to `2.0.0`, the hostname would be verified *only* if the option `natsOptions_SetExpectedHostname()` was invoked. Although we recommend leaving the new default behavior, you can restore the previous