الاسم¶

BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn \&- دوال استدعاء BIO

موجز¶

 #include <openssl/bio.h>
 typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
                                    size_t len, int argi,
                                    long argl, int ret, size_t *processed);
 void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
 BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
 void BIO_set_callback_arg(BIO *b, char *arg);
 char *BIO_get_callback_arg(const BIO *b);
 long BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len,
                            int argi, long argl, int ret, size_t *processed);

الدوال التالية أصبحت مهجورة منذ OpenSSL 3.0، ويمكن إخفاؤها تماماً عن طريق تعريف OPENSSL_API_COMPAT بقيمة إصدار مناسبة، انظر openssl_user_macros(7):

 typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
                                 long argl, long ret);
 void BIO_set_callback(BIO *b, BIO_callback_fn cb);
 BIO_callback_fn BIO_get_callback(const BIO *b);
 long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
                         long argl, long ret);
 typedef struct bio_mmsg_cb_args_st {
     BIO_MSG    *msg;
     size_t      stride, num_msg;
     uint64_t    flags;
     size_t     *msgs_processed;
 } BIO_MMSG_CB_ARGS;

الوصف¶

\&BIO_set_callback_ex() و BIO_get_callback_ex() يضبطان ويستعيدان استدعاء BIO. يُستدعى الاستدعاء خلال معظم عمليات BIO عالية المستوى. يمكن استخدامه لأغراض التصحيح لتتبع العمليات على BIO أو لتعديل تشغيله.

\&BIO_set_callback() و BIO_get_callback() يضبطان ويستعيدان استدعاء BIO بالتنسيق القديم. لا ينبغي للكود الجديد استخدام هذه الدوال، لكنها محفوظة للتوافق العكسي. أي استدعاء يُضبط عبر BIO_set_callback_ex() سيُستدعى بأفضلية على أي استدعاء يُضبط بواسطة BIO_set_callback().

\&BIO_set_callback_arg() و BIO_get_callback_arg() هما وحدتان ماكرو يمكن استخدامهما لضبط واستعادة وسيط للاستخدام في الاستدعاء.

\&BIO_debug_callback_ex() هو استدعاء تصحيح قياسي يطبع معلومات متعلقة بكل عملية BIO. إذا ضُبط وسيط الاستدعاء، يُفسر على أنه BIO لإرسال المعلومات إليه، وإلا يُستخدم stderr. دالة BIO_debug_callback() هي النسخة المهملة من نفس الاستدعاء للاستخدام مع دالة تنسيق الاستدعاء القديم BIO_set_callback().

BIO_callback_fn_ex هو نوع دالة الاستدعاء و BIO_callback_fn هو نوع دالة الاستدعاء بالتنسيق القديم. معنى كل وسيط موصوف أدناه:

b

BIO الذي يُرفق به الاستدعاء يُمرر في b.

oper

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

len

طول البيانات المطلوب قراءتها أو كتابتها. هذا مفيد فقط إذا كان \&oper هو BIO_CB_READ أو BIO_CB_WRITE أو BIO_CB_GETS.

argp argi argl

معنى الوسائط argp وargi وargl يعتمد على قيمة oper، أي العملية المنفذة.

processed

processed مؤشر إلى موقع يُحدّث بمقدار البيانات التي قُرئت أو كُتبت فعلياً. يُستخدم فقط لـ BIO_CB_READ وBIO_CB_WRITE وBIO_CB_GETS وBIO_CB_PUTS.

ret

ret قيمة الإرجاع التي كانت سترجع إلى التطبيق لو لم يكن هناك دالة استدعاء. القيمة الفعلية المرجعة هي قيمة إرجاع دالة الاستدعاء نفسها. في حالة دوال الاستدعاء المستدعاة قبل عملية BIO الفعلية، توضع 1 في ret، وإذا لم تكن قيمة الإرجاع موجبة، ترجع فوراً إلى التطبيق ولا تنفذ عملية BIO.

يجب أن ترجع دالة الاستدعاء عادةً ret ببساطة عند انتهاء المعالجة، إلا إذا أرادت تحديداً تعديل القيمة المرجعة إلى التطبيق.

عمليات دالة الاستدعاء¶

في الملاحظات أدناه، يشير callback إلى دالة الاستدعاء الفعلية المستدعاة.

BIO_free(b)

 callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
    

أو

 callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
    

تُستدعى قبل عملية التحرير.

BIO_read_ex(b, data, dlen, readbytes)

 callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, NULL)
    

أو

 callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
    

يُستدعى قبل القراءة و

 callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
             &readbytes)
    

أو

 callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
    

بعد.

BIO_write(b, data, dlen, written)

 callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL)
    

أو

 callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
    

يُستدعى قبل الكتابة و

 callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue,
             &written)
    

أو

 callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
    

بعد.

BIO_gets(b, buf, size)

 callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
    

أو

 callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
    

يُستدعى قبل العملية و

 callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue,
             &readbytes)
    

أو

 callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
    

بعد.

BIO_puts(b, buf)

 callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
    

أو

 callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
    

يُستدعى قبل العملية و

 callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, &written)
    

أو

 callback(b, BIO_CB_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue)
    

بعد.

BIO_ctrl(BIO *b, int cmd, long larg, void *parg)

 callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
    

أو

 callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
    

يُستدعى قبل الاستدعاء و

 callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
    

أو

 callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
    

بعد.

ملاحظة: cmd == BIO_CTRL_SET_CALLBACK خاص، لأن parg ليس وسيطًا من النوع BIO_info_cb نفسه. في هذه الحالة parg مؤشر إلى معامل الاستدعاء الفعلي، انظر BIO_callback_ctrl.

BIO_sendmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)

  callback_ex(b, BIO_CB_SENDMMSG, args, 0, 0, 0, 1, NULL)
    

أو

  callback(b, BIO_CB_SENDMMSG, args, 0, 0, 1)
    

يُستدعى قبل الاستدعاء و

  callback_ex(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret, NULL)
    

أو

  callback(b, BIO_CB_SENDMMSG | BIO_CB_RETURN, args, ret, 0, 0, ret)
    

بعد.

args مؤشر إلى بنية BIO_MMSG_CB_ARGS تحتوي على الوسائط الممررة إلى BIO_sendmmsg(). ret قيمة الإرجاع لاستدعاء BIO_sendmmsg(). قيمة إرجاع BIO_sendmmsg() تُغير إلى القيمة التي أرجعها استدعاء BIO_CB_SENDMMSG | BIO_CB_RETURN.

BIO_recvmmsg(BIO *b, BIO_MSG *msg, size_t stride, size_t num_msg, uint64_t flags, size_t *msgs_processed)

انظر التوثيق لـ BIO_sendmmsg(). تعمل BIO_recvmmsg() بشكل مطابق باستثناء أن BIO_CB_RECVMMSG يُستخدم بدلاً من BIO_CB_SENDMMSG.

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

تُرجع BIO_get_callback_ex() و BIO_get_callback() دالة الاستدعاء التي وُضعت سابقًا باستدعاء BIO_set_callback_ex() و BIO_set_callback() على التوالي.

تُرجع BIO_get_callback_arg() مؤشر char إلى القيمة التي وُضعت سابقًا عبر استدعاء BIO_set_callback_arg().

تُرجع BIO_debug_callback() 1 أو ret إذا استُدعيت بعد عمليات BIO محددة.

أمثلة¶

دالة BIO_debug_callback_ex() هي مثال، مصدرها في crypto/bio/bio_cb.c

التاريخ¶

أُضيفت دالة BIO_debug_callback_ex() في OpenSSL 3.0.

أُهملت BIO_set_callback() و BIO_get_callback() و BIO_debug_callback() في OpenSSL 3.0. استخدم دوال _ex غير المُهملة بدلاً منها.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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