BIO_S_ACCEPT(3SSL)

الاسم
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_accept, BIO_set_accept_bios, BIO_get_peer_name, BIO_get_peer_port, BIO_get_accept_ip_family, BIO_set_accept_ip_family, BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - BIO القبول

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

 const BIO_METHOD *BIO_s_accept(void);

 long BIO_set_accept_name(BIO *b, char *name);
 char *BIO_get_accept_name(BIO *b);

 long BIO_set_accept_port(BIO *b, char *port);
 char *BIO_get_accept_port(BIO *b);

 BIO *BIO_new_accept(char *host_port);

 long BIO_set_nbio_accept(BIO *b, int n);
 long BIO_set_tfo_accept(BIO *b, int n);
 long BIO_set_accept_bios(BIO *b, char *bio);

 char *BIO_get_peer_name(BIO *b);
 char *BIO_get_peer_port(BIO *b);
 long BIO_get_accept_ip_family(BIO *b);
 long BIO_set_accept_ip_family(BIO *b, long family);

 long BIO_set_bind_mode(BIO *b, long mode);
 long BIO_get_bind_mode(BIO *b);

 int BIO_do_accept(BIO *b);

الوصف
BIO_s_accept() يُرجع طريقة BIO للقبول. هذه غلاف حول دوال قبول المقبس TCP/IP للمنصة.

باستخدام BIOs القبول، يمكن قبول اتصالات TCP/IP ونقل البيانات باستخدام إجراءات BIO فقط. بهذه الطريقة، تُخفى أي عمليات خاصة بالمنصة بواسطة تجريد BIO.

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

BIOs القبول تدعم BIO_puts() ولكن لا تدعم BIO_gets().

إذا وُضع علم الإغلاق على BIO القبول، فإن أي اتصال نشط على تلك السلسلة يُغلق ويُغلق المقبس عند تحرير BIO.

استدعاء BIO_reset() على BIO القبول سيغلق أي اتصال نشط ويعيد تعيين BIO إلى حالة ينتظر فيها اتصالاً وارداً آخر.

يمكن استدعاء BIO_get_fd() و BIO_set_fd() لاسترجاع أو تعيين مقبس القبول. انظر BIO_s_fd(3)

BIO_set_accept_name() تستخدم السلسلة name لتعيين اسم القبول. يُعرض الاسم كسلسلة بالصيغة "host:port"، حيث "host" هي الواجهة المستخدمة و"port" هو المنفذ. يمكن أن يكون المضيف "*" أو فارغاً، وهو ما يُفسر على أنه أي واجهة. إذا كان المضيف عنوان IPv6، فيجب وضعه بين قوسين، مثلاً "[::1]:https". "port" له نفس الصيغة كالمنفذ المحدد في BIO_set_conn_port() لـ BIOs الاتصال، أي يمكن أن يكون سلسلة منفذ رقمية أو سلسلة للبحث باستخدام getservbyname() وجدول سلاسل.

BIO_set_accept_port() تستخدم السلسلة port لتعيين منفذ القبول لـ BIO b. "port" له نفس الصيغة كالمنفذ المحدد في BIO_set_conn_port() لـ BIOs الاتصال، أي يمكن أن يكون سلسلة منفذ رقمية أو سلسلة للبحث باستخدام getservbyname() وجدول سلاسل. إذا كان المنفذ المعطى هو 0، فإن منفذاً عشوائياً متاحاً يُختار. يمكن الاستعلام عنه باستخدام BIO_sock_info() و BIO_ADDR_service_string(3).

BIO_new_accept() تدمج BIO_new() و BIO_set_accept_name() في استدعاء واحد: أي أنها تنشئ BIO قبول جديد بالمنفذ host_port.

BIO_set_nbio_accept() تعين مقبس القبول إلى وضع الحظر (المبدئي) إذا كان n هو 0 أو وضع عدم الحظر إذا كان n هو 1.

BIO_set_tfo_accept() تُفعّل TCP Fast Open على مقبس القبول إذا كان n هو 1 أو تُعطّل TCP Fast Open إذا كان n هو 0 (المبدئي). تعيين القيمة إلى 1 يعادل تعيين BIO_SOCK_TFO في BIO_set_bind_mode().

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

BIO_get_accept_ip_family() تُرجع عائلة IP المقبولة بواسطة BIO b، والتي قد تكون BIO_FAMILY_IPV4 أو BIO_FAMILY_IPV6 أو BIO_FAMILY_IPANY.

BIO_set_accept_ip_family() يضبط عائلة IP family المقبولة من BIO b. المبدئي هو BIO_FAMILY_IPANY.

BIO_set_bind_mode() و BIO_get_bind_mode() يضبطان ويسترجعان وضع الربط الحالي. إذا ضُبط BIO_BIND_NORMAL (المبدئي) فلا يمكن ربط مقبس آخر بنفس المنفذ. إذا ضُبط BIO_BIND_REUSEADDR فيمكن للمقابس الأخرى الربط بنفس المنفذ. إذا ضُبط BIO_BIND_REUSEADDR_IF_UNUSED فيُحاول أولاً استخدام BIO_BIN_NORMAL، وإذا فشل ذلك والمنفذ غير مستخدم، فتُجرى محاولة ثانية باستخدام BIO_BIND_REUSEADDR. إذا ضُبط BIO_SOCK_TFO، فسيُهيأ المقبس لقبول اتصالات TCP Fast Open.

BIO_do_accept() يخدم دالتين. عند استدعائه أولاً، بعد إعداد BIO القبول، سيحاول إنشاء مقبس القبول وربط عنوان به. الاستدعاءات الثانية واللاحقة لـ BIO_do_accept() ستنتظر اتصالاً وارداً، أو تطلب إعادة محاولة في وضع غير محظور.

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

عند إنشاء اتصال، يُنشأ BIO مقبس جديد للاتصال ويُلحق بالسلسلة. أي أن السلسلة أصبحت الآن accept->socket. هذا يعني فعلياً أن محاولة الإدخال/الإخراج على مقبس قبول أولي ستنتظر اتصالاً وارداً ثم تؤدي الإدخال/الإخراج عليه.

إذا ضُبطت أي BIOs إضافية باستخدام BIO_set_accept_bios() فتُوضع بين المقبس وBIO القبول، أي أن السلسلة ستكون accept->otherbios->socket.

إذا أراد خادم معالجة اتصالات متعددة (كما هو الحال عادة)، فيجب جعل BIO القبول متاحاً لاتصالات واردة إضافية. يمكن فعل ذلك بانتظار اتصال ثم استدعاء:

 connection = BIO_pop(accept);

بعد هذا الاستدعاء، سيحتوي connection على BIO للاتصال المُنشأ حديثاً وسيصبح accept الآن BIO واحداً مرة أخرى يمكن استخدامه لانتظار اتصالات واردة إضافية. إذا لم تُقبل اتصالات إضافية، يمكن تحرير accept باستخدام BIO_free().

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

إذا كان مقبس القبول الأساسي غير محظور واستُدعي BIO_do_accept() لانتظار اتصال وارد، فمن الممكن لـ BIO_should_io_special() مع السبب BIO_RR_ACCEPT. إذا حدث هذا، فهو مؤشر على أن محاولة القبول ستحظر: يجب على التطبيق اتخاذ إجراء مناسب لانتظار حتى يقبل المقبس الأساسي اتصالاً ويعيد محاولة الاستدعاء.

BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_get_peer_name(), BIO_get_peer_port(), BIO_get_accept_ip_family(), BIO_set_accept_ip_family(), BIO_set_bind_mode(), BIO_get_bind_mode() و BIO_do_accept() هي وحدات ماكرو.

القيم المُرجعة
BIO_do_accept(), BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_set_accept_ip_family(), و BIO_set_bind_mode() تُرجع 1 للنجاح و <= 0 للفشل.

BIO_get_accept_name() تُرجع اسم القبول أو NULL عند الخطأ. BIO_get_peer_name() تُرجع اسم النظير أو NULL عند الخطأ.

BIO_get_accept_port() تُرجع منفذ القبول كسلسلة أو NULL عند الخطأ. BIO_get_peer_port() تُرجع منفذ النظير كسلسلة أو NULL عند الخطأ. BIO_get_accept_ip_family() تُرجع عائلة IP أو <= 0 عند الخطأ.

BIO_get_bind_mode() تُرجع مجموعة أعلام BIO_BIND، أو <= 0 عند الفشل.

BIO_new_accept() تُرجع BIO أو NULL عند الخطأ.

أمثلة
هذا المثال يقبل اتصالين على المنفذ 4444، ويرسل رسائل عبر كل منهما، ويغلق كليهما أخيراً.

 BIO *abio, *cbio, *cbio2;

 /* الاستدعاء الأول لـ BIO_do_accept() يضبط BIO القبول */
 abio = BIO_new_accept("4444");
 if (BIO_do_accept(abio) <= 0) {
     fprintf(stderr, "خطأ في إعداد القبول\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }

 /* انتظار اتصال وارد */
 if (BIO_do_accept(abio) <= 0) {
     fprintf(stderr, "خطأ في قبول الاتصال\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 fprintf(stderr, "تم إنشاء الاتصال 1\n");

 /* استرجاع BIO للاتصال */
 cbio = BIO_pop(abio);
 BIO_puts(cbio, "الاتصال 1: إرسال بيانات على الاتصال الأولي\n");
 fprintf(stderr, "أُرسلت البيانات على الاتصال 1\n");

 /* انتظار اتصال آخر */
 if (BIO_do_accept(abio) <= 0) {
     fprintf(stderr, "خطأ في قبول الاتصال\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 fprintf(stderr, "تم إنشاء الاتصال 2\n");

 /* إغلاق BIO القبول لرفض اتصالات إضافية */
 cbio2 = BIO_pop(abio);
 BIO_free(abio);
 BIO_puts(cbio2, "الاتصال 2: إرسال بيانات على الثاني\n");
 fprintf(stderr, "أُرسلت البيانات على الاتصال 2\n");

 BIO_puts(cbio, "الاتصال 1: تم إنشاء الاتصال الثاني\n");

 /* إغلاق الاتصالين المُنشأين */
 BIO_free(cbio);
 BIO_free(cbio2);

التاريخ
BIO_set_tfo_accept() أُضيف في OpenSSL 3.2.

حقوق النسخ
حقوق النشر 2000-2022 لمؤلفي مشروع 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.