الاسم¶

BIO_s_secmem, BIO_s_dgram_mem, BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, BIO_get_mem_ptr, BIO_new_mem_buf - BIO الذاكرة

موجز¶

 #include <openssl/bio.h>
 const BIO_METHOD *BIO_s_mem(void);
 const BIO_METHOD *BIO_s_dgram_mem(void);
 const BIO_METHOD *BIO_s_secmem(void);
 BIO_set_mem_eof_return(BIO *b, int v);
 long BIO_get_mem_data(BIO *b, char **pp);
 BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c);
 BIO_get_mem_ptr(BIO *b, BUF_MEM **pp);
 BIO *BIO_new_mem_buf(const void *buf, int len);

الوصف¶

BIO_s_mem() تُرجع دالة طريقة BIO الذاكرة.

BIO الذاكرة هي BIO مصدر/مصرف تستخدم الذاكرة لإدخال/إخراجها. تُخزَّن البيانات المكتوبة إلى BIO الذاكرة في بنية BUF_MEM التي تُوسَّع حسب الحاجة لاستيعاب البيانات المخزنة.

BIO_s_secmem() مثل BIO_s_mem() باستثناء أن الكومة الآمنة تُستخدم لتخزين المخزن المؤقت.

BIO_s_dgram_mem() هي BIO ذاكرة تحترم دلالات الرزم. استدعاء واحد لـ BIO_write(3) سيكتب رزمة واحدة إلى BIO الذاكرة. استدعاء لاحق لـ BIO_read(3) سيقرأ البيانات في تلك الرزمة. استدعاء BIO_read(3) لن يُرجع أبدًا بيانات أكثر مما كُتب في استدعاء BIO_write(3) الأصلي حتى لو وُجدت استدعاءات BIO_write(3) لاحقة كتبت رزمًا إضافية. كل استدعاء متتالٍ لـ BIO_read(3) سيقرأ الرزمة التالية. إذا زوّد استدعاء BIO_read(3) مخزن قراءة أصغر من حجم الرزمة، فسيُملأ مخزن القراءة بالكامل وتُتجاهل البيانات المتبقية من الرزمة.

لا يمكن كتابة رزمة بطول صفري. استدعاء BIO_write(3) في هذه الحالة سيُرجع 0 ولن تُكتب أي رزم. استدعاء BIO_read(3) عندما لا توجد رزم في BIO للقراءة سيُرجع نتيجة سالبة وتُضبط أعلام "إعادة المحاولة" (أي استدعاء BIO_should_retry(3) سيُرجع صحيحًا). BIO رزم الذاكرة لن تُرجع أبدًا صحيحًا من BIO_eof(3).

يمكن استدعاء أي بيانات كُتبت إلى BIO الذاكرة بقراءتها منها. ما لم تكن BIO الذاكرة للقراءة فقط، فتُحذف أي بيانات تُقرأ منها من BIO.

BIOs الذاكرة باستثناء BIO_s_dgram_mem() تدعم BIO_gets() و BIO_puts().

BIO_s_dgram_mem() تدعم استدعاءات BIO_sendmmsg(3) و BIO_recvmmsg(3) والاستدعاءات المتعلقة بـ BIO_ADDR ومعالجة MTU بشكل مشابه لـ BIO_s_dgram_pair(3).

إذا ضُبط علم BIO_CLOSE عند تحرير BIO ذاكرة، فتُحرر أيضًا بنية BUF_MEM الأساسية.

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

BIO_eof() صحيح إذا لم توجد بيانات في BIO.

BIO_ctrl_pending() تُرجع عدد البايتات المخزنة حاليًا.

BIO_set_mem_eof_return() تضبط سلوك BIO الذاكرة b عندما تكون فارغة. إذا كان v صفرًا، فستُرجع BIO الذاكرة الفارغة EOF (أي ستُرجع صفرًا وستكون BIO_should_retry(b) خاطئة). إذا كان v غير صفري، فستُرجع v عندما تكون فارغة وستضبط علم إعادة محاولة القراءة (أي BIO_read_retry(b) صحيحة). لتجنب الغموض مع قيمة إرجاع موجبة عادية، يجب ضبط v على قيمة سالبة، عادةً -1. استدعاء هذه الكلية سيفشل لـ BIOs رزم الذاكرة.

BIO_get_mem_data() تضبط *pp على مؤشر لبداية بيانات BIO الذاكرة وتُرجع الكمية الإجمالية للبيانات المتاحة. نُفذت ككلية. لاحظ أن المؤشر الذي يُرجعه هذا الاستدعاء إعلامي، ولا يُقصد به نقل ملكية هذه الذاكرة. انظر الملاحظات على BIO_set_close().

BIO_set_mem_buf() تُعيّن بنية BUF_MEM الداخلية إلى bm وتُعيّن علم الإغلاق إلى c، أي يجب أن يكون c إما BIO_CLOSE أو BIO_NOCLOSE. وهي دالة كليّة.

BIO_get_mem_ptr() تضع بنية BUF_MEM الأساسية في *pp. وهي دالة كليّة.

BIO_new_mem_buf() تُنشئ BIO ذاكرة باستخدام len بايت من البيانات في buf، إذا كان len هو -1 فسيُفترض أن buf منتهية بصفر وتُحدد طولها بواسطة strlen. تُعيّن BIO إلى حالة قراءة فقط ونتيجة لذلك لا يمكن الكتابة إليها. هذا مفيد عندما تحتاج بعض البيانات إلى الإتاحة من منطقة ذاكرة ثابتة في شكل BIO. تُقرأ البيانات المقدمة مباشرة من المخزن المؤقت المقدم: لا تُنسخ أولاً، لذا يجب أن تبقى منطقة الذاكرة المقدمة دون تغيير حتى تُحرر BIO.

جميع الدوال الخمس الموصوفة أعلاه تُرجع خطأ مع BIO_s_dgram_mem().

ملاحظات¶

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

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

استدعاء BIO_set_mem_buf() على BIO secmem أو dgram سيعطي نتائج غير محددة، بما في ذلك ربما تعطل البرنامج.

تبديل BIO ذاكرة من قراءة-كتابة إلى قراءة فقط غير مدعوم ويمكن أن يعطي نتائج غير محددة بما في ذلك تعطل البرنامج. هناك استثناءان ملحوظان للقاعدة. الأول هو تعيين مخزن ذاكرة ثابت فور إنشاء BIO وتعيين BIO كقراءة فقط.

التسلسل الآخر المدعوم هو البدء بـ BIO قراءة-كتابة ثم تبديلها مؤقتًا إلى قراءة فقط واستدعاء BIO_reset() على BIO القراءة فقط فورًا قبل تبديلها مرة أخرى إلى قراءة-كتابة. قبل تحرير BIO، يجب تبديلها مرة أخرى إلى وضع القراءة-الكتابة.

استدعاء BIO_get_mem_ptr() على BIO قراءة فقط سيرجع BUF_MEM يحتوي فقط على البيانات المتبقية للقراءة. إذا عُيّنت حالة إغلاق BIO إلى BIO_NOCLOSE، قبل تحرير BUF_MEM يجب تعيين مؤشر البيانات فيه إلى NULL لأن مؤشر البيانات لا يشير إلى ذاكرة مخصصة.

استدعاء BIO_reset() على BIO ذاكرة قراءة-كتابة مع تعيين علم BIO_FLAGS_NONCLEAR_RST يمكن أن يكون له نتيجة غير متوقعة عندما تكون القراءات والكتابات إلى BIO متداخلة. كما هو موثق أعلاه، ستُعاد تعيين BIO إلى الحالة بعد آخر عملية كتابة مكتملة. لا يمكن التراجع عن تأثيرات القراءات السابقة لعملية الكتابة تلك.

استدعاء BIO_get_mem_ptr() قبل استدعاء BIO_reset() مع تعيين BIO_FLAGS_NONCLEAR_RST له نفس تأثير عملية كتابة.

استدعاء BIO_set_close() مع BIO_NOCLOSE يُيتم BUF_MEM الداخلي لـ BIO، _وليس_ مخزن البيانات الفعلي. راجع قسم الأمثلة للطريقة الصحيحة للمطالبة بملكية مؤشر البيانات لعملية تحرير مؤجلة.

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

BIO_s_mem() و BIO_s_dgram_mem() و BIO_s_secmem() تُرجع بنية BIO_METHOD ذاكرة صالحة.

BIO_set_mem_eof_return() و BIO_set_mem_buf() و BIO_get_mem_ptr() تُرجع 1 عند النجاح أو قيمة أقل من أو تساوي 0 إذا حدث خطأ.

BIO_get_mem_data() تُرجع العدد الإجمالي للبايتات المتاحة عند النجاح، 0 إذا كان b NULL، أو قيمة سالبة في حالة أخطاء أخرى.

BIO_new_mem_buf() تُرجع بنية BIO صالحة عند النجاح أو NULL عند الخطأ.

أمثلة¶

إنشاء BIO ذاكرة وكتابة بعض البيانات إليها:

 BIO *mem = BIO_new(BIO_s_mem());
 BIO_puts(mem, "Hello World\n");

إنشاء BIO ذاكرة للقراءة فقط:

 char data[] = "Hello World";
 BIO *mem = BIO_new_mem_buf(data, -1);

استخرج بنية BUF_MEM من BIO الذاكرة ثم حرر BIO:

 BUF_MEM *bptr;
 BIO_get_mem_ptr(mem, &bptr);
 BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
 BIO_free(mem);

استخرج مؤشر BUF_MEM، ادع ملكية البيانات الداخلية وحرر BIO وبنية BUF_MEM:

 BUF_MEM *bptr;
 char *data;
 BIO_get_mem_data(bio, &data);
 BIO_get_mem_ptr(bio, &bptr);
 BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free orphans BUF_MEM */
 BIO_free(bio);
 bptr->data = NULL; /* Tell BUF_MEM to orphan data */
 BUF_MEM_free(bptr);
 ...
 free(data);

التاريخ¶

BIO_s_dgram_mem() أُضيف في OpenSSL 3.2.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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