BIO_S_CONNECT(3ssl)

الاسم
BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_address, BIO_set_conn_ip_family, BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_address, BIO_get_conn_ip_family, BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get0_dgram_bio, BIO_do_connect - BIO اتصال

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

 const BIO_METHOD *BIO_s_connect(void);

 BIO *BIO_new_connect(const char *name);

 long BIO_set_conn_hostname(BIO *b, char *name);
 long BIO_set_conn_port(BIO *b, char *port);
 long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
 long BIO_set_conn_ip_family(BIO *b, long family);
 const char *BIO_get_conn_hostname(BIO *b);
 const char *BIO_get_conn_port(BIO *b);
 const BIO_ADDR *BIO_get_conn_address(BIO *b);
 const long BIO_get_conn_ip_family(BIO *b);

 long BIO_set_nbio(BIO *b, long n);

 int BIO_set_sock_type(BIO *b, int sock_type);
 int BIO_get_sock_type(BIO *b);
 int BIO_get0_dgram_bio(BIO *B, BIO **dgram_bio);

 long BIO_do_connect(BIO *b);

الوصف
BIO_s_connect() تُرجع أسلوب BIO للاتصال. هذه غلاف حول إجراءات اتصال مقبس TCP/IP الخاصة بالمنصة.

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

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

تدعم BIOs الاتصال BIO_puts() و BIO_gets().

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

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

BIO_new_connect() تدمج BIO_new() و BIO_set_conn_hostname() في استدعاء واحد: أي أنها تُنشئ BIO اتصال جديد باسم المضيف name.

BIO_set_conn_hostname() تستخدم السلسلة name لتعيين اسم المضيف. يمكن أن يكون اسم المضيف عنوان IP؛ إذا كان العنوان من نوع IPv6، فيجب وضعه بين قوسين "[" و "]". يمكن أن يتضمن اسم المضيف أيضًا المنفذ بالصيغة hostname:port؛ انظر BIO_parse_hostserv(3) و BIO_set_conn_port() للتفاصيل.

BIO_set_conn_port() تعين المنفذ إلى port. يمكن أن يكون port بالصيغة الرقمية أو سلسلة خدمة مثل "http"، والتي ستُربط برقم منفذ باستخدام دالة النظام getservbyname().

BIO_set_conn_address() تعين معلومات العنوان والمنفذ باستخدام BIO_ADDR(3ssl).

BIO_set_conn_ip_family() تعين عائلة IP.

BIO_get_conn_hostname() تُرجع اسم المضيف لـ BIO الاتصال أو NULL إذا تمت تهيئة BIO ولكن لم يُعين اسم مضيف. قيمة الإرجاع هذه مؤشر داخلي لا ينبغي تعديله.

BIO_get_conn_port() تُرجع المنفذ كسلسلة. قيمة الإرجاع هذه مؤشر داخلي لا ينبغي تعديله.

BIO_get_conn_address() تُرجع معلومات العنوان كـ BIO_ADDR. قيمة الإرجاع هذه مؤشر داخلي لا ينبغي تعديله.

BIO_get_conn_ip_family() تُرجع عائلة IP الخاصة بـ BIO المتصل.

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

BIO_do_connect() تحاول توصيل BIO المقدم. يُنفذ ذلك مصافحة SSL/TLS بقدر ما تدعمه BIO. بالنسبة لـ BIOs غير SSL، يُجرى الاتصال عادةً على مستوى TCP. إذا أسفر تحليل اسم النطاق عن عناوين IP متعددة، فتُجرى محاولة جميعها بعد فشل connect(). تُرجع الدالة 1 إذا وُصل الاتصال بنجاح. تُرجع قيمة صفر أو سالبة إذا تعذر إنشاء الاتصال. يجب استخدام استدعاء BIO_should_retry() لـ BIOs الاتصال غير المحظورة لتحديد ما إذا كان يجب إعادة المحاولة. إذا كان الاتصال قد أُنشئ بالفعل، فلا تأثير لهذا الاستدعاء.

BIO_set_sock_type() يمكن استخدامها لضبط قيمة نوع مقبس كما ستمرر في استدعاء socket(2). القيم المدعومة حاليًا فقط هي SOCK_STREAM (المبدئي) وSOCK_DGRAM. إذا ضُبط SOCK_DGRAM، فالاتصال المُنشأ هو مقبس مخطط بيانات UDP يُدار عبر BIO_s_datagram(3). استدعاءات الإدخال/الإخراج مثل BIO_read(3) وBIO_write(3) تُمرر بشفافية إلى مثيل داخلي من BIO_s_datagram(3). يمكن استرجاع مثيل BIO_s_datagram(3) المُنشأ باستخدام BIO_get0_dgram_bio() إذا رغب، والذي يكتب مؤشرًا إلى مثيل BIO_s_datagram(3) إلى *dgram_bio. عمر مثيل BIO_s_datagram(3) الداخلي يُدار بواسطة BIO_s_connect() ولا يحتاج إلى تحريره من قبل المستدعي.

BIO_get_sock_type() تسترجع القيمة المضبوطة باستخدام BIO_set_sock_type().

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

إذا وُفر اسم المنفذ كجزء من اسم المضيف، فسيتجاوز ذلك أي قيمة مضبوطة بـ BIO_set_conn_port(). قد يكون هذا غير مرغوب إذا كان التطبيق لا يرغب في السماح بالاتصال بمنافذ عشوائية. يمكن تجنب ذلك بالتحقق من وجود الحرف ':' في اسم المضيف المُمرر وإما الإشارة إلى خطأ أو اقتطاع السلسلة عند تلك النقطة.

القيم التي تُرجعها BIO_get_conn_hostname() وBIO_get_conn_address() وBIO_get_conn_port() تُحدث عند محاولة اتصال. قبل أي محاولة اتصال، القيم المُرجعة هي تلك التي ضبطها التطبيق نفسه.

لا يتعين على التطبيقات استدعاء BIO_do_connect() ولكن قد ترغب في فعل ذلك لفصل عملية الاتصال عن معالجة الإدخال/الإخراج الأخرى.

إذا ضُبط الإدخال/الإخراج غير المحظور، فستُطلب إعادة المحاولة حسب الاقتضاء.

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

BIO_set_conn_hostname() وBIO_set_conn_port() وBIO_get_conn_hostname() وBIO_set_conn_address() وBIO_get_conn_port() وBIO_get_conn_address() وBIO_set_conn_ip_family() وBIO_get_conn_ip_family() وBIO_set_nbio() وBIO_do_connect() هي وحدات ماكرو.

القيم المُرجعة
BIO_s_connect() تُرجع طريقة BIO الاتصال.

BIO_set_conn_address() وBIO_set_conn_port() وBIO_set_conn_ip_family() تُرجع 1 أو <=0 إذا حدث خطأ.

BIO_set_conn_hostname() تُرجع 1 عند النجاح و<=0 عند الفشل.

BIO_get_conn_address() تُرجع معلومات العنوان أو NULL إذا لم يُضبط شيء.

BIO_get_conn_hostname() تُرجع اسم المضيف المتصل أو NULL إذا لم يُضبط شيء.

BIO_get_conn_ip_family() تُرجع عائلة العنوان أو -1 إذا لم تُضبط.

BIO_get_conn_port() تُرجع سلسلة تمثل المنفذ المتصل أو NULL إذا لم يُضبط.

BIO_set_nbio() تُرجع 1 أو <=0 إذا حدث خطأ.

BIO_do_connect() يُرجع 1 إذا وُصِل الاتصال بنجاح و<=0 إذا فشل الاتصال.

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

BIO_get_sock_type() يُرجع نوع مقبس أو 0 إذا لم تُدعم الاستدعاء.

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

أمثلة
هذا مثال يتصل بخادم ويب على المضيف المحلي ويحاول استرجاع صفحة ونسخ النتيجة إلى المخرج المعياري.

 BIO *cbio, *out;
 int len;
 char tmpbuf[1024];

 cbio = BIO_new_connect("localhost:http");
 out = BIO_new_fp(stdout, BIO_NOCLOSE);
 if (BIO_do_connect(cbio) <= 0) {
     fprintf(stderr, "Error connecting to server\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 BIO_puts(cbio, "GET / HTTP/1.0\n\n");
 for (;;) {
     len = BIO_read(cbio, tmpbuf, 1024);
     if (len <= 0)
         break;
     BIO_write(out, tmpbuf, len);
 }
 BIO_free(cbio);
 BIO_free(out);

انظر أيضًا
BIO_ADDR(3), BIO_parse_hostserv(3)

التاريخ
BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(), وBIO_get_conn_ip() أُزيلت في OpenSSL 1.1.0. استخدم BIO_set_conn_address() وBIO_get_conn_address() بدلاً منها.

BIOs الاتصال تدعم BIO_gets(), BIO_get0_dgram_bio(), BIO_get_sock_type(), BIO_set_sock_type() أُضيفت في OpenSSL 3.2.

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