nats.c
v3.9.2
عميل AC لنظام المراسلة NATS.
اذهب هنا للحصول على الوثائق عبر الإنترنت، وتحقق من الأسئلة المتداولة.
يعتمد تنفيذ عميل NATS هذا بشكل كبير على عميل NATS GO. يوجد دعم لأنظمة التشغيل Mac OS/X وLinux وWindows (على الرغم من عدم وجود مصفوفة دعم محددة للنظام الأساسي).
يتوفر العديد من مديري الحزم مع مكتبة عملاء NATS C. إذا كنت تعرف شخصًا غير موجود في هذه القائمة، فيرجى إرسال تقرير علاقات عامة لإضافته!
أولاً، قم بتنزيل الكود المصدري:
git clone [email protected]:nats-io/nats.c.git .
لبناء المكتبة، استخدم CMake. لاحظ أنه سيتم بشكل افتراضي إنشاء واجهة برمجة تطبيقات NATS Streaming API وإدراجها في مكتبة NATS. انظر أدناه إذا كنت لا ترغب في إنشاء واجهات برمجة التطبيقات ذات الصلة بالبث.
تأكد من إضافة CMake إلى المسار الخاص بك. في حالة البناء على Windows، افتح واجهة الأوامر من قائمة أدوات Visual Studio، وحدد واجهة الأوامر المناسبة (x64 أو x86 للإصدارات 64 أو 32 بت على التوالي). ربما ستحتاج أيضًا إلى تشغيل هذا بامتيازات المسؤول.
قم بإنشاء دليل 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 (أو استخدم -DNATS_NO_SPIN إذا كنت تقوم بالتجميع بدون CMake):
cmake .. -DNATS_BUILD_NO_SPIN=ON
إذا كنت قد أنشأت المكتبة مسبقًا، فقد تحتاج إلى إجراء make clean ، أو ببساطة حذف دليل البناء وإعادة إنشائه قبل تنفيذ أمر cmake.
للبناء على Windows، ستحتاج إلى تحديد منشئ البناء. على سبيل المثال، لتحديد nmake ، يمكنك تشغيل:
cmake .. -G "NMake Makefiles"
تشغيل cmake -h سيعطيك قائمة بالخيارات الممكنة وجميع أسماء المولدات.
وبدلاً من ذلك، يمكنك تشغيل إصدار واجهة المستخدم الرسومية. من نفس واجهة أوامر البناء ، ابدأ تشغيل واجهة المستخدم الرسومية:
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 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. بشكل افتراضي نستخدم 3.0+ واجهات برمجة التطبيقات. نظرًا لأن OpenSSL 1.0.2 لم يعد مدعومًا، بدءًا من الإصدار v3.6.0 من NATS C Client، فقد تم الآن تعيين متغير CMake NATS_BUILD_TLS_USE_OPENSSL_1_1_API على ON افتراضيًا (إذا كنت تقوم بإعداد بيئة جديدة) وسيستخدم واجهات برمجة تطبيقات OpenSSL من 1.1+ / 3.0+ واجهات برمجة التطبيقات. سيظل بإمكانك التجميع باستخدام مكتبة OpenSSL 1.0.2 عن طريق ضبط خيار CMake على OFF :
cmake .. -DNATS_BUILD_TLS_USE_OPENSSL_1_1_API=OFF
تم إهمال المتغير NATS_BUILD_TLS_USE_OPENSSL_1_1_API ، مما يعني أنه في المستقبل سيتم إزالة هذا الخيار ببساطة وسيتم استخدام OpenSSL 3.0+ APIs فقط. ستتم أيضًا إزالة التعليمات البرمجية الموجودة في المكتبة التي تستخدم واجهات برمجة تطبيقات OpenSSL الأقدم.
لاحظ أن المتغير NATS_BUILD_WITH_TLS_CLIENT_METHOD الذي تم إهماله في v2.0.0 قد تمت إزالته الآن.
نظرًا لأن عميل NATS C يرتبط ديناميكيًا بمكتبة OpenSSL، فأنت بحاجة إلى التأكد من أنك تقوم بعد ذلك بتشغيل التطبيق الخاص بك مقابل مكتبة OpenSSL 1.1+/3.0+.
إذا كنت تريد الارتباط بمكتبة OpenSSL الثابتة، فأنت بحاجة إلى حذف CMakeCache.txt وإعادة إنشائه باستخدام الخيار الإضافي:
rm CMakeCache.txt
cmake .. -DNATS_BUILD_OPENSSL_STATIC_LIBS=ON
ثم اتصل make (أو ما يعادله اعتمادًا على نظامك الأساسي) وهذا من شأنه أن يضمن أن المكتبة (والأمثلة و/أو مجموعة الاختبار القابلة للتنفيذ) مرتبطة بمكتبة OpenSSL، إذا تم العثور عليها بواسطة CMake.
عند إنشاء مكتبة تدعم البث، تستخدم مكتبة NATS مكتبة libprotobuf-c. عند تشغيل cmake لأول مرة (أو بعد إزالة CMakeCache.txt واستدعاء 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
يمكن دمج الاثنين إذا كان رأس التضمين موجودًا في دليل مختلف
# 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 ليتم تضمينها في مكتبة NATS:
cmake .. -DNATS_BUILD_STREAMING=OFF
عند استخدام ميزات أمان NATS 2.0 الجديدة، تحتاج المكتبة إلى التوقيع على بعض "nonce" التي يرسلها الخادم أثناء الاتصال أو إعادة الاتصال. نستخدم توقيع المفتاح العام Ed25519. تأتي المكتبة مع بعض التعليمات البرمجية لتنفيذ التوقيع. في معظم الحالات، سيكون الأمر جيدًا، ولكن إذا كان الأداء يمثل مشكلة (خاصة إذا كنت تخطط لاستخدام وظيفة natsConnection_Sign() كثيرًا)، فسيكون لديك خيار البناء باستخدام مكتبة Libsodium.
اتبع التعليمات حول كيفية تثبيت مكتبة libsodium هنا.
على نظام التشغيل macOS، يمكنك استخدام brew :
brew install libsodium
في نظام Linux، يمكنك استخدام apt-get
apt-get install libsodium-dev
بمجرد التثبيت، يمكنك إعادة إنشاء عميل NATS C عن طريق تمكين استخدام مكتبة libsodium أولاً:
cmake .. -DNATS_BUILD_USE_SODIUM=ON
إذا كانت لديك مكتبة libsodium مثبتة في موقع غير قياسي لا يمكن لـ CMake العثور عليه، فيمكنك تحديد موقع هذا الدليل:
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، سيتم set بدلاً من export .
عند تشغيل الاختبارات في الوضع المطول، يتيح لك متغير البيئة التالي رؤية مخرجات الخادم من داخل الاختبار نفسه. بدون هذا الخيار، يتم إسكات مخرجات الخادم:
export NATS_TEST_KEEP_SERVER_OUTPUT=yes
إذا كنت تريد تغيير الاسم القابل للتنفيذ للخادم الافتراضي ( nats-server.exe ) أو تحديد موقع معين، فاستخدم متغير البيئة هذا:
set NATS_TEST_SERVER_EXE=c:testnats-server.exe
تم توثيق واجهة برمجة التطبيقات العامة باستخدام Doxygen.
لإنشاء الوثائق، انتقل إلى دليل doc واكتب الأمر التالي:
doxygen DoxyFile.NATS.Client
إذا قمت بتبديل إنشاء Streaming APIs، ولم تعد الوثائق مطابقة لما يتم إنشاؤه، فيمكنك تحديث الوثائق عن طريق تبديل علامة البناء 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 وبالتالي يتوافق مع إصدار الخادم. لقد تم تقديم واجهات برمجة تطبيقات جديدة، ولكن التغيير الأكثر أهمية هو السلوك الافتراضي الجديد مع اتصالات TLS:
عند إنشاء اتصال آمن، يتم الآن التحقق دائمًا من اسم المضيف لشهادة الخادم، بغض النظر عما إذا كان المستخدم قد قام باستدعاء natsOptions_SetExpectedHostname() . قد يؤدي هذا إلى تعطيل التطبيقات التي كانت تستخدم عنوان IP على سبيل المثال للاتصال بخادم يحتوي على اسم المضيف فقط في الشهادة. يمكن حل هذه المشكلة عن طريق تغيير التطبيق الخاص بك لاستخدام اسم المضيف في عنوان URL أو الاستفادة من natsOptions_SetExpectedHostname() . إذا لم يكن ذلك ممكنًا، فيمكنك استعادة السلوك القديم عن طريق إنشاء المكتبة مع تعطيل السلوك الجديد. راجع #tls-support لمزيد من المعلومات.
يستخدم هذا المستودع ليشمل مكتبات libprotobuf-c المترجمة مسبقًا لأنظمة التشغيل macOS وLinux وWindows بالإضافة إلى ملفات الرأس (في دليل /pbuf ). لقد قمنا الآن بإزالة هذا الدليل ونطلب من المستخدم تثبيت مكتبة libprotobuf-c بشكل منفصل. راجع تعليمات البناء لتحديد موقع المكتبة إذا لم يتمكن CMake من العثور عليها مباشرة.
1.8.0natsConnStatus ببادئة NATS_CONN_STATUS_ . إذا كان تطبيقك لا يستخدم الإشارة إلى أي قيمة أصلية، مثل CONNECTED أو CLOSED ، وما إلى ذلك. فليس هناك ما تحتاج إلى القيام به. إذا قمت بذلك، فلديك خياران: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 Server v2.2.0+ ، على الرغم من أن الحصول على رموز الخطأ الخاصة بـ JetStream يتطلب وجود خادم بالإصدار v2.3.0+ . تتوفر بعض خيارات التكوين فقط بدءًا من v2.3.3 ، لذا نوصي باستخدام أحدث إصدار من NATS Server للحصول على تجربة أفضل.
انظر إلى الأمثلة المسماة js-xxx.c في دليل examples للحصول على أمثلة حول كيفية استخدام واجهة برمجة التطبيقات. يتم توثيق الكائنات وواجهات برمجة التطبيقات الجديدة بالكامل في الوثائق عبر الإنترنت.
// 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. الدلو عبارة عن دفق والمفاتيح هي موضوعات ضمن هذا الدفق.
تتطلب بعض الميزات v2.6.2 من NATS Server، لذا نوصي باستخدام أحدث إصدار من NATS Server للحصول على تجربة أفضل.
يتم توثيق الكائنات الجديدة وواجهات برمجة التطبيقات بالكامل في الوثائق عبر الإنترنت.
مثال لكيفية إنشاء متجر 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" );يمكن للمرء تحديث المفتاح إذا وفقط إذا كانت المراجعة الأخيرة في الخادم تطابق المراجعة التي تم تمريرها إلى واجهة برمجة التطبيقات هذه:
// 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 .
توجد واجهة برمجة تطبيقات لمعرفة ما إذا كان الخادم المتصل حاليًا يدعم الرؤوس:
natsStatus s = natsConnection_HasHeaderSupport ( conn );
if ( s == NATS_NO_SERVER_SUPPORT )
// deal with server not supporting this feature.إذا كان الخادم يفهم الرؤوس ولكنه على وشك تسليم الرسالة إلى عميل لا يفهمها، فسيتم تجريد الرؤوس حتى يتمكن العملاء الأقدم من تلقي الرسالة. من المهم أن يكون لدى جميع العملاء والخوادم إصدار يدعم الرؤوس إذا كانت التطبيقات تعتمد على الرؤوس.
لمزيد من التفاصيل حول واجهة برمجة تطبيقات الرؤوس، يرجى الحصول على المثال: examples/getstarted/headers.c .
يطابق حرف البدل * أي رمز مميز، على أي مستوى للموضوع:
natsConnection_Subscribe ( & sub , nc , "foo.*.baz" , onMsg , NULL );سيتلقى هذا المشترك الرسائل المرسلة إلى:
ومع ذلك، فإنه لن يتلقى رسائل على:
يطابق حرف البدل > أي طول لفشل الموضوع، ويمكن أن يكون فقط الرمز الأخير.
natsConnection_Subscribe ( & sub , nc , "foo.>" , onMsg , NULL );سيتلقى هذا المشترك أي رسالة يتم إرسالها إلى:
ومع ذلك، لن يتلقى الرسائل المرسلة على:
النشر في هذا الموضوع سيؤدي إلى وصول الرسالة للمشتركين أعلاه:
natsConnection_PublishString ( nc , "foo.bar.baz" , "got it?" );ستشكل كافة الاشتراكات التي تحمل نفس اسم قائمة الانتظار مجموعة قوائم انتظار. سيتم تسليم كل رسالة إلى مشترك واحد فقط لكل مجموعة قائمة انتظار، باستخدام دلالات قائمة الانتظار. يمكنك الحصول على أي عدد تريده من مجموعات الانتظار. سيستمر المشتركون العاديون في العمل كما هو متوقع.
natsConnection_QueueSubscribe ( & sub , nc , "foo" , "job_workers" , onMsg , NULL );(لاحظ أنه يجب إنشاء المكتبة بدعم TLS - وهو افتراضيًا - حتى تعمل واجهات برمجة التطبيقات هذه. راجع فصل الإنشاء حول كيفية الإنشاء باستخدام TLS أو بدونه لمزيد من التفاصيل).
يتم تكوين اتصال SSL/TLS من خلال استخدام natsOptions . اعتمادًا على مستوى الأمان الذي تريده، يمكن أن يكون الأمر بسيطًا مثل ضبط القيمة المنطقية الآمنة على true في استدعاء natsOptions_SetSecure() .
حتى مع وجود الأمان الكامل (التحقق من شهادة الخادم من قبل العميل، والخادم الذي يتطلب شهادات العميل)، فإن الإعداد لا يتضمن سوى عدد قليل من المكالمات.
// 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! 
