الاسم¶

BIO_s_datagram, BIO_new_dgram, BIO_ctrl_dgram_connect, BIO_ctrl_set_connected, BIO_dgram_recv_timedout, BIO_dgram_send_timedout, BIO_dgram_get_peer, BIO_dgram_set_peer, BIO_dgram_detect_peer_addr, BIO_dgram_get_mtu_overhead - BIO شبكي بدلالات الرزم

موجز¶

 #include <openssl/bio.h>
 BIO_METHOD *BIO_s_datagram(void);
 BIO *BIO_new_dgram(int fd, int close_flag);
 int BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer);
 int BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer);
 int BIO_dgram_recv_timedout(BIO *bio);
 int BIO_dgram_send_timedout(BIO *bio);
 int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer);
 int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer);
 int BIO_dgram_get_mtu_overhead(BIO *bio);
 int BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer);

الوصف¶

BIO_s_datagram() هي تنفيذ BIO مصمم للاستخدام مع مقابس شبكية توفر دلالات الرزم، مثل مقابس UDP. وهي مناسبة للاستخدام مع DTLSv1 أو QUIC.

لأن BIO_s_datagram() تمتلك دلالات رزم، فإن استدعاء واحد لـ BIO_write() يُرسل رزمة واحدة واستدعاء واحد لـ BIO_read() يستقبل رزمة واحدة. إذا كان حجم المخزن المُمرر إلى BIO_read() غير كافٍ، تُبتَر الرزمة بصمت.

لـ BIO قائم على الذاكرة توفر دلالات رزم مطابقة لتلك الخاصة بـ BIO_s_datagram()، انظر BIO_s_dgram_pair(3).

تدعم BIO هذه دالتي BIO_sendmmsg(3) و BIO_recvmmsg(3).

عند استخدام BIO_s_datagram()، من المهم ملاحظة أن:

• يمكن استخدام BIO هذه مع مقبس شبكي موصول أو غير موصول. المقبس الموصول هو مقبس شبقي استُدعيت عليه BIO_connect(3) أو دالة مشابهة خاصة بنظام التشغيل. يمكن لمثل هذا المقبس استقبال رزم فقط من النظير المُحدد. أي مقبس آخر هو مقبس غير موصول ويمكنه استقبال رزم من أي مضيف.
• على الرغم من تسميتهما، لا BIO_ctrl_dgram_connect() ولا BIO_ctrl_set_connected() تسببان اتصال المقبس. تُوفر عناصر التحكم هذه للإشارة إلى BIO كيف يُهيأ المقبس الأساسي وكيف سيُستخدم؛ انظر أدناه.
• استخدام BIO_s_datagram() مع مقبس شبكي غير موصول خطير لأن أي استدعاء ناجح لـ BIO_read() يؤدي إلى تعيين عنوان النظير المستخدم لأي استدعاء لاحق لـ BIO_write() إلى عنوان المصدر للرزمة المستلمة بواسطة ذلك الاستدعاء لـ BIO_read(). وبالتالي، ما لم يستدعِ المتصل BIO_dgram_set_peer() فورًا قبل كل استدعاء لـ BIO_write()، أو لا يستدعي BIO_read() أبدًا، فقد يتسبب أي مضيف على الشبكة في إعادة توجيه الرزم المستقبلية المكتوبة إلى ذلك المضيف. لذلك، يُوصى بأن يستخدم المستخدمون إما BIO_s_dgram() فقط مع مقبس موصول، أو، إذا استُخدمت BIO_s_dgram() مع مقبس غير موصول، استخدام طريقتي BIO_sendmmsg(3) و BIO_recvmmsg(3) فقط والاستغناء عن استخدام BIO_read(3) و BIO_write(3). الاستثناء هو عندما يجب استخدام DTLSv1_listen(3)؛ انظر DTLSv1_listen(3) لمزيد من النقاش.
• على عكس BIO_read(3) و BIO_write(3)، فإن طريقتي BIO_sendmmsg(3) و BIO_recvmmsg(3) عديمتا الحالة ولا تسببان تغيير الحالة الداخلية لـ BIO_s_datagram().

عناصر تحكم متنوعة متاحة لتكوين BIO_s_datagram() باستخدام BIO_ctrl(3):

BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)

هذا مكافئ لاستدعاء BIO_dgram_set_peer(3).

على الرغم من اسمها، لا تسبب هذه الدالة اتصال المقبس الأساسي.

BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)

يُعلم هذا الدالة BIO_s_datagram() ما إذا كان المقبس الأساسي قد وُصل، وبالتالي كيف ينبغي للدالة BIO_s_datagram() أن تحاول استخدام المقبس.

إذا كانت وسيطة peer غير NULL، تفترض BIO_s_datagram() أن المقبس الأساسي قد وُصل وستحاول استخدام المقبس باستخدام واجهات برمجة تطبيقات نظام التشغيل التي لا تحدد عناوين النظير (مثلاً، send(3) و recv(3) أو ما شابه). يجب أن تحدد وسيطة peer عنوان النظير الذي وُصل به المقبس.

إذا كانت وسيطة peer NULL، تفترض BIO_s_datagram() أن المقبس الأساسي غير موصول وستحاول استخدام المقبس باستخدام واجهات برمجة تطبيقات نظام التشغيل التي تحدد عناوين النظير (مثلاً، sendto(3) و recvfrom(3)).

لا يؤثر عنصر التحكم هذا على تشغيل BIO_sendmmsg(3) أو BIO_recvmmsg(3).

BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)

يُخرج هذا قيمة BIO_ADDR تحدد إحدى القيم التالية، أياً منها حدث مؤخراً:

BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)

يضبط عنوان النظير الذي سيُستخدم للكتابات اللاحقة إلى BIO هذا.

تحذير: عند استخدامه مع مقبس شبكة غير موصول، قد تُعدل القيمة المضبوطة باستدعاءات مستقبلية لـ BIO_read(3)، مما يجعل استخدام BIO_s_datagram() خطيراً عند استخدامه مع مقابس شبكة غير موصولة؛ انظر أعلاه.

لا يؤثر هذا على تشغيل BIO_sendmmsg(3). لا يؤثر BIO_recvmmsg(3) على القيمة المضبوطة بواسطة BIO_dgram_set_peer().

BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR)

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

BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)

يُرجع 1 إذا كانت آخر عملية إدخال/إخراج أُجريت على BIO (مثلاً، عبر استدعاء BIO_read(3)) قد نجمت عن انتهاء مهلة الاستقبال.

BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)

يُرجع 1 إذا كانت آخر عملية إدخال/إخراج أُجريت على BIO (مثلاً، عبر استدعاء BIO_write(3)) قد نجمت عن انتهاء مهلة الإرسال.

BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)

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

تعتمد القيمة التي تُرجعها هذه الاستدعاء على بروتوكول طبقة الشبكة المستخدم.

القيمة المُرجعة ليست موثوقة تمامًا لأن الحمل الإضافي لمخططات البيانات قد يكون أعلى في تكوينات الشبكة غير النمطية، على سبيل المثال عند استخدام رؤوس تمديد IPv6 أو خيارات IPv4.

BIO_CTRL_DGRAM_SET_DONT_FRAG

إذا كان num غير صفري، يُهيئ مقبس الشبكة الأساسي لتمكين وضع عدم التجزئة، حيث تُضبط الرزم مع تعيين بت عدم التجزئة (DF) في IP. إذا كان num صفرًا، يُعطل وضع عدم التجزئة.

BIO_CTRL_DGRAM_QUERY_MTU

يستعلم نظام التشغيل عن تقييمه لـ Path MTU للوجهة التي يتصل بها مقبس الشبكة الأساسي، ويُعيد ذلك Path MTU بالبايتات. يمكن استخدام هذا التحكم فقط مع مقبس متصل.

هذا غير مدعوم على جميع المنصات ويعتمد على توفر دعم نظام التشغيل. يُرجع 0 عند الفشل.

BIO_CTRL_DGRAM_MTU_DISCOVER

يطلب هذا التحكم تمكين اكتشاف Path MTU على مقبس الشبكة الأساسي.

BIO_CTRL_DGRAM_GET_FALLBACK_MTU

تُرجع الحجم الأدنى المقدر لحمولة مخطط البيانات الذي يجب دعمه دائمًا على BIO. يُحدد هذا الحجم بواسطة الحد الأدنى لـ MTU المطلوب دعمه بواسطة طبقة الشبكة الأساسية المطبقة. قد يؤدي استخدام مخططات البيانات بهذا الحجم إلى أداء دون الأمثل، لكن يجب أن يكون قابلاً للتوجيه في جميع الظروف. القيمة المُرجعة هي حجم حمولة مخطط البيانات بالبايتات ولا تتضمن حجم رؤوس بروتوكول الطبقة 3 أو الطبقة 4.

BIO_CTRL_DGRAM_MTU_EXCEEDED

تُرجع 1 إذا فشلت آخر محاولة كتابة إلى BIO بسبب تجاوز حجم الكتابة المُحاولة لـ MTU المطبق.

BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT

يقبل مؤشرًا إلى struct timeval. إذا كان الوقت المحدد صفرًا، يُعطل مهلات الاستقبال. وإلا، يُهيئ الفاصل الزمني المحدد كمهلة استقبال للمقبس لأغراض استدعاءات BIO_read(3) المستقبلية.

BIO_CTRL_DGRAM_SET_PEEK_MODE

إذا كان num غير صفري، يُفعّل وضع peek؛ وإلا، يُعطّله. عند تفعيل وضع peek، تقرأ استدعاءات BIO_read(3) مخططات البيانات من مقبس الشبكة الأساسي في وضع peek، مما يعني أن استدعاءً مستقبليًا لـ BIO_read(3) سيعطي نفس مخطط البيانات حتى يُعطّل وضع peek.

BIO_recvmmsg(3) لا يتأثر بهذا التحكم.

BIO_new_dgram() هي دالة مساعدة تُنشئ مثيلاً لـ BIO_s_datagram() وتضبط BIO لاستخدام المقبس المُعطى في fd باستدعاء BIO_set_fd().

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

BIO_s_datagram() تُرجع دالة BIO.

BIO_new_dgram() تُرجع BIO عند النجاح وNULL عند الفشل.

BIO_ctrl_dgram_connect() وBIO_ctrl_set_connected() وBIO_dgram_set_peer() تُرجع 1 عند النجاح و0 عند الفشل.

BIO_dgram_get_peer() وBIO_dgram_detect_peer_addr() تُرجع 0 عند الفشل وعدد البايتات لتمثيل العنوان المُخرج (قيمة موجبة) عند النجاح.

BIO_dgram_recv_timedout() وBIO_dgram_send_timedout() تُرجع 0 أو 1 اعتمادًا على الظرف؛ انظر النقاش أعلاه.

BIO_dgram_get_mtu_overhead() تُرجع قيمة بالبايت.

انظر أيضًا¶

BIO_sendmmsg(3)، BIO_s_dgram_pair(3)، DTLSv1_listen(3)، bio(7)

حقوق النسخ¶

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

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

ترجمة¶

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

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

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