الاسم¶

BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send, BIO_get_ktls_recv, BIO_set_conn_mode, BIO_get_conn_mode, BIO_set_tfo - عمليات التحكم في BIO

موجز¶

 #include <openssl/bio.h>
 typedef int BIO_info_cb(BIO *b, int state, int res);
 long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
 long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb);
 void *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
 long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
 int BIO_reset(BIO *b);
 int BIO_seek(BIO *b, int ofs);
 int BIO_tell(BIO *b);
 int BIO_flush(BIO *b);
 int BIO_eof(BIO *b);
 int BIO_set_close(BIO *b, long flag);
 int BIO_get_close(BIO *b);
 int BIO_pending(BIO *b);
 int BIO_wpending(BIO *b);
 size_t BIO_ctrl_pending(BIO *b);
 size_t BIO_ctrl_wpending(BIO *b);
 int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp);
 int BIO_set_info_callback(BIO *b, BIO_info_cb *cb);
 int BIO_get_ktls_send(BIO *b);
 int BIO_get_ktls_recv(BIO *b);
 int BIO_set_conn_mode(BIO *b, int mode);
 int BIO_get_conn_mode(BIO *b);
 int BIO_set_tfo(BIO *b, int onoff);

الوصف¶

الدوال BIO_ctrl() و BIO_callback_ctrl() و BIO_ptr_ctrl() و BIO_int_ctrl() هي عمليات "تحكم" في BIO تأخذ وسائط من أنواع مختلفة. هذه الدوال لا تُستدعى عادةً مباشرةً، بل تُستخدم بدلاً منها ماكروات متنوعة. الماكروات القياسية موصوفة أدناه، والماكروات الخاصة بنوع معين من BIO موصوفة في صفحة الدليل الخاصة بذلك BIO بالإضافة إلى أي ميزات خاصة للاستدعاءات القياسية.

عادةً ما يُعيد BIO_reset() BIO إلى حالة مبدئية ما، ففي حالة BIOs المرتبطة بالملف مثلاً يُعيد مؤشر الملف إلى بداية الملف.

BIO_seek() يُعيد تعيين مؤشر موضع الملف لـBIO المرتبط بالملف (أي واصف الملف وBIOs FILE) إلى ofs بايت من بداية الملف.

يُرجع BIO_tell() موضع الملف الحالي لـ BIO مرتبط بالملف.

يكتب BIO_flush() عادةً أي بيانات مخزنة داخلياً، وفي بعض الحالات يُستخدم للإشارة إلى EOF وأنه لن تُكتب بيانات أخرى.

يُرجع BIO_eof() 1 إذا قرأ BIO علامة EOF، ويختلف المعنى الدقيق لـ "EOF" حسب نوع BIO.

يضبط BIO_set_close() علامة إغلاق BIO b إلى flag. يمكن أن تأخذ flag القيمة BIO_CLOSE أو BIO_NOCLOSE. يُستخدم BIO_CLOSE عادةً في BIO مصدر/مصرف للإشارة إلى أن تيار الإدخال/الإخراج الأساسي يجب أن يُغلق عند تحرير BIO.

يُرجع BIO_get_close() علامة إغلاق BIO.

تُرجع BIO_pending() و BIO_ctrl_pending() و BIO_wpending() و BIO_ctrl_wpending() عدد الأحرف المعلقة في مخازن القراءة والكتابة لـ BIO. لا تدعم جميع BIOs هذه الاستدعاءات. تُرجع BIO_ctrl_pending() و BIO_ctrl_wpending() نوع size_t وهما دالتان، بينما BIO_pending() و BIO_wpending() هما ماكروات تستدعيان BIO_ctrl().

تُرجع BIO_get_ktls_send() 1 إذا كان BIO يستخدم مسار بيانات Kernel TLS للإرسال. وإلا، تُرجع صفراً. تُرجع BIO_get_ktls_recv() 1 إذا كان BIO يستخدم مسار بيانات Kernel TLS للاستقبال. وإلا، تُرجع صفراً.

تُرجع BIO_get_conn_mode() وضع اتصال BIO. يضبط BIO_set_conn_mode() وضع اتصال BIO.

يُعطل BIO_set_tfo() TCP Fast Open عندما يكون onoff 0، ويُفعله عندما يكون onoff غير صفري. ضبط القيمة إلى 1 يُعادل ضبط BIO_SOCK_TFO في BIO_set_conn_mode().

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

يُرجع BIO_reset() عادةً 1 للنجاح و <=0 للفشل. BIOs الملف هي استثناء، فهي تُرجع 0 للنجاح و -1 للفشل.

