الاسم¶

BIO_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc, BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps, BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu, BIO_dgram_set0_local_addr - BIO زوج الرزم

موجز¶

 #include <openssl/bio.h>
 const BIO_METHOD *BIO_s_dgram_pair(void);
 int BIO_new_bio_dgram_pair(BIO **bio1, size_t writebuf1,
                            BIO **bio2, size_t writebuf2);
 int BIO_dgram_set_no_trunc(BIO *bio, int enable);
 int BIO_dgram_get_no_trunc(BIO *bio);
 uint32_t BIO_dgram_get_effective_caps(BIO *bio);
 uint32_t BIO_dgram_get_caps(BIO *bio);
 int BIO_dgram_set_caps(BIO *bio, uint32_t caps);
 int BIO_dgram_set_mtu(BIO *bio, unsigned int mtu);
 unsigned int BIO_dgram_get_mtu(BIO *bio);
 int BIO_dgram_set0_local_addr(BIO *bio, BIO_ADDR *addr);

الوصف¶

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

يُرفق زوج BIO للرزم بيانات وصفية معينة بكل كتابة، مثل عناوين المصدر والوجهة. قد تُسترجع هذه المعلومات عند القراءة.

تطبيق نموذجي لزوج BIO للرزم هو السماح لتطبيق بالاحتفاظ بكل إدخال/إخراج شبكة الرزم المطلوب بواسطة libssl تحت سيطرة التطبيق.

صُمم زوج BIO للرزم لدعم الاستخدام متعدد الخيوط حيث تُراعى قيود معينة؛ انظر الخيوط.

يسمح زوج BIO للرزم لكل نصف من الزوج بالإشارة إلى النصف الآخر حول ما إذا كان يدعم قدرات معينة؛ انظر إشارة القدرة.

تجمع الدالة BIO_new_bio_dgram_pair() استدعاءات BIO_new(3) وBIO_make_bio_pair(3) وBIO_set_write_buf_size(3) لإنشاء زوج متصل من BIOs bio1 وbio2 بأحجام مخازن كتابة writebuf1 وwritebuf2. إذا كان أي حجم صفرًا، فسيُستخدم الحجم المبدئي.

قد تُستخدم الدالة BIO_make_bio_pair(3) لربط اثنين من BIOs زوج الرزم في زوج. يجب أن يستخدم كلا BIOs الطريقة المُرجعة بواسطة BIO_s_dgram_pair() ولا يجوز أن يكون أي من BIOs مرتبطًا حاليًا في زوج.

تُدمر الدالة BIO_destroy_bio_pair(3) الارتباط بين اثنين من BIOs متصلين. تحرير أي نصف من الزوج سيدمر الارتباط آليًا.

تمسح الدالة BIO_reset(3) أي بيانات في مخزن الكتابة لـ BIO المعطى. يعني هذا أن BIO المقابل في الزوج لن يكون لديه أي بيانات تنتظر القراءة.

يحتفظ BIO بمخزن كتابة داخلي بحجم ثابت. عندما يمتلئ المخزن، ستفشل الكتابات الإضافية حتى يُفرغ المخزن عبر استدعاءات BIO_read(3). يمكن تغيير حجم المخزن باستخدام BIO_set_write_buf_size(3) والاستعلام عنه باستخدام BIO_get_write_buf_size(3).

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

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

لا يدعم هذا BIO إرسال أو استقبال رزم بطول صفري. يُعالج تمرير مخزن بطول صفري إلى BIO_write كعملية عدم فعل.

تُرجع الدالة BIO_eof(3) 1 فقط إذا كان BIO زوج الرزم المعطى غير متصل حاليًا بـ BIO نظير.

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

BIO_dgram_set_no_trunc() و BIO_ctrl_get_no_trunc() يُحددان ويسترجعان وضع الاقتطاع للنصف المُعطى من زوج رزم BIO. عندما يكون وضع عدم الاقتطاع مُفعّلاً، سيفشل BIO_read() إذا كان المخزن المُقدم غير كافٍ لاحتواء الرزمة التالية المراد قراءتها. إذا كان وضع عدم الاقتطاع معطلاً (المبدئي)، ستُقتطع الرزمة بصمت. هذا السلوك المبدئي يحافظ على التوافق مع دلالات واجهة برمجة مقابس Berkeley.

BIO_dgram_set_mtu() و BIO_dgram_get_mtu() قد يُستخدمان لتعيين قيمة MTU إعلامية على زوج رزم BIO. إذا استُخدم BIO_dgram_set_mtu() على BIO هو حاليًا جزء من زوج رزم BIO، تُعيّن قيمة MTU على كلا نصفي الزوج. القيمة لا تؤثر على تشغيل زوج رزم BIO (باستثناء BIO_get_write_guarantee()؛ انظر أعلاه) ولكن قد تُستخدم بواسطة كود آخر لتحديد MTU مطلوب. عندما يُنشأ BIO لزوج رزم BIO، تُعيّن MTU إلى قيمة غير محددة ولكن صالحة.

BIO_dgram_set0_local_addr() يمكن استخدامه لتعيين BIO_ADDR المحلي الذي سيُستخدم عند إرسال رزمة عبر زوج رزم BIO. يصبح هذا عنوان النظير عند الاستقبال على النصف الآخر من الزوج. إذا استُخدم BIO في استدعاء لـ BIO_sendmmsg(3) وعُيّن عنوان محلي صراحةً، فإن العنوان المحلي المُحدد صراحةً يأخذ الأولوية. يُمرر المرجع إلى BIO_ADDR إلى BIO بواسطة هذا الاستدعاء وسيُحرر آليًا عندما يُحرر BIO.

BIO_flush(3) هو عملية لا تفعل شيئًا.

ملاحظات¶

أنصاف زوج رزم BIO لها أعمار مستقلة ويجب تحريرها بشكل منفصل.

الخيوط¶

BIO_recvmmsg(3), BIO_sendmmsg(3), BIO_read(3), BIO_write(3), BIO_pending(3), BIO_get_write_guarantee(3) و BIO_flush(3) قد تُستخدم بواسطة خيوط متعددة في وقت واحد على نفس زوج رزم BIO. عمليات BIO_ctrl(3) المحددة (وهي BIO_CTRL_PENDING, BIO_CTRL_FLUSH و BIO_C_GET_WRITE_GUARANTEE) قد تُستخدم أيضًا. استدعاء أي استدعاء BIO آخر، أو أي عملية BIO_ctrl(3) أخرى، على أي نصف من زوج رزم BIO بينما أي استدعاء BIO آخر قيد التقدم على أي نصف من نفس زوج رزم BIO يؤدي إلى سلوك غير محدد.

إشارة القدرة¶

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

كل نصف من زوج رزم BIO يمكن أن تُعيّن عليه أعلام قدرة تشير إلى ما إذا كانت عناوين المصدر والوجهة ستُلتزم بها من قبل القارئ وما إذا كانت ستُقدم من قبل الكاتب. يجب تعيين أعلام القدرة هذه عبر استدعاء لـ BIO_dgram_set_caps()، وستنعكس هذه القدرات في القيمة التي يُرجعها BIO_dgram_get_effective_caps() على BIO المقابل. إذا لزم الأمر، يمكن استرجاع قيمة القدرة المُعينة سابقًا باستخدام BIO_dgram_get_caps(). لاحظ أن BIO_dgram_set_caps() على BIO معين يتحكم في القدرات المُعلن عنها للنظير، و BIO_dgram_get_effective_caps() على BIO معين يحدد القدرات المُعلن عنها من قبل نظير ذلك BIO.

القدرات التالية متاحة:

BIO_DGRAM_CAP_HANDLES_SRC_ADDR

مستخدم BIO زوج الرزم يعد بالالتزام بعناوين المصدر المقدمة مع الرزم المكتوبة إلى زوج BIO.

BIO_DGRAM_CAP_HANDLES_DST_ADDR

مستخدم BIO زوج الرزم يعد بالالتزام بعناوين الوجهة المقدمة مع الرزم المكتوبة إلى زوج BIO.

BIO_DGRAM_CAP_PROVIDES_SRC_ADDR

يعلن مستخدم BIO الزوجي للبيانات المُجزّأة عن توفيره معلومات عنوان المصدر مع عمليات الكتابة المستقبلية إلى زوج BIO، حيثما أمكن.

BIO_DGRAM_CAP_PROVIDES_DST_ADDR

يعلن مستخدم BIO الزوجي للبيانات المُجزّأة عن توفيره معلومات عنوان الوجهة مع عمليات الكتابة المستقبلية إلى زوج BIO، حيثما أمكن.

إذا حاول المُستدعي تحديد عنوان وجهة (مثلاً، باستخدام BIO_sendmmsg(3)) ولم يُعلن النظير عن إمكانية BIO_DGRAM_CAP_HANDLES_DST_ADDR، تفشل العملية. وبالتالي، التفاوض على الإمكانيات إلزامي.

إذا حاول المُستدعي تحديد عنوان مصدر عند الكتابة، أو طلب عنوان وجهة عند الاستقبال، ولم يتم تمكين دعم العنوان المحلي، تفشل العملية؛ انظر BIO_dgram_set_local_addr_enable(3).

إذا حاول المُستدعي تمكين دعم العنوان المحلي باستخدام BIO_dgram_set_local_addr_enable(3) ولم يُرجع BIO_dgram_get_local_addr_cap(3) القيمة 1 (مما يعني أن النظير لم يُعلن عن كل من إمكانية BIO_DGRAM_CAP_HANDLES_SRC_ADDR وإمكانية BIO_DGRAM_CAP_PROVIDES_DST_ADDR)، تفشل العملية.

يشير BIO_DGRAM_CAP_PROVIDES_SRC_ADDR وBIO_DGRAM_CAP_PROVIDES_DST_ADDR إلى أن التطبيق الذي يستخدم ذلك النصف من زوج BIO للبيانات المُجزّأة يعد بتوفير عناوين المصدر والوجهة على التوالي عند كتابة البيانات المُجزّأة إلى ذلك النصف من زوج BIO للبيانات المُجزّأة. ومع ذلك، لا تؤثر أعلام الإمكانيات هذه على سلوك زوج BIO للبيانات المُجزّأة.

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

يُرجع BIO_new_bio_dgram_pair() القيمة 1 عند النجاح، مع توفر BIOs الجديدة في bio1 وbio2، أو القيمة 0 عند الفشل، مع تخزين مؤشرات NULL في مواقع bio1 وbio2. افحص مكدس الأخطاء لمزيد من المعلومات.

يُرجع BIO_dgram_set_no_trunc() وBIO_dgram_set_caps() وBIO_dgram_set_mtu() القيمة 1 عند النجاح والقيمة 0 عند الفشل.

يُرجع BIO_dgram_get_no_trunc() القيمة 1 إذا تم تمكين وضع عدم الاقتطاع على BIO، أو القيمة 0 إذا لم يتم تمكين وضع عدم الاقتطاع أو غير مدعوم على BIO معين.

يُرجع BIO_dgram_get_effective_caps() وBIO_dgram_get_caps() القيمة صفر إذا لم يتم دعم أي إمكانيات.

يُرجع BIO_dgram_get_mtu() قيمة MTU المُهيأة على BIO، أو القيمة صفر إذا كانت العملية غير مدعومة.

يُرجع BIO_dgram_set0_local_addr() القيمة 1 عند النجاح والقيمة <= 0 بخلاف ذلك.

انظر أيضًا¶

BIO_s_bio(3), bio(7)

التاريخ¶

أُضيفت BIO_s_dgram_pair() وBIO_new_bio_dgram_pair() وBIO_dgram_get_caps() وBIO_dgram_get_effective_caps() وBIO_dgram_get_no_trunc() وBIO_dgram_set_caps() وBIO_dgram_set_mtu() وBIO_dgram_set_no_trunc() في OpenSSL 3.2.

أُضيفت BIO_dgram_set0_local_addr() في OpenSSL 3.5.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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