nats.c
v3.9.2
NATS メッセージング システムの AC クライアント。
ここにアクセスしてオンライン ドキュメントを参照し、よくある質問を確認してください。
この NATS クライアントの実装は、NATS GO クライアントに大きく基づいています。 Mac OS/X、Linux、Windows がサポートされています (ただし、特定のプラットフォームのサポート マトリックスはありません)。
NATS C クライアント ライブラリを備えたパッケージ マネージャーがいくつか利用可能です。このリストにないものをご存知の場合は、PR を送信して追加してください。
まず、ソースコードをダウンロードします。
git clone [email protected]:nats-io/nats.c.git .
ライブラリを構築するには、CMake を使用します。デフォルトでは、NATS ストリーミング API が構築され、NATS ライブラリに含まれることに注意してください。ストリーミング関連の API を構築したくない場合は、以下を参照してください。
CMake がパスに追加されていることを確認してください。 Windows 上でビルドする場合は、Visual Studio の [ツール] メニューからコマンド シェルを開き、適切なコマンド シェル (64 ビット ビルドの場合は x64、32 ビット ビルドの場合は x86) を選択します。おそらく、管理者権限でこれを実行する必要もあります。
ルート ソース ツリーからbuildディレクトリ (任意の名前が機能します) を作成し、そこにcdます。次に、初めて次のコマンドを発行します。
cmake ..
一部のアーキテクチャでは、ロックを取得しようとするスピン時に譲歩するために使用するアセンブラ命令がサポートされていないため、 mutex.coのコンパイル エラーが発生する可能性があります。
次のようなビルド エラーが発生する場合があります。
/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
その場合は、 NATS_BUILD_NO_SPINフラグを有効にすることで問題を解決できます (または、CMake を使用せずにコンパイルする場合は-DNATS_NO_SPINを使用します)。
cmake .. -DNATS_BUILD_NO_SPIN=ON
以前にライブラリをビルドしたことがある場合は、 cmake コマンドを実行する前に、 make clean実行するか、単純にビルド ディレクトリを削除して再作成する必要がある場合があります。
Windows 上でビルドするには、ビルド ジェネレーターを選択する必要があります。たとえば、 nmake選択するには、次を実行します。
cmake .. -G "NMake Makefiles"
cmake -h実行すると、使用可能なオプションのリストとすべてのジェネレーター名が表示されます。
あるいは、GUI バージョンを実行することもできます。同じビルドコマンド シェルから GUI を起動します。
c:program files (x86)CMakebincmake-gui.exe
空のビルド ディレクトリから開始した場合は、ソースとビルド ディレクトリを選択し、 Configureクリックする必要があります。ここで、ドロップダウン ボックスからビルド ジェネレーターの名前を選択できます。完了したら、 Generateをクリックします。その後、コマンド シェルまたは Visual Studio に戻ってビルドできます。
一部のビルド オプションを変更するには、キャッシュを編集して再構築する必要があります。
make edit_cache
Windows 上でビルドし、「NMake Makefiles」を選択した場合は、次のmakeへの参照をすべてnmakeに置き換えてください。
キャッシュを編集すると、ビルド タイプ (デバッグ、リリースなど)、アーキテクチャ (64 または 32 ビット) などを選択できます。
デフォルトのターゲットは、静的および共有 NATS ライブラリ、サンプルおよびテスト プログラムなど、すべてをビルドします。それぞれは、ビルド ディレクトリの下のそれぞれのディレクトリにあります: src 、 examples 、およびtest 。
make install
静的ライブラリと共有ライブラリの両方をinstall/libフォルダーにコピーし、パブリック ヘッダーをinstall/includeにコピーします。
デフォルトでは、ライブラリは TLS サポートを使用して構築されます。 cmake gui make edit_cacheからこれを無効にしてNATS_BUILD_WITH_TLSオプションをOFFに切り替えるか、オプションをcmakeコマンドに直接渡すことができます。
cmake .. -DNATS_BUILD_WITH_TLS=OFF
2.0.0以降、TLS/SSL サポートを使用して構築する場合、サーバー証明書の予期されるホスト名が常に検証されます。これは、URL またはオプションnatsOptions_SetExpectedHostname()で指定されたホスト名が、証明書に存在するホスト名を確認するために使用されることを意味します。 2.0.0より前では、ホスト名はオプションnatsOptions_SetExpectedHostname()が呼び出された場合にのみ検証されます。
新しいデフォルトの動作をそのままにすることをお勧めしますが、このオプションをオフにしてライブラリをビルドすることで以前の動作を復元できます。
cmake .. -DNATS_BUILD_TLS_FORCE_HOST_VERIFY=OFF
NATS C クライアントは、OpenSSL ライブラリの API を使用して構築されます。デフォルトでは3.0+ API を使用します。 NATS C クライアントv3.6.0バージョン以降、OpenSSL 1.0.2サポートされなくなったため、CMake 変数NATS_BUILD_TLS_USE_OPENSSL_1_1_APIはデフォルトでONに設定され (新しい環境をセットアップしている場合)、 1.1+以降の OpenSSL API を使用するようになります。 3.0+ API。この CMake オプションをOFFに設定することで、OpenSSL 1.0.2ライブラリを使用してコンパイルすることができます。
cmake .. -DNATS_BUILD_TLS_USE_OPENSSL_1_1_API=OFF
変数NATS_BUILD_TLS_USE_OPENSSL_1_1_APIは非推奨になりました。つまり、将来的には、このオプションは単に削除され、OpenSSL 3.0+ API のみが使用されることになります。古い OpenSSL API を使用するライブラリ内のコードも削除されます。
v2.0.0で非推奨となった変数NATS_BUILD_WITH_TLS_CLIENT_METHODは削除されたことに注意してください。
NATS C クライアントは OpenSSL ライブラリに動的にリンクするため、アプリケーションを OpenSSL 1.1+/3.0+ ライブラリに対して実行していることを確認する必要があります。
静的 OpenSSL ライブラリにリンクする場合は、 CMakeCache.txtを削除し、追加のオプションを使用して再生成する必要があります。
rm CMakeCache.txt
cmake .. -DNATS_BUILD_OPENSSL_STATIC_LIBS=ON
次に、 make (またはプラットフォームに応じて同等の機能) を呼び出します。これにより、ライブラリ (およびサンプルおよび/またはテスト スイートの実行可能ファイル) が CMake によって見つかった場合、OpenSSL ライブラリに対して確実にリンクされます。
ストリーミング サポートを使用してライブラリを構築する場合、NATS ライブラリは libprotobuf-c ライブラリを使用します。 cmake を初めて実行するとき (またはCMakeCache.txtを削除してcmake ..再度呼び出した後)、cmake は libprotobuf-c ライブラリを探します。見つからない場合は、メッセージが出力され、ビルド プロセスは失敗します。 CMake は、ライブラリが通常見つかるディレクトリでライブラリを検索します。ただし、ライブラリが配置されている特定のディレクトリを指定する場合は、次のようにする必要があります。
cmake .. -DNATS_PROTOBUF_DIR=
デフォルトでは静的ライブラリが使用されます。これを変更したい場合、またはライブラリの名前が予期したものではない場合は、次の操作を行う必要があります。
# Use the library named mylibproto.so located at /my/location
cmake .. -DNATS_PROTOBUF_LIBRARY=/my/location/mylibproto.so
インクルードヘッダーが別のディレクトリにある場合、この 2 つは結合される可能性があります。
# Use the library named mylibproto.so located at /my/location and the directory protobuf-c/ containing protobuf-c.h located at /my/other/location
cmake .. -DNATS_PROTOBUF_LIBRARY=/my/location/mylibproto.so -DNATS_PROTOBUF_DIR=/my/other/location
NATS ストリーミング API を構築して NATS ライブラリに含めたくない場合は、次のようにします。
cmake .. -DNATS_BUILD_STREAMING=OFF
新しい NATS 2.0 セキュリティ機能を使用する場合、ライブラリは、接続または再接続中にサーバーによって送信される「ノンス」に署名する必要があります。 Ed25519 公開鍵署名を使用します。ライブラリには、署名を実行するためのコードが付属しています。ほとんどの場合は問題ありませんが、パフォーマンスが問題になる場合 (特にnatsConnection_Sign()関数を頻繁に使用する予定がある場合)、Libsodium ライブラリを使用してビルドするオプションがあります。
ここで libsodium ライブラリをインストールする方法の指示に従ってください。
macOS では、 brew使用できます。
brew install libsodium
Linux では、 apt-get使用できます
apt-get install libsodium-dev
インストールしたら、まず libsodium ライブラリの使用を有効にすることで、NATS C クライアントを再構築できます。
cmake .. -DNATS_BUILD_USE_SODIUM=ON
CMake が見つけられない標準以外の場所に libsodium ライブラリをインストールしている場合は、このディレクトリの場所を指定できます。
cmake .. -DNATS_BUILD_USE_SODIUM=ON -DNATS_SODIUM_DIR=/my/path/to/libsodium
valgrindが利用可能なプラットフォームでは、メモリ チェックを使用してテストを実行できます。以下に例を示します。
make test ARGS="-T memcheck"
または、 ctestプログラムを直接呼び出すこともできます。
ctest -T memcheck -V -I 1,4
上記のコマンドは、 valgrind ( -T memcheck )、詳細出力 ( -V ) を使用してテストを実行し、1 から 4 までのテスト ( -I 1,4 ) を実行します。
テストをtest/test.cに追加する場合は、それをlist_test.txtファイルに追加する必要があります。各エントリにはテスト名のみが含まれており、関数にはtest_プレフィックスを付けた同一の名前を付ける必要があります。リストはアルファベット順ですが、必ずしもそうである必要はなく、どこにでも追加できます。
ベンチマークを追加する場合は、 list_bench.txtに追加する必要があります。これらのテストには異なるラベルが付けられ ( -L 'bench' )、CI 上で個別に実行されます。
変更を有効にするには、 cmake再実行する必要があります。
cmake ..
-- Configuring done
-- Generating done
-- Build files have been written to: /home/ivan/nats.c/build
次の環境変数を使用して、テストスイートの動作に影響を与えることができます。
メモリ チェックを使用して実行すると、タイミングが変化し、全体的なパフォーマンスが低下します。次の変数を使用すると、テストスイートでテスト中に使用される値の一部を調整できます。
export NATS_TEST_VALGRIND=yes
Windows では、 export代わりにsetます。
テストを冗長モードで実行する場合、次の環境変数を使用すると、テスト自体内からサーバーの出力を確認できます。このオプションを使用しない場合、サーバー出力は沈黙します。
export NATS_TEST_KEEP_SERVER_OUTPUT=yes
デフォルトのサーバー実行可能ファイル名 ( nats-server.exe ) を変更する場合、または特定の場所を指定する場合は、次の環境変数を使用します。
set NATS_TEST_SERVER_EXE=c:testnats-server.exe
パブリック API は Doxygen を使用して文書化されています。
ドキュメントを生成するには、 docディレクトリに移動し、次のコマンドを入力します。
doxygen DoxyFile.NATS.Client
ストリーミング API のビルドを切り替え、ドキュメントがビルド中のものと一致しなくなった場合は、 NATS_UPDATE_DOCビルド フラグを切り替えてドキュメントを更新し、ドキュメントを再ビルドできます。
ビルド ディレクトリから:
cmake .. -DNATS_UPDATE_DOC=ON
make
cd /doc
doxygen DoxyFile.NATS.Client
生成されたドキュメントはhtmlディレクトリに配置されます。ドキュメントを参照するには、ブラウザでそのディレクトリ内のファイルindex.htmlを指定します。
オンラインドキュメントについては、ここにアクセスしてください。
ソースコードも十分に文書化されています。
このセクションには、非推奨の通知などの重要な変更がリストされています。
2.0.0このバージョンでは、NATS Server 2.0.0で使用されるセキュリティ概念が導入されているため、サーバーのバージョンと一致しています。新しい API が導入されましたが、最も重要な変更点は、TLS 接続での新しいデフォルトの動作です。
安全な接続を確立するときに、ユーザーがnatsOptions_SetExpectedHostname()を呼び出したかどうかに関係なく、サーバー証明書のホスト名が常に検証されるようになりました。これにより、たとえば、証明書にホスト名しか含まれていないサーバーに接続するために IP を使用していたアプリケーションが機能しなくなる可能性があります。これは、URL でホスト名を使用するようにアプリケーションを変更するか、 natsOptions_SetExpectedHostname()を使用することで解決できます。これが不可能な場合は、新しい動作を無効にしてライブラリをビルドすることで、古い動作を復元できます。詳細については、#tls-support を参照してください。
このリポジトリには、macOS、Linux、および Windows 用の libprotobuf-c のプリコンパイル済みライブラリとヘッダー ファイル ( /pbufディレクトリ内) が含まれていました。このディレクトリは削除されたため、ユーザーは libprotobuf-c ライブラリを個別にインストールする必要があります。 CMake がライブラリの場所を直接見つけられない場合は、構築手順を参照してライブラリの場所を指定してください。
1.8.0natsConnStatus列挙値には、 NATS_CONN_STATUS_という接頭辞が付けられています。アプリケーションがCONNECTEDやCLOSEDなどの元の値の参照を使用していない場合は、何もする必要はありません。そうする場合、次の 2 つのオプションがあります。NATS_BUILD_NO_PREFIX_CONNSTSをオンにします。これは、ビルド ディレクトリから次の方法で実行できます: cmake .. -DNATS_BUILD_NO_PREFIX_CONNSTS=ON examples/getstartedディレクトリには、完全に機能しつつも非常にシンプルなサンプルのセットが含まれています。目標は、API の使用がいかに簡単であるかを実証することです。
より複雑な例のセットは、 examples/ディレクトリにあり、クライアント ライブラリのベンチマークに使用することもできます。
簡単にするために、ここではエラー チェックは実行されないことに注意してください。
natsConnection * nc = NULL ;
natsSubscription * sub = NULL ;
natsMsg * msg = NULL ;
// Connects to the default NATS Server running locally
natsConnection_ConnectTo ( & nc , NATS_DEFAULT_URL );
// Connects to a server with username and password
natsConnection_ConnectTo ( & nc , "nats://ivan:secret@localhost:4222" );
// Connects to a server with token authentication
natsConnection_ConnectTo ( & nc , "nats://myTopSecretAuthenticationToken@localhost:4222" );
// Simple publisher, sending the given string to subject "foo"
natsConnection_PublishString ( nc , "foo" , "hello world" );
// Publish binary data. Content is not interpreted as a string.
char data [] = { 1 , 2 , 0 , 4 , 5 };
natsConnection_Publish ( nc , "foo" , ( const void * ) data , 5 );
// Simple asynchronous subscriber on subject foo, invoking message
// handler 'onMsg' when messages are received, and not providing a closure.
natsConnection_Subscribe ( & sub , nc , "foo" , onMsg , NULL );
// Simple synchronous subscriber
natsConnection_SubscribeSync ( & sub , nc , "foo" );
// Using a synchronous subscriber, gets the first message available, waiting
// up to 1000 milliseconds (1 second)
natsSubscription_NextMsg ( & msg , sub , 1000 );
// Destroy any message received (asynchronously or synchronously) or created
// by your application. Note that if 'msg' is NULL, the call has no effect.
natsMsg_Destroy ( msg );
// Unsubscribing
natsSubscription_Unsubscribe ( sub );
// Destroying the subscription (this will release the object, which may
// result in freeing the memory). After this call, the object must no
// longer be used.
natsSubscription_Destroy ( sub );
// Publish requests to the given reply subject:
natsConnection_PublishRequestString ( nc , "foo" , "bar" , "help!" );
// Sends a request (internally creates an inbox) and Auto-Unsubscribe the
// internal subscriber, which means that the subscriber is unsubscribed
// when receiving the first response from potentially many repliers.
// This call will wait for the reply for up to 1000 milliseconds (1 second).
natsConnection_RequestString ( & reply , nc , "foo" , "help" , 1000 );
// Closing a connection (but not releasing the connection object)
natsConnection_Close ( nc );
// When done with the object, free the memory. Note that this call
// closes the connection first, in other words, you could have simply
// this call instead of natsConnection_Close() followed by the destroy
// call.
natsConnection_Destroy ( nc );
// Message handler
void
onMsg ( natsConnection * nc , natsSubscription * sub , natsMsg * msg , void * closure )
{
// Prints the message, using the message getters:
printf ( "Received msg: %s - %.*sn" ,
natsMsg_GetSubject ( msg ),
natsMsg_GetDataLength ( msg ),
natsMsg_GetData ( msg ));
// Don't forget to destroy the message!
natsMsg_Destroy ( msg );
}JetStream のサポートは、ライブラリのバージョンv3.0.0および NATS サーバーv2.2.0+から始まりますが、JetStream 固有のエラー コードを取得するには、バージョンv2.3.0+のサーバーが必要です。一部の構成オプションはv2.3.3以降でのみ使用できるため、より良いエクスペリエンスを得るために最新の NATS サーバー リリースを使用することをお勧めします。
API の使用方法の例については、 examplesディレクトリにあるjs-xxx.cという名前のサンプルを参照してください。新しいオブジェクトと API については、オンライン ドキュメントに詳しく記載されています。
// Connect to NATS
natsConnection_Connect ( & conn , opts );
// Initialize and set some JetStream options
jsOptions jsOpts ;
jsOptions_Init ( & jsOpts );
jsOpts . PublishAsync . MaxPending = 256 ;
// Create JetStream Context
natsConnection_JetStream ( & js , conn , & jsOpts );
// Simple Stream Publisher
js_Publish ( & pa , js , "ORDERS.scratch" , ( const void * ) "hello" , 5 , NULL , & jerr );
// Simple Async Stream Publisher
for ( i = 0 ; i < 500 ; i ++ )
{
js_PublishAsync ( js , "ORDERS.scratch" , ( const void * ) "hello" , 5 , NULL );
}
// Wait for up to 5 seconds to receive all publish acknowledgments.
jsPubOptions_Init ( & jsPubOpts );
jsPubOpts . MaxWait = 5000 ;
js_PublishAsyncComplete ( js , & jsPubOpts );
// One can get the list of all pending publish async messages,
// to either resend them or simply destroy them.
natsMsgList pending ;
s = js_PublishAsyncGetPendingList ( & pending , js );
if ( s == NATS_OK )
{
int i ;
for ( i = 0 ; i < pending . Count ; i ++ )
{
// There could be a decision to resend these messages or not.
if ( your_decision_to_resend ( pending . Msgs [ i ]))
{
// If the call is successful, pending.Msgs[i] will be set
// to NULL so destroying the pending list will not destroy
// this message since the library has taken ownership back.
js_PublishMsgAsync ( js , & ( pending . Msgs [ i ]), NULL );
}
}
// Destroy the pending list object and all messages still in that list.
natsMsgList_Destroy ( & pending );
}
// To create an asynchronous ephemeral consumer
js_Subscribe ( & sub , js , "foo" , myMsgHandler , myClosure , & jsOpts , NULL , & jerr );
// Same but use a subscription option to ask the callback to not do auto-ack.
jsSubOptions so ;
jsSubOptions_Init ( & so );
so . ManualAck = true;
js_Subscribe ( & sub , js , "foo" , myMsgHandler , myClosure , & jsOpts , & so , & jerr );
// Or to bind to an existing specific stream/durable:
jsSubOptions_Init ( & so );
so . Stream = "MY_STREAM" ;
so . Consumer = "my_durable" ;
js_Subscribe ( & sub , js , "foo" , myMsgHandler , myClosure , & jsOpts , & so , & jerr );
// Synchronous subscription:
js_SubscribeSync ( & sub , js , "foo" , & jsOpts , & so , & jerr ); jsStreamConfig cfg ;
// Connect to NATS
natsConnection_Connect ( & conn , opts );
// Create JetStream Context
natsConnection_JetStream ( & js , conn , NULL );
// Initialize the configuration structure.
jsStreamConfig_Init ( & cfg );
// Provide a name
cfg . Name = "ORDERS" ;
// Array of subjects and its size
cfg . Subjects = ( const char * [ 1 ]){ "ORDERS.*" };
cfg . SubjectsLen = 1 ;
// Create a Stream. If you are not interested in the returned jsStreamInfo object,
// you can pass NULL.
js_AddStream ( NULL , js , & cfg , NULL , & jerr );
// Update a Stream
cfg . MaxBytes = 8 ;
js_UpdateStream ( NULL , js , & cfg , NULL , & jerr );
// Delete a Stream
js_DeleteStream ( js , "ORDERS" , NULL , & jerr );実験的な機能！当社は、必ずしもライブラリのメジャー バージョンを変更することなく API を変更する権利を留保します。
KeyValue ストアは、JetStream に基づいたマテリアライズド ビューです。バケットはストリームであり、キーはそのストリーム内のサブジェクトです。
一部の機能には NATS サーバーv2.6.2必要なため、より良いエクスペリエンスを得るために最新の NATS サーバー リリースを使用することをお勧めします。
新しいオブジェクトと API については、オンライン ドキュメントに詳しく記載されています。
KeyValue ストアの作成方法の例:
jsCtx * js = NULL ;
kvStore * kv = NULL ;
kvConfig kvc ;
// Assume we got a JetStream context in `js`...
kvConfig_Init ( & kvc );
kvc . Bucket = "KVS" ;
kvc . History = 10 ;
s = js_CreateKeyValue ( & kv , js , & kvc );
// Do some stuff...
// This is to free the memory used by `kv` object,
// not delete the KeyValue store in the server
kvStore_Destroy ( kv );これは、既存のものに「バインド」する方法を示しています。
jsCtx * js = NULL ;
kvStore * kv = NULL ;
// Assume we got a JetStream context in `js`...
s = js_KeyValue ( & kv , ks , "KVS" );
// Do some stuff...
// This is to free the memory used by `kv` object,
// not delete the KeyValue store in the server
kvStore_Destroy ( kv );サーバー内の KeyValue ストアを削除する方法は次のとおりです。
jsCtx * js = NULL ;
// Assume we got a JetStream context in `js`...
s = js_DeleteKeyValue ( js , "KVS" );指定されたキーに値を設定する方法は次のとおりです。
kvStore * kv = NULL ;
uint64_t rev = 0 ;
// Assume we got a kvStore...
s = kvStore_PutString ( & rev , kv , "MY_KEY" , "my value" );
// If the one does not care about getting the revision, pass NULL:
s = kvStore_PutString ( NULL , kv , "MY_KEY" , "my value" );上記は指定されたキーに値を配置しますが、代わりに、キーが以前に存在したことがない場合にのみ値がキーに配置されることを確認したい場合は、次のように呼び出します。
// Same note than before: if "rev" is not needed, pass NULL:
s = kvStore_CreateString ( & rev , kv , "MY_KEY" , "my value" );サーバー内の最後のリビジョンがこの API に渡されたものと一致する場合にのみ、キーを更新できます。
// This would update the key "MY_KEY" with the value "my updated value" only if the current revision (sequence number) for this key is 10.
s = kvStore_UpdateString ( & rev , kv , "MY_KEY" , "my updated value" , 10 );キーを取得する方法は次のとおりです。
kvStore * kv = NULL ;
kvEntry * e = NULL ;
// Assume we got a kvStore...
s = kvStore_Get ( & e , kv , "MY_KEY" );
// Then we can get some fields from the entry:
printf ( "Key value: %sn" , kvEntry_ValueString ( e ));
// Once done with the entry, we need to destroy it to release memory.
// This is NOT deleting the key from the server.
kvEntry_Destroy ( e );キーをパージする方法は次のとおりです。
kvStore * kv = NULL ;
// Assume we got a kvStore...
s = kvStore_Purge ( kv , "MY_KEY" );これにより、サーバー内のキーが削除されます。
kvStore * kv = NULL ;
// Assume we got a kvStore...
s = kvStore_Delete ( kv , "MY_KEY" );特定のキーの「ウォッチャー」を作成するには:
kvWatcher * w = NULL ;
kvWatchOptions o ;
// Assume we got a kvStore...
// Say that we are not interested in getting the
// delete markers...
// Initialize a kvWatchOptions object:
kvWatchOptions_Init ( & o );
o . IgnoreDeletes = true;
// Create the watcher
s = kvStore_Watch ( & w , kv , "foo.*" , & o );
// Check for error..
// Now get updates:
while ( some_condition )
{
kvEntry * e = NULL ;
// Wait for the next update for up to 5 seconds
s = kvWatcher_Next ( & e , w , 5000 );
// Do something with the entry...
// Destroy to release memory
kvEntry_Destroy ( e );
}
// When done with the watcher, it needs to be destroyed to release memory:
kvWatcher_Destroy ( w );キーの履歴を取得するには:
kvEntryList l ;
int i ;
// The list is defined on the stack and will be initilized/updated by this call:
s = kvStore_History ( & l , kv , "MY_KEY" , NULL );
for ( i = 0 ; i < l . Count ; i ++ )
{
kvEntry * e = l . Entries [ i ];
// Do something with the entry...
}
// When done with the list, call this to free entries and the content of the list.
kvEntryList_Destroy ( & l );
// In order to set a timeout to get the history, we need to do so through options:
kvWatchOptions o ;
kvWatchOptions_Init ( & o );
o . Timeout = 5000 ; // 5 seconds.
s = kvStore_History ( & l , kv , "MY_KEY" , & o );バケットのキーを取得する方法は次のとおりです。
kvKeysList l ;
int i ;
// If no option is required, pass NULL as the last argument.
s = kvStore_Keys ( & l , kv , NULL );
// Check error..
// Go over all keys:
for ( i = 0 ; i < l . Count ; i ++ )
printf ( "Key: %sn" , l . Keys [ i ]);
// When done, list need to be destroyed.
kvKeysList_Destroy ( & l );
// If option need to be specified:
kvWatchOptions o ;
kvWatchOptions_Init ( & o );
o . Timeout = 5000 ; // 5 seconds.
s = kvStore_Keys ( & l , kv , & o );ヘッダーは、バージョン 2.2.0 以降のサーバーに接続するときに使用できます。
これらは http ヘッダーによく似ています。これらはキーと値のペアのマップであり、値は文字列の配列です。
ヘッダーを使用すると、ユーザーはメッセージ ペイロードを妨げることなく、メッセージに関するメタ情報を追加できます。
ヘッダーを理解できないサーバーに接続したときにアプリケーションがヘッダー付きのメッセージを送信しようとすると、パブリッシュ呼び出しでエラーNATS_NO_SERVER_SUPPORT返されることに注意してください。
現在接続しているサーバーがヘッダーをサポートしているかどうかを確認する API があります。
natsStatus s = natsConnection_HasHeaderSupport ( conn );
if ( s == NATS_NO_SERVER_SUPPORT )
// deal with server not supporting this feature.サーバーがヘッダーを理解しているが、理解していないクライアントにメッセージを配信しようとしている場合、ヘッダーは取り除かれ、古いクライアントは引き続きメッセージを受信できます。アプリケーションがヘッダーに依存している場合は、すべてのクライアントとサーバーをヘッダーをサポートするバージョンにすることが重要です。
ヘッダー API の詳細については、 examples/getstarted/headers.cの例を入手してください。
*ワイルドカードは、サブジェクトの任意のレベルの任意のトークンに一致します。
natsConnection_Subscribe ( & sub , nc , "foo.*.baz" , onMsg , NULL );このサブスクライバは、次の宛先に送信されたメッセージを受信します。
ただし、次の場合はメッセージを受信しません。
>ワイルドカードは、サブジェクトの失敗の任意の長さに一致し、最後のトークンにのみ使用できます。
natsConnection_Subscribe ( & sub , nc , "foo.>" , onMsg , NULL );このサブスクライバは、次の宛先に送信されたメッセージを受信します。
ただし、以下に送信されたメッセージは受信できません。
この件名で公開すると、上記の 2 人の購読者が次のメッセージを受信します。
natsConnection_PublishString ( nc , "foo.bar.baz" , "got it?" );同じキュー名を持つすべてのサブスクリプションがキュー グループを形成します。各メッセージは、キュー セマティクスを使用して、キュー グループごとに 1 人のサブスクライバにのみ配信されます。キュー グループは必要な数だけ持つことができます。通常のサブスクライバーは引き続き期待どおりに動作します。
natsConnection_QueueSubscribe ( & sub , nc , "foo" , "job_workers" , onMsg , NULL );(これらの API が機能するには、ライブラリは TLS サポート (デフォルト) を使用してビルドする必要があることに注意してください。詳細については、TLS を使用するか使用しないでビルドする方法に関するビルドの章を参照してください。)
SSL/TLS 接続は、 natsOptionsを使用して構成されます。希望するセキュリティのレベルに応じて、 natsOptions_SetSecure()呼び出しで secure ブール値を true に設定するだけで済みます。
完全なセキュリティ (クライアントがサーバー証明書を検証し、サーバーがクライアント証明書を必要とする) を使用しても、セットアップに必要な呼び出しは数回だけです。
// Here is the minimum to create a TLS/SSL connection:
// Create an options object.
natsOptions_Create ( & opts );
// Set the secure flag.
natsOptions_SetSecure ( opts , true);
// You may not need this, but suppose that the server certificate
// is self-signed and you would normally provide the root CA, but
// don't want to. You can disable the server certificate verification
// like this:
natsOptions_SkipServerVerification ( opts , true);
// Connect now...
natsConnection_Connect ( & nc , opts );
// That's it! On success you will have a secure connection with the server!
(...)
// This example shows what it takes to have a full SSL configuration,
// including server expected's hostname, root CA, client certificates
// and specific ciphers to use.
// Create an options object.
natsOptions_Create ( & opts );
// Set the secure flag.
natsOptions_SetSecure ( opts , true);
// For a server with a trusted chain built into the client host,
// simply designate the server name that is expected. Without this
// call, the server certificate is still verified, but not the
// hostname.
natsOptions_SetExpectedHostname ( opts , "localhost" );
// Instead, if you are using a self-signed cert and need to load in the CA.
natsOptions_LoadCATrustedCertificates ( opts , caCertFileName );
// If the server requires client certificates, provide them along with the
// private key, all in one call.
natsOptions_LoadCertificatesChain ( opts , certChainFileName , privateKeyFileName );
// You can also specify preferred ciphers if you want.
natsOptions_SetCiphers ( opts , "-ALL:HIGH" );
// Then simply pass the options object to the connect call:
natsConnection_Connect ( & nc , opts );
// That's it! On success you will have a secure connection with the server! 