يُرجع كل من BIO_seek() و BIO_tell() موضع الملف الحالي عند النجاح و -1 عند الفشل، باستثناء BIOs الملف التي تُرجع دائماً 0 للنجاح و -1 للفشل بالنسبة لـ BIO_seek().

BIO_flush() يُرجع 1 للنجاح و<=0 للفشل.

BIO_eof() يُرجع 1 إذا وُصِلَ إلى نهاية الملف، 0 إذا لم يُوصل، أو قيم سالبة للفشل.

BIO_set_close() يُرجع 1 عند النجاح أو <=0 للفشل.

BIO_get_close() يُرجع قيمة علم الإغلاق: BIO_CLOSE أو BIO_NOCLOSE. ويُرجع أيضًا قيمًا سالبة أخرى إذا حدث خطأ.

BIO_pending()، BIO_ctrl_pending()، BIO_wpending() وBIO_ctrl_wpending() يُرجعون كمية البيانات المعلقة. BIO_pending() وBIO_wpending() يُرجعان قيمة سالبة أو 0 عند الخطأ. BIO_ctrl_pending() وBIO_ctrl_wpending() يُرجعان 0 عند الخطأ.

تُرجع BIO_get_ktls_send() 1 إذا كان BIO يستخدم مسار بيانات Kernel TLS للإرسال. وإلا، تُرجع صفراً. تُرجع BIO_get_ktls_recv() 1 إذا كان BIO يستخدم مسار بيانات Kernel TLS للاستقبال. وإلا، تُرجع صفراً.

BIO_set_conn_mode() يُرجع 1 للنجاح و0 للفشل. BIO_get_conn_mode() يُرجع وضع الاتصال الحالي. والذي قد يحتوي على الجمع البتّي للأعلام التالية:

 BIO_SOCK_REUSEADDR
 BIO_SOCK_V6_ONLY
 BIO_SOCK_KEEPALIVE
 BIO_SOCK_NONBLOCK
 BIO_SOCK_NODELAY
 BIO_SOCK_TFO

BIO_set_tfo() يُرجع 1 للنجاح، و0 للفشل.

ملاحظات¶

BIO_flush()، لأنه يمكنه كتابة البيانات، قد يُرجع 0 أو -1 للإشارة إلى أن الاستدعاء يجب إعادة محاولته لاحقًا بطريقة مشابهة لـBIO_write_ex(). يجب استخدام استدعاء BIO_should_retry() واتخاذ الإجراء المناسب إذا فشل الاستدعاء.

قيم الإرجاع لـBIO_pending() وBIO_wpending() قد لا تحدد بشكل موثوق كمية البيانات المعلقة في جميع الحالات. على سبيل المثال في حالة BIO ملف، قد تكون بعض البيانات متاحة في المخازن المؤقتة الداخلية لهيكل FILE ولكن ليس من الممكن تحديد ذلك بطريقة محمولة. بالنسبة لأنواع أخرى من BIO قد لا تكون مدعومة.

BIOs المرشحة إذا لم تعالج داخليًا عملية BIO_ctrl() معينة، فإنها عادةً تمرر العملية إلى BIO التالي في السلسلة. هذا يعني غالبًا أنه لا حاجة لتحديد موقع BIO المطلوب لعملية معينة، يمكن استدعاؤها على سلسلة وسيتم تمريرها آليًا إلى BIO ذي الصلة. ومع ذلك، قد يتسبب هذا في نتائج غير متوقعة: على سبيل المثال، لا تنفذ أي BIOs مرشحة حاليًا BIO_seek()، ولكن قد ينجح هذا إذا انتهت السلسلة في BIO ملف أو واصف ملف.

BIOs المصدر/المصرف يُرجعون 0 إذا لم يتعرفوا على عملية BIO_ctrl().

العلل¶

بعض قيم الإرجاع غامضة ويجب توخي الحذر. على وجه الخصوص، يمكن إرجاع قيمة 0 إذا كانت العملية غير مدعومة، أو إذا حدث خطأ، أو إذا لم يُوصل إلى نهاية الملف، وفي حالة BIO_seek() على BIO ملف لعملية ناجحة.

في الإصدارات الأقدم من OpenSSL، كان بإمكان BIO_ctrl_pending() وBIO_ctrl_wpending() إرجاع قيم أكبر من INT_MAX عند الخطأ.

التاريخ¶

أُضيفت وحدات الماكرو BIO_get_ktls_send() وBIO_get_ktls_recv() في OpenSSL 3.0. تم تعديلها لعدم إرجاع -1 أبدًا في OpenSSL 3.0.4.

أُضيفت دوال BIO_get_conn_mode() وBIO_set_conn_mode() وBIO_set_tfo() في OpenSSL 3.2.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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