BIO_SHOULD_RETRY(3ssl)

الاسم
BIO_should_read, BIO_should_write, BIO_should_io_special, BIO_retry_type, BIO_should_retry, BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - دوال إعادة المحاولة لـ BIO

موجز
 #include <openssl/bio.h>

 int BIO_should_read(BIO *b);
 int BIO_should_write(BIO *b);
 int BIO_should_io_special(iBIO *b);
 int BIO_retry_type(BIO *b);
 int BIO_should_retry(BIO *b);

 BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
 int BIO_get_retry_reason(BIO *bio);
 void BIO_set_retry_reason(BIO *bio, int reason);

الوصف
تحدد هذه الدوال سبب عدم قدرة BIO على قراءة أو كتابة البيانات. تُستدعى عادةً بعد استدعاء فاشل لـ BIO_read_ex() أو BIO_write_ex().

BIO_should_retry() صحيحة إذا كان الاستدعاء الذي أنتج هذه الحالة يجب إعادة محاولته لاحقًا.

إذا كانت BIO_should_retry() خاطئة، فالسبب هو حالة خطأ.

BIO_should_read() صحيحة إذا كان سبب الحالة هو أن BIO لا تملك بيانات كافية للإرجاع. تحقق من قابلية القراءة و/أو أعد محاولة آخر عملية.

BIO_should_write() صحيحة إذا كان سبب الحالة هو أن BIO لديها بيانات معلقة للكتابة. تحقق من قابلية الكتابة و/أو أعد محاولة آخر عملية.

BIO_should_io_special() صحيحة إذا كانت حالة "خاصة" ما، أي سبب غير القراءة أو الكتابة، هي سبب الحالة.

BIO_retry_type() تُرجع قناعًا لسبب حالة إعادة المحاولة مكونًا من القيم BIO_FLAGS_READ و BIO_FLAGS_WRITE و BIO_FLAGS_IO_SPECIAL، رغم أن أنواع BIO الحالية ستضبط واحدًا منها فقط.

BIO_get_retry_BIO() تحدد السبب الدقيق للحالة الخاصة، وتُعيد BIO التي تسببت في هذه الحالة، وإذا كان reason ليس NULL، فسيحتوي على رمز السبب. يعتمد معنى رمز السبب والإجراء الذي يجب اتخاذه على نوع BIO الذي أدى إلى هذه الحالة.

BIO_get_retry_reason() تُعيد سبب الحالة الخاصة إذا مُررت BIO ذات الصلة، مثلًا كما تُعاد بواسطة BIO_get_retry_BIO().

BIO_set_retry_reason() تضبط سبب إعادة المحاولة لحالة خاصة لـ BIO معينة. يُستدعى هذا عادةً فقط بواسطة تطبيقات BIO.

ملاحظات
BIO_should_read() و BIO_should_write() و BIO_should_io_special() و BIO_retry_type() و BIO_should_retry()، كلها مُطبقة كوحدات ماكرو.

إذا أعادت BIO_should_retry() قيمة خاطئة، فإن "حالة الخطأ" الدقيقة تعتمد على نوع BIO الذي تسبب فيها ورمز إرجاع عملية BIO. مثلًا، إذا أعاد استدعاء BIO_read_ex() على BIO مقبس 0 وكانت BIO_should_retry() خاطئة، فالسبب هو أن الاتصال أُغلق. حالة مماثلة على BIO ملف تعني أنها وصلت إلى نهاية الملف. قد تضع بعض أنواع BIO معلومات إضافية في قائمة انتظار الأخطاء. لمزيد من التفاصيل، انظر صفحات الدليل الخاصة بكل نوع BIO.

إذا كان هيكل الإدخال/الإخراج الأساسي في وضع الحظر، فلن تطلب جميع أنواع BIO الحالية تقريبًا إعادة محاولة، لأن استدعاءات الإدخال/الإخراج الأساسية لن تفعل. إذا علم التطبيق أن نوع BIO لن يشير أبدًا إلى إعادة محاولة، فلا حاجة لاستدعاء BIO_should_retry() بعد استدعاء إدخال/إخراج BIO فاشل. يُفعل هذا عادةً مع BIOs الملف.

BIOs SSL هي الاستثناء الوحيد حاليًا لهذه القاعدة: يمكنها طلب إعادة محاولة حتى إذا كان هيكل الإدخال/الإخراج الأساسي يحظر، إذا حدثت مصافحة أثناء استدعاء BIO_read(). يمكن للتطبيق إعادة محاولة الاستدعاء الفاشل فورًا أو تجنب هذه الحالة بضبط SSL_MODE_AUTO_RETRY على هيكل SSL الأساسي.

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

على سبيل المثال، إذا كان السبب في النهاية مقبساً وكان BIO_should_read() صحيحاً، فقد يُجرى استدعاء لـ select() للانتظار حتى تصبح البيانات متاحة ثم إعادة محاولة عملية BIO. بدمج شروط إعادة المحاولة لعدة BIOs غير محظورة في استدعاء واحد لـ select()، يمكن خدمة عدة BIOs في خيط واحد، رغم أن الأداء قد يكون ضعيفاً إذا وُجدت SSL BIOs لأن تأخيرات طويلة قد تحدث أثناء عملية المصافحة الأولية.

من الممكن أن يحجب BIO إلى أجل غير مسمى إذا لم تستطع بنية الإدخال/الإخراج الأساسية معالجة أو إرجاع أي بيانات. هذا يعتمد على سلوك دوال الإدخال/الإخراج للمنصة. غالباً ما يكون هذا غير مرغوب: أحد الحلول هو استخدام إدخال/إخراج غير محظور واستخدام مهلة على استدعاء select() (أو ما يعادله).

العلل
لا تستطيع دوال OpenSSL ASN1 التعامل بلطف مع الإدخال/الإخراج غير المحظور: أي لا يمكنها إعادة المحاولة بعد قراءة أو كتابة جزئية. يُتجاوز هذا عادةً بتمرير البيانات ذات الصلة فقط إلى دوال ASN1 عندما يمكن قراءة أو كتابة البنية بأكملها.

القيم المُرجعة
BIO_should_read() و BIO_should_write() و BIO_should_io_special() و BIO_should_retry() تُرجع إما 1 أو 0 بناءً على الظروف الفعلية لـ BIO.

BIO_retry_type() تُرجع مجموعة أعلام تعرض سبب حالة إعادة المحاولة أو خطأ إذا لم توجد حالة إعادة محاولة.

BIO_get_retry_BIO() تُرجع بنية BIO صالحة.

BIO_get_retry_reason() تُرجع سبب حالة خاصة.

انظر أيضًا
bio(7)

التاريخ
أُضيفت دالتا BIO_get_retry_reason() و BIO_set_retry_reason() في OpenSSL 1.1.0.

حقوق النسخ
حقوق الطبع والنشر 2000-2018 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

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

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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