nats.c
v3.9.2
Klien AC untuk sistem pesan NATS.
Buka di sini untuk dokumentasi online, dan periksa pertanyaan umum.
Implementasi Klien NATS ini sebagian besar didasarkan pada Klien NATS GO. Ada dukungan untuk Mac OS/X, Linux dan Windows (walaupun kami tidak memiliki matriks dukungan platform khusus).
Ada beberapa manajer paket dengan perpustakaan klien NATS C yang tersedia. Jika Anda mengetahui salah satu yang tidak ada dalam daftar ini, silakan kirimkan PR untuk menambahkannya!
Pertama, unduh kode sumbernya:
git clone [email protected]:nats-io/nats.c.git .
Untuk membangun perpustakaan, gunakan CMake. Perhatikan bahwa secara default NATS Streaming API akan dibuat dan disertakan dalam perpustakaan NATS. Lihat di bawah jika Anda tidak ingin membuat API terkait Streaming.
Pastikan CMake ditambahkan ke jalur Anda. Jika dibangun di Windows, buka shell perintah dari menu Alat Visual Studio, dan pilih shell perintah yang sesuai (x64 atau x86 masing-masing untuk build 64 atau 32 bit). Anda juga mungkin perlu menjalankan ini dengan hak administrator.
Buat direktori build (nama apa pun bisa digunakan) dari pohon sumber root, dan cd ke dalamnya. Kemudian keluarkan perintah ini untuk pertama kalinya:
cmake ..
Di beberapa arsitektur, Anda mungkin mengalami kesalahan kompilasi untuk mutex.co karena tidak ada dukungan untuk instruksi assembler yang kami gunakan untuk menghasilkan saat memutar mencoba mendapatkan kunci.
Anda mungkin mendapatkan kesalahan build seperti ini:
/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
Jika demikian, Anda dapat mengatasinya dengan mengaktifkan flag NATS_BUILD_NO_SPIN (atau menggunakan -DNATS_NO_SPIN jika Anda mengkompilasi tanpa CMake):
cmake .. -DNATS_BUILD_NO_SPIN=ON
Jika sebelumnya Anda telah membuat perpustakaan, Anda mungkin perlu melakukan make clean , atau cukup menghapus dan membuat ulang direktori build sebelum menjalankan perintah cmake.
Untuk membangun di Windows, Anda harus memilih generator build. Misalnya, untuk memilih nmake , Anda akan menjalankan:
cmake .. -G "NMake Makefiles"
Menjalankan cmake -h akan memberi Anda daftar opsi yang memungkinkan dan semua nama generator.
Alternatifnya, Anda dapat menjalankan versi GUI. Dari shell perintah build yang sama, mulai GUI:
c:program files (x86)CMakebincmake-gui.exe
Jika Anda memulai dengan direktori build yang kosong, Anda harus memilih sumber dan direktori build, lalu klik Configure . Di sini, Anda dapat memilih dari kotak drop-down nama generator build. Setelah selesai, klik Generate . Kemudian Anda dapat kembali ke shell perintah Anda, atau Visual Studio dan membangun.
Untuk mengubah beberapa opsi build, Anda perlu mengedit cache dan membangun kembali.
make edit_cache
Perhatikan bahwa jika Anda membangun di Windows dan telah memilih "NMake Makefiles", ganti semua referensi berikut ke make dengan nmake .
Mengedit cache memungkinkan Anda memilih jenis build (Debug, Rilis, dll), arsitektur (64 atau 32bit), dan seterusnya.
Target defaultnya akan membangun semuanya, yaitu pustaka NATS statis dan bersama serta contoh dan program pengujian. Masing-masing terletak di direktori masing-masing di bawah direktori build Anda: src , examples dan test .
make install
Akan menyalin perpustakaan statis dan bersama di folder install/lib dan header publik di install/include .
Secara default, perpustakaan dibangun dengan dukungan TLS. Anda dapat menonaktifkan ini dari cmake gui make edit_cache dan mengalihkan opsi NATS_BUILD_WITH_TLS ke OFF , atau meneruskan opsi langsung ke perintah cmake :
cmake .. -DNATS_BUILD_WITH_TLS=OFF
Mulai 2.0.0 , ketika membangun dengan dukungan TLS/SSL, nama host yang diharapkan dari sertifikat server selalu diverifikasi. Artinya, nama host yang diberikan di URL atau melalui opsi natsOptions_SetExpectedHostname() akan digunakan untuk memeriksa nama host yang ada di sertifikat. Sebelum 2.0.0 , nama host akan diverifikasi hanya jika opsi natsOptions_SetExpectedHostname() dipanggil.
Meskipun kami menyarankan untuk membiarkan perilaku default baru, Anda dapat memulihkan perilaku sebelumnya dengan membangun perpustakaan dengan menonaktifkan opsi ini:
cmake .. -DNATS_BUILD_TLS_FORCE_HOST_VERIFY=OFF
Klien NATS C dibuat menggunakan API dari perpustakaan OpenSSL. Secara default kami menggunakan API 3.0+ . Karena OpenSSL 1.0.2 tidak lagi didukung, dimulai dengan versi NATS C Client v3.6.0 , variabel CMake NATS_BUILD_TLS_USE_OPENSSL_1_1_API kini disetel ke ON secara default (jika Anda menyiapkan lingkungan baru) dan akan menggunakan API OpenSSL dari 1.1+ / 3.0+ API. Anda masih dapat mengkompilasi dengan pustaka OpenSSL 1.0.2 dengan mengatur opsi CMake ini ke OFF :
cmake .. -DNATS_BUILD_TLS_USE_OPENSSL_1_1_API=OFF
Variabel NATS_BUILD_TLS_USE_OPENSSL_1_1_API tidak digunakan lagi, artinya di masa mendatang opsi ini akan dihapus begitu saja dan hanya OpenSSL 3.0+ API yang akan digunakan. Kode di perpustakaan yang menggunakan API OpenSSL lama juga akan dihapus.
Perhatikan bahwa variabel NATS_BUILD_WITH_TLS_CLIENT_METHOD yang tidak digunakan lagi di v2.0.0 kini telah dihapus.
Karena klien NATS C secara dinamis tertaut ke pustaka OpenSSL, Anda perlu memastikan bahwa Anda kemudian menjalankan aplikasi Anda pada pustaka OpenSSL 1.1+/3.0+.
Jika Anda ingin menautkan ke perpustakaan OpenSSL statis, Anda perlu menghapus CMakeCache.txt dan membuatnya kembali dengan opsi tambahan:
rm CMakeCache.txt
cmake .. -DNATS_BUILD_OPENSSL_STATIC_LIBS=ON
Kemudian panggil make (atau yang setara tergantung pada platform Anda) dan ini akan memastikan bahwa perpustakaan (dan contoh dan/atau rangkaian pengujian yang dapat dieksekusi) ditautkan dengan perpustakaan OpenSSL, jika ditemukan oleh CMake.
Saat membangun perpustakaan dengan dukungan Streaming, perpustakaan NATS menggunakan perpustakaan libprotobuf-c. Saat cmake dijalankan untuk pertama kalinya (atau setelah menghapus CMakeCache.txt dan memanggil cmake .. lagi), ia mencari perpustakaan libprotobuf-c. Jika tidak menemukannya, pesan akan dicetak dan proses build gagal. CMake mencari perpustakaan di direktori tempat perpustakaan biasanya ditemukan. Namun, jika Anda ingin menentukan direktori tertentu tempat perpustakaan berada, Anda perlu melakukan ini:
cmake .. -DNATS_PROTOBUF_DIR=
Perpustakaan statis akan digunakan secara default. Jika Anda ingin mengubahnya, atau jika perpustakaan tidak memiliki nama yang diharapkan, Anda perlu melakukan ini:
# Use the library named mylibproto.so located at /my/location
cmake .. -DNATS_PROTOBUF_LIBRARY=/my/location/mylibproto.so
Keduanya dapat digabungkan jika header penyertaan terletak di direktori berbeda
# 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
Jika Anda tidak ingin membuat API Streaming NATS untuk disertakan dalam perpustakaan NATS:
cmake .. -DNATS_BUILD_STREAMING=OFF
Saat menggunakan fitur keamanan NATS 2.0 yang baru, perpustakaan perlu menandatangani beberapa "nonce" yang dikirim oleh server selama koneksi atau koneksi ulang. Kami menggunakan tanda tangan kunci publik Ed25519. Perpustakaan dilengkapi dengan beberapa kode untuk melakukan tanda tangan. Dalam kebanyakan kasus, ini akan baik-baik saja, tetapi jika kinerja menjadi masalah (terutama jika Anda berencana untuk sering menggunakan fungsi natsConnection_Sign() ), Anda akan memiliki opsi untuk membangun dengan perpustakaan Libsodium.
Ikuti petunjuk tentang cara menginstal perpustakaan libsodium di sini.
Di macOS, Anda dapat menggunakan brew :
brew install libsodium
Di Linux, Anda bisa menggunakan apt-get
apt-get install libsodium-dev
Setelah terinstal, Anda dapat membangun kembali klien NATS C dengan terlebih dahulu mengaktifkan penggunaan perpustakaan libsodium:
cmake .. -DNATS_BUILD_USE_SODIUM=ON
Jika Anda menginstal perpustakaan libsodium di lokasi non standar yang tidak dapat ditemukan CMake, Anda dapat menentukan lokasi direktori ini:
cmake .. -DNATS_BUILD_USE_SODIUM=ON -DNATS_SODIUM_DIR=/my/path/to/libsodium
Pada platform di mana valgrind tersedia, Anda dapat menjalankan pengujian dengan pemeriksaan memori. Berikut ini contohnya:
make test ARGS="-T memcheck"
Atau, Anda dapat langsung menjalankan program ctest :
ctest -T memcheck -V -I 1,4
Perintah di atas akan menjalankan pengujian dengan valgrind ( -T memcheck ), dengan keluaran verbose ( -V ), dan menjalankan pengujian dari 1 hingga 4 ( -I 1,4 ).
Jika Anda menambahkan tes ke test/test.c , Anda perlu menambahkannya ke dalam file list_test.txt . Setiap entri hanya berisi nama pengujian, fungsinya harus diberi nama yang sama, dengan awalan test_ . Daftarnya disusun berdasarkan abjad, tetapi tidak perlu, Anda dapat menambahkannya di mana saja.
Jika Anda menambahkan tolok ukur, tolok ukur tersebut harus ditambahkan ke list_bench.txt . Tes ini diberi label berbeda ( -L 'bench' ) dan dijalankan secara terpisah di CI.
Anda perlu menjalankan kembali cmake agar perubahan diterapkan:
cmake ..
-- Configuring done
-- Generating done
-- Build files have been written to: /home/ivan/nats.c/build
Anda dapat menggunakan variabel lingkungan berikut untuk memengaruhi perilaku testsuite.
Saat dijalankan dengan pemeriksaan memori, perubahan waktu dan kinerja keseluruhan menjadi lebih lambat. Variabel berikut memungkinkan testsuite menyesuaikan beberapa nilai yang digunakan selama pengujian:
export NATS_TEST_VALGRIND=yes
Di Windows, ini akan set bukan export .
Saat menjalankan pengujian dalam mode verbose, variabel lingkungan berikut memungkinkan Anda melihat output server dari dalam pengujian itu sendiri. Tanpa opsi ini, keluaran server akan dibungkam:
export NATS_TEST_KEEP_SERVER_OUTPUT=yes
Jika Anda ingin mengubah nama server default yang dapat dieksekusi ( nats-server.exe ) atau menentukan lokasi tertentu, gunakan variabel lingkungan ini:
set NATS_TEST_SERVER_EXE=c:testnats-server.exe
API publik telah didokumentasikan menggunakan Doxygen.
Untuk menghasilkan dokumentasi, buka direktori doc dan ketik perintah berikut:
doxygen DoxyFile.NATS.Client
Jika Anda mengganti versi API Streaming, dan dokumentasinya tidak lagi cocok dengan apa yang sedang dibuat, Anda dapat memperbarui dokumentasi dengan mengganti tanda versi NATS_UPDATE_DOC dan membuat ulang dokumentasi.
Dari direktori build:
cmake .. -DNATS_UPDATE_DOC=ON
make
cd /doc
doxygen DoxyFile.NATS.Client
Dokumentasi yang dihasilkan akan ditempatkan di direktori html . Untuk melihat dokumentasinya, arahkan browser Anda ke file index.html di direktori tersebut.
Buka di sini untuk dokumentasi online.
Kode sumbernya juga cukup terdokumentasi.
Bagian ini mencantumkan perubahan penting seperti pemberitahuan penghentian, dll...
2.0.0 Versi ini memperkenalkan konsep keamanan yang digunakan oleh NATS Server 2.0.0 dan karenanya selaras dengan versi server. Ada API baru yang diperkenalkan, namun perubahan paling penting adalah perilaku default baru dengan koneksi TLS:
Saat membuat sambungan aman, nama host sertifikat server kini selalu diverifikasi, terlepas dari apakah pengguna telah memanggil natsOptions_SetExpectedHostname() . Hal ini dapat merusak aplikasi yang misalnya menggunakan IP untuk menyambung ke server yang hanya memiliki nama host di sertifikatnya. Hal ini dapat diatasi dengan mengubah aplikasi Anda untuk menggunakan nama host di URL atau menggunakan natsOptions_SetExpectedHostname() . Jika hal ini tidak memungkinkan, Anda dapat memulihkan perilaku lama dengan membangun perpustakaan dengan menonaktifkan perilaku baru. Lihat #tls-support untuk informasi lebih lanjut.
Repositori ini digunakan untuk menyertakan perpustakaan libprotobuf-c yang telah dikompilasi untuk macOS, Linux dan Windows bersama dengan file header (di direktori /pbuf ). Kami sekarang telah menghapus direktori ini dan mengharuskan pengguna menginstal perpustakaan libprotobuf-c secara terpisah. Lihat petunjuk pembangunan untuk menentukan lokasi perpustakaan jika CMake tidak dapat menemukannya secara langsung.
1.8.0natsConnStatus telah diawali dengan NATS_CONN_STATUS_ . Jika aplikasi Anda tidak menggunakan referensi nilai asli apa pun, seperti CONNECTED atau CLOSED , dll.. maka Anda tidak perlu melakukan apa pun. Jika ya, Anda memiliki dua opsi:NATS_BUILD_NO_PREFIX_CONNSTS . Ini dapat dilakukan dengan cara ini dari direktori build: cmake .. -DNATS_BUILD_NO_PREFIX_CONNSTS=ON Direktori examples/getstarted memiliki serangkaian contoh sederhana yang berfungsi penuh, namun sangat sederhana. Tujuannya adalah untuk menunjukkan betapa mudahnya menggunakan API.
Kumpulan contoh yang lebih kompleks ada di direktori examples/ dan juga dapat digunakan untuk membuat tolok ukur pustaka klien.
Perhatikan bahwa untuk kesederhanaan, pemeriksaan kesalahan tidak dilakukan di sini.
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 );
} Dukungan untuk JetStream dimulai dengan perpustakaan versi v3.0.0 dan NATS Server v2.2.0+ , meskipun untuk mendapatkan kode kesalahan spesifik JetStream memerlukan server pada versi v2.3.0+ . Beberapa opsi konfigurasi hanya tersedia mulai v2.3.3 , jadi kami menyarankan Anda menggunakan rilis Server NATS terbaru untuk mendapatkan pengalaman yang lebih baik.
Lihat contoh bernama js-xxx.c di direktori examples untuk contoh cara menggunakan API. Objek dan API baru didokumentasikan secara lengkap dalam dokumentasi online.
// 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 );FITUR EKSPERIMENTAL! Kami berhak mengubah API tanpa harus mengubah versi utama perpustakaan.
Penyimpanan KeyValue adalah tampilan terwujud berdasarkan JetStream. Bucket adalah aliran dan kunci adalah subjek dalam aliran tersebut.
Beberapa fitur memerlukan NATS Server v2.6.2 , jadi kami menyarankan Anda menggunakan rilis NATS Server terbaru untuk mendapatkan pengalaman yang lebih baik.
Objek dan API baru didokumentasikan secara lengkap dalam dokumentasi online.
Contoh cara membuat penyimpanan 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 );Ini menunjukkan cara "mengikat" ke yang sudah ada:
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 );Ini adalah cara menghapus penyimpanan KeyValue di server:
jsCtx * js = NULL ;
// Assume we got a JetStream context in `js`...
s = js_DeleteKeyValue ( js , "KVS" );Ini adalah cara memberi nilai pada kunci tertentu:
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" );Cara di atas menempatkan nilai untuk kunci tertentu, tetapi jika seseorang ingin memastikan bahwa nilai ditempatkan untuk kunci tersebut hanya jika kunci tersebut belum pernah ada sebelumnya, maka ia akan memanggil:
// Same note than before: if "rev" is not needed, pass NULL:
s = kvStore_CreateString ( & rev , kv , "MY_KEY" , "my value" );Seseorang dapat memperbarui kunci jika dan hanya jika revisi terakhir di server cocok dengan yang diteruskan ke API ini:
// 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 );Ini cara mendapatkan kuncinya:
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 );Ini adalah cara membersihkan kunci:
kvStore * kv = NULL ;
// Assume we got a kvStore...
s = kvStore_Purge ( kv , "MY_KEY" );Ini akan menghapus kunci di server:
kvStore * kv = NULL ;
// Assume we got a kvStore...
s = kvStore_Delete ( kv , "MY_KEY" );Untuk membuat "pengamat" untuk kunci tertentu:
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 );Untuk mendapatkan riwayat kunci:
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 );Beginilah cara Anda mendapatkan kunci ember:
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 );Header tersedia saat menyambung ke server pada versi 2.2.0+.
Mereka sangat mirip dengan header http. Mereka adalah peta pasangan kunci/nilai, nilainya berupa array string.
Header memungkinkan pengguna untuk menambahkan informasi meta tentang pesan tanpa mengganggu muatan pesan.
Perhatikan bahwa jika aplikasi mencoba mengirim pesan dengan header saat terhubung ke server yang tidak memahaminya, panggilan publikasikan akan mengembalikan kesalahan NATS_NO_SERVER_SUPPORT .
Ada API untuk mengetahui apakah server yang saat ini terhubung mendukung header:
natsStatus s = natsConnection_HasHeaderSupport ( conn );
if ( s == NATS_NO_SERVER_SUPPORT )
// deal with server not supporting this feature.Jika server memahami header tetapi hendak menyampaikan pesan ke klien yang tidak memahaminya, header akan dihapus sehingga klien lama masih dapat menerima pesan tersebut. Penting untuk memiliki semua klien dan server ke versi yang mendukung header jika aplikasi mengandalkan header.
Untuk detail lebih lanjut tentang API headers, silakan dapatkan contoh: examples/getstarted/headers.c .
Wildcard * cocok dengan token apa pun, pada tingkat subjek mana pun:
natsConnection_Subscribe ( & sub , nc , "foo.*.baz" , onMsg , NULL );Pelanggan ini akan menerima pesan yang dikirim ke:
Namun, ia tidak akan menerima pesan tentang:
Wildcard > cocok dengan panjang subjek yang gagal, dan hanya dapat menjadi token terakhir.
natsConnection_Subscribe ( & sub , nc , "foo.>" , onMsg , NULL );Pelanggan ini akan menerima pesan apa pun yang dikirim ke:
Namun, ia tidak akan menerima pesan yang dikirim pada:
Penerbitan mengenai hal ini akan menyebabkan dua pelanggan di atas menerima pesan:
natsConnection_PublishString ( nc , "foo.bar.baz" , "got it?" );Semua langganan dengan nama antrian yang sama akan membentuk grup antrian. Setiap pesan akan dikirimkan hanya ke satu pelanggan per grup antrian, menggunakan semantik antrian. Anda dapat memiliki grup antrean sebanyak yang Anda inginkan. Pelanggan normal akan terus bekerja seperti yang diharapkan.
natsConnection_QueueSubscribe ( & sub , nc , "foo" , "job_workers" , onMsg , NULL );(Perhatikan bahwa perpustakaan perlu dibangun dengan dukungan TLS - yang merupakan default - agar API ini dapat berfungsi. Lihat bab Build tentang cara membangun dengan atau tanpa TLS untuk detail selengkapnya).
Koneksi SSL/TLS dikonfigurasi melalui penggunaan natsOptions . Tergantung pada tingkat keamanan yang Anda inginkan, hal ini bisa dilakukan dengan cara sederhana, seperti mengatur boolean aman ke true pada panggilan natsOptions_SetSecure() .
Bahkan dengan keamanan penuh (klien memverifikasi sertifikat server, dan server memerlukan sertifikat klien), pengaturan hanya melibatkan beberapa panggilan.
// 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! 
