الاسم¶

BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - زوج BIO BIO

موجز¶

 #include <openssl/bio.h>
 const BIO_METHOD *BIO_s_bio(void);
 int BIO_make_bio_pair(BIO *b1, BIO *b2);
 int BIO_destroy_bio_pair(BIO *b);
 int BIO_shutdown_wr(BIO *b);
 int BIO_set_write_buf_size(BIO *b, long size);
 size_t BIO_get_write_buf_size(BIO *b, long size);
 int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
 int BIO_get_write_guarantee(BIO *b);
 size_t BIO_ctrl_get_write_guarantee(BIO *b);
 int BIO_get_read_request(BIO *b);
 size_t BIO_ctrl_get_read_request(BIO *b);
 int BIO_ctrl_reset_read_request(BIO *b);

الوصف¶

BIO_s_bio() تُرجع الطريقة لزوج BIO. زوج BIO هو زوج من BIOs مصدر/مصرف حيث البيانات المكتوبة إلى أي نصف من الزوج تُخزن مؤقتًا ويمكن قراءتها من النصف الآخر. كلا النصفين يجب عادةً أن يُعالجا بواسطة نفس خيط التطبيق حيث لا يُجرى أي قفل على هياكل البيانات الداخلية.

بما أن سلاسل BIO تنتهي عادةً في BIO مصدر/مصرف، فمن الممكن جعل هذا نصفًا من زوج BIO وجميع البيانات تُعالج بواسطة السلسلة تحت سيطرة التطبيق.

أحد الاستخدامات النمطية لأزواج BIO هو وضع إدخال/إخراج TLS/SSL تحت سيطرة التطبيق، يمكن استخدام هذا عندما يرغب التطبيق في استخدام ناقل غير قياسي لـ TLS/SSL أو عندما تكون إجراءات المقبس العادية غير مناسبة.

استدعاءات BIO_read_ex() ستقرأ البيانات من الخبيئة أو تطلب إعادة محاولة إذا لم تكن البيانات متاحة.

استدعاءات BIO_write_ex() ستضع البيانات في الخبيئة أو تطلب إعادة محاولة إذا كانت الخبيئة ممتلئة.

الاستدعاءات القياسية BIO_ctrl_pending() و BIO_ctrl_wpending() يمكن استخدامها لتحديد كمية البيانات المعلقة في خبيئة القراءة أو الكتابة.

BIO_reset() تمسح أي بيانات في خبيئة الكتابة.

BIO_make_bio_pair() تصل اثنين من BIOs منفصلين في زوج متصل.

BIO_destroy_pair() تدمر الارتباط بين اثنين من BIOs متصلين. تحرير أي نصف من الزوج سيدمر الارتباط آليًا.

BIO_shutdown_wr() تُستخدم لإغلاق BIO b. بعد هذا الاستدعاء لا يُسمح بمزيد من الكتابات على BIO b (ستُرجع خطأ). القراءات على النصف الآخر من الزوج سترجع أي بيانات معلقة أو EOF عندما تُقرأ جميع البيانات المعلقة.

BIO_set_write_buf_size() تضبط حجم خبيئة الكتابة لـ BIO b إلى size. إذا لم يُهيأ الحجم، يُستخدم قيمة مبدئية. هذا حاليًا 17K، كافٍ لسجل TLS بأقصى حجم.

BIO_get_write_buf_size() تُرجع حجم خبيئة الكتابة.

BIO_new_bio_pair() تجمع الاستدعاءات إلى BIO_new() و BIO_make_bio_pair() و BIO_set_write_buf_size() لإنشاء زوج متصل من BIOs bio1 و bio2 بأحجام خبيئة كتابة writebuf1 و writebuf2. إذا كان أي من الحجمين صفرًا، يُستخدم الحجم المبدئي. BIO_new_bio_pair() لا تتحقق مما إذا كان bio1 أو bio2 يشيران إلى BIO آخر، القيم تُستبدل، BIO_free() لا تُستدعى.

BIO_get_write_guarantee() و BIO_ctrl_get_write_guarantee() تُرجعان الطول الأقصى للبيانات التي يمكن كتابتها حاليًا إلى BIO. الكتابات الأكبر من هذه القيمة سترجع قيمة من BIO_write_ex() أقل من الكمية المطلوبة أو إذا كانت الخبيئة ممتلئة تطلب إعادة محاولة. BIO_ctrl_get_write_guarantee() هي دالة بينما BIO_get_write_guarantee() هي ماكرو.

BIO_get_read_request() و BIO_ctrl_get_read_request() تُرجعان كمية البيانات المطلوبة، أو حجم الخبيئة إذا كان أقل، إذا فشلت آخر محاولة قراءة في النصف الآخر من زوج BIO بسبب خبيئة فارغة. يمكن استخدام هذا لتحديد كمية البيانات التي يجب كتابتها في BIO بحيث تنجح القراءة التالية: هذا مفيد جدًا في تطبيقات TLS/SSL حيث تكون كمية البيانات المقروءة ذات معنى عادةً بدلاً من مجرد حجم خبيئة. بعد قراءة ناجحة، سترجع هذه الدالة صفرًا. كما سترجع صفرًا بمجرد كتابة بيانات جديدة تلبي طلب القراءة أو جزءًا منه. لاحظ أن BIO_get_read_request() لا تُرجع أبدًا كمية أكبر من تلك التي تُرجعها BIO_get_write_guarantee().

BIO_ctrl_reset_read_request() يمكن استخدامها أيضًا لإعادة تعيين القيمة التي تُرجعها BIO_get_read_request() إلى صفر.

ملاحظات¶

يجب تحرير كلا نصفي زوج BIO. أي حتى إذا تم تحرير نصف ضمنيًا بسبب استدعاء BIO_free_all() أو SSL_free()، فإن النصف الآخر يحتاج إلى التحرير.

عند الاستخدام في تطبيقات ثنائية الاتجاه (مثل TLS/SSL)، يجب توخي الحذر لتفريغ أي بيانات في مخزن الكتابة المؤقت. يمكن فعل ذلك باستدعاء BIO_pending() على النصف الآخر من الزوج، وإذا كانت أي بيانات معلقة، فقراءتها وإرسالها إلى النقل الأساسي. يجب فعل ذلك قبل أي معالجة عادية (مثل استدعاء select()) بسبب طلب وكون BIO_should_read() صحيحًا.

لرؤية لماذا هذا مهم، اعتبر حالة حيث يُرسل طلب باستخدام BIO_write_ex() وتُقرأ استجابة باستخدام BIO_read_ex()، يمكن أن يحدث هذا أثناء مصافحة TLS/SSL على سبيل المثال. BIO_write_ex() ستنجح وتضع البيانات في مخزن الكتابة المؤقت. BIO_read_ex() ستفشل في البداية و BIO_should_read() سيكون صحيحًا. إذا انتظر التطبيق بعد ذلك توفر البيانات على النقل الأساسي قبل تفريغ مخزن الكتابة المؤقت، فلن ينجح أبدًا لأن الطلب لم يُرسل!

BIO_eof() صحيح إذا لم تكن هناك بيانات في BIO النظير وتم إيقاف تشغيل BIO النظير.

BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), BIO_set_write_buf_size(), BIO_get_write_buf_size(), BIO_get_write_guarantee(), و BIO_get_read_request() مُنفذة كوحدات ماكرو.

القيم المُرجعة¶

BIO_new_bio_pair() تُرجع 1 عند النجاح، مع توفر BIOs الجديدة في bio1 و bio2، أو 0 عند الفشل، مع تخزين مؤشرات NULL في المواقع الخاصة بـ bio1 و bio2. افحص مكدس الأخطاء لمزيد من المعلومات.

[XXXXX: يجب إضافة المزيد من قيم الإرجاع هنا]

أمثلة¶

يمكن استخدام زوج BIO للحصول على تحكم كامل في الوصول إلى الشبكة لتطبيق. يمكن للتطبيق استدعاء select() على المقبس حسب الحاجة دون الحاجة إلى المرور عبر واجهة SSL.

 BIO *internal_bio, *network_bio;
 ...
 BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
 SSL_set_bio(ssl, internal_bio, internal_bio);
 SSL_operations(); /* e.g. SSL_read and SSL_write */
 ...
 application |   TLS-engine
    |        |
    +----------> SSL_operations()
             |     /\    ||
             |     ||    \/
             |   BIO-pair (internal_bio)
             |   BIO-pair (network_bio)
             |     ||     /\
             |     \/     ||
    +-----------< BIO_operations()
    |        |
    |        |
   socket
  ...
  SSL_free(ssl);                /* implicitly frees internal_bio */
  BIO_free(network_bio);
  ...

بما أن زوج BIO سيخزن البيانات مؤقتًا فقط ولن يصل إلى الاتصال مباشرة أبدًا، فإنه يتصرف بشكل غير محظور وسيعود بمجرد امتلاء مخزن الكتابة المؤقت أو استنزاف مخزن القراءة. ثم يجب على التطبيق تفريغ مخزن الكتابة المؤقت و/أو ملء مخزن القراءة.

استخدم BIO_ctrl_pending() لمعرفة ما إذا كانت البيانات مخزنة مؤقتًا في BIO ويجب نقلها إلى الشبكة. استخدم BIO_ctrl_get_read_request() لمعرفة عدد البايتات التي يجب كتابتها في المخزن قبل أن يمكن متابعة SSL_operation() بنجاح.

تحذيرات¶

بما أن البيانات مخزنة مؤقتًا، قد تُرجع SSL_operation() بحالة ERROR_SSL_WANT_READ، ولكن لا تزال هناك بيانات في مخزن الكتابة المؤقت. يجب ألا يعتمد التطبيق على قيمة الخطأ لـ SSL_operation() بل يجب أن يضمن تفريغ مخزن الكتابة المؤقت أولاً دائمًا. وإلا قد يحدث توقف تام لأن النظير قد ينتظر البيانات قبل أن يتمكن من المتابعة.

انظر أيضًا¶

SSL_set_bio(3), ssl(7), bio(7), BIO_should_retry(3), BIO_read_ex(3)

حقوق النسخ¶

حقوق النشر 2000-2020 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“). لا يجوز لك استخدام هذا الملف إلا وفقًا لشروط الرخصة. يمكنك الحصول على نسخة منها في الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط <https://www.openssl.org/source/license.html>.

ترجمة¶

تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.