تجريدات بروتوكول التحكم بالنقل

تتضمن هذه الوحدة تجريدات سهلة الاستخدام على سطح واجهة برمجة تطبيقات TCP الأساسية.

ملخّص

عمليات التعداد
anonymous enum تعداد
يحدِّد العلامات التي تم تمريرها إلى otTcpCircularSendBufferWrite.

تحديدات النوع
otTcpCircularSendBuffer typedef
يمثل مخزنًا مؤقتًا للإرسال دائريًا لاستخدامه مع نقطة نهاية بروتوكول التحكم بالنقل.
otTcpEndpointAndCircularSendBuffer typedef
بنية السياق المراد استخدامها مع mbedtls_ssl_set_bio.

الدوال
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)
إلغاء تهيئة المخزن المؤقت لإرسال الإرسال الدائري عبر بروتوكول التحكم بالنقل، وفصله عند توصيله.
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)
void
يتجاهل جميع البيانات بالقوة في المخزن المؤقت للإرسال الدائري.
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)
size_t
لعرض مقدار المساحة الحرة في المخزن المؤقت للإرسال الدائري لبروتوكول TCP.
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)
void
لتنفيذ معالجة خاصة بالإرسال الدائري للمخزن المؤقت في معاودة الاتصال otTcpForwardProgress.
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)
void
تهيئة المخزن المؤقت للإرسال الدائري في بروتوكول التحكم بالنقل.
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)
يرسل البيانات على نقطة نهاية TCP، باستخدام المخزن المؤقت للإرسال الدائري لبروتوكول TCP المقدَّم لإدارة التخزين المؤقت.
otTcpMbedTlsSslRecvCallback(void *aCtx, unsigned char *aBuf, size_t aLen)
int
يتم معاودة الاتصال بدون حظر لتمريره إلى mbedtls_ssl_set_bio.
otTcpMbedTlsSslSendCallback(void *aCtx, const unsigned char *aBuf, size_t aLen)
int
يتم إرسال معاودة الاتصال بدون حظر لتمريرها إلى mbedtls_ssl_set_bio.

الهياكل
otTcpCircularSendBuffer

يمثل مخزنًا مؤقتًا للإرسال دائريًا لاستخدامه مع نقطة نهاية بروتوكول التحكم بالنقل.

otTcpEndpointAndCircularSendBuffer

بنية السياق المراد استخدامها مع mbedtls_ssl_set_bio.

عمليات التعداد

تعداد مجهول

 anonymous enum

يحدِّد العلامات التي تم تمريرها إلى otTcpCircularSendBufferWrite.

تحديدات النوع

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

يمثل مخزنًا مؤقتًا للإرسال دائريًا لاستخدامه مع نقطة نهاية بروتوكول التحكم بالنقل.

يعد استخدام مخزن مؤقت دائري للإرسال اختياريًا. يمكن للتطبيقات استخدام نقطة نهاية بروتوكول التحكم بالنقل لإرسال البيانات من خلال إدارة otLinkedBuffers مباشرةً. ومع ذلك، قد يكون من الأسهل استخدام مخزن إرسال مؤقت دائري، حيث يمكن لهذه التطبيقات استدعاء الدالة otTcpCircularSendBufferWrite() لـ "إرفاق" مخزن إرسال دائري دائري إلى نقطة نهاية بروتوكول التحكم بالنقل وإرسال البيانات من نقطة نهاية بروتوكول التحكم في الإرسال (TCP) هذه، اعتمادًا على مخزن الإرسال الدائري لإدارة نقاط الاتصال otLinkedBuffer الأساسية.

يتم تنفيذ otTcpCircularSendBuffer على واجهة برمجة التطبيقات المستندة إلى otLinkedBuffer التي توفّرها otTcpEndpoint. بعد الإرفاق بـ otTcpEndpoint، ينفِّذ otTcpCircularSendBuffer جميع مهام إدارة otLinkedBuffers للاتصال. وهذا يعني أنّه بعد إرفاق otTcpCircularSendBuffer بعنصر otTcpEndpoint، يجب ألا يستدعي التطبيق otTcpSendByReference() أو otTcpSendByExtension() على ذلك otTcpEndpoint. بدلاً من ذلك، يجب أن يستخدم التطبيق otTcpCircularSendBufferWrite() لإضافة البيانات إلى المخزن المؤقت للإرسال.

استدعاء otTcpForwardProgress() هو الطريقة المقصودة لمعرفة المستخدمين عند توفُّر مساحة في المخزن المؤقت للإرسال الدائري. في otTcpEndpoint الذي تم إرفاق otTcpCircularSendBuffer به، يجب أن يثبّت التطبيق معاودة الاتصال otTcpForwardProgress() ويستدعي otTcpCircularSendBufferHandleForwardProgress() في otTcpCircularSendBuffer المرفق في بداية دالة معاودة الاتصال. ننصح بعدم تثبيت المستخدم استدعاء otTcpSendDone()، لأنّه تتم معالجة جميع عمليات إدارة otLinkedBuffers بواسطة المخزن المؤقت للإرسال الدائري.

يجب ألا يفحص التطبيق حقول هذه البنية مباشرةً، بل يجب أن يتفاعل معها فقط من خلال وظائف واجهة برمجة التطبيقات TCP Circular Send Buffer التي يتم تقديم توقيعها في هذا الملف.

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

بنية السياق المراد استخدامها مع mbedtls_ssl_set_bio.

الدوال

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

إلغاء تهيئة المخزن المؤقت لإرسال الإرسال الدائري عبر بروتوكول التحكم بالنقل، وفصله عند توصيله.

إذا كان المخزن المؤقت للإرسال الدائري في بروتوكول التحكم بالنقل فارغًا، فسيتعذّر إتمام هذه العملية.

التفاصيل
المَعلمات
[in] aSendBuffer
يتم إلغاء المخزن المؤقت لإرسال الإرسال الدائري لبروتوكول TCP.
قيم الإرجاع
OT_ERROR_NONE
بنجاح إلغاء تهيئة المخزن المؤقت للإرسال الدائري لبروتوكول TCP.
OT_ERROR_BUSY
يحتوي المخزن المؤقت الدائري على بيانات ولا يمكن إلغاء إعداده.

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

يتجاهل جميع البيانات بالقوة في المخزن المؤقت للإرسال الدائري.

من المتوقّع أن يستدعي التطبيق هذه الدالة عند إنهاء اتصال بروتوكول التحكم بالنقل (TCP) بشكل غير رسمي (على سبيل المثال، إذا استدعى التطبيق otTcpEndpointAbort() أو تم إبلاغه بالاتصال بإعادة الضبط من خلال استدعاء otTcpConnectionLost()).

ينتج عن استدعاء هذه الدالة على خادم TCP الدائري غير الفارغة المتصل بنقطة نهاية TCP سلوك غير معروف.

التفاصيل
المَعلمات
[in] aSendBuffer
المخزن المؤقت للإرسال الدائري لبروتوكول التحكم في الإرسال (TCP) الذي يتم تجاهل بياناته.

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

لعرض مقدار المساحة الحرة في المخزن المؤقت للإرسال الدائري لبروتوكول TCP.

ستنجح هذه العملية دائمًا.

التفاصيل
المَعلمات
[in] aSendBuffer
مؤشر إلى المخزن المؤقت للإرسال الدائري لبروتوكول التحكم في الإرسال، الذي يكون مقدار المساحة الحرة المطلوب إرجاعه.
المرتجعات
مقدار المساحة الخالية في المخزن المؤقت للإرسال.

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

لتنفيذ معالجة خاصة بالإرسال الدائري للمخزن المؤقت في معاودة الاتصال otTcpForwardProgress.

من المتوقع أن يثبِّت التطبيق استدعاء otTcpForwardProgress() على otTcpEndpoint، ويطلب هذه الدالة في بداية دالة الاستدعاء لإجراء معالجة خاصة بمخزن مؤقّت لإرسال المخزن المؤقت.

في دالة رد الاتصال، يمكن للتطبيق تحديد مقدار المساحة الخالية في المخزن المؤقت للإرسال الدائري من خلال استدعاء otTcpCircularSendBufferFreeSpace()، أو من خلال مقارنة aInSendBuffer بسعة المخزن المؤقت للإرسال التي يختارها المستخدم عند استدعاء otTcpCircularSendBufferInitialize().

التفاصيل
المَعلمات
[in] aSendBuffer
مؤشر يشير إلى المخزن المؤقت للإرسال الدائري في بروتوكول التحكم بالنقل لنقطة النهاية التي تم استدعاء otTcpForwardProgress() لها.
[in] aInSendBuffer
تم تمرير قيمة aInSendBuffer إلى معاودة الاتصال otTcpForwardProgress().

otTcpCircularSendBufferInitialize

void otTcpCircularSendBufferInitialize(
  otTcpCircularSendBuffer *aSendBuffer,
  void *aDataBuffer,
  size_t aCapacity
)

تهيئة المخزن المؤقت للإرسال الدائري في بروتوكول التحكم بالنقل.

التفاصيل
المَعلمات
[in] aSendBuffer
مؤشر إلى المخزن المؤقت للإرسال الدائري لبروتوكول TCP للتهيئة.
[in] aDataBuffer
مؤشر إلى الذاكرة للاستخدام في تخزين البيانات في المخزن المؤقت للإرسال الدائري في بروتوكول التحكم بالنقل.
[in] aCapacity
سعة المخزن المؤقت للإرسال الدائري لبروتوكول TCP، بالبايت، والذي يجب أن يساوي حجم الذاكرة المشار إليها بـ aDataBuffer .

otTcpCircularSendBufferWrite

otError otTcpCircularSendBufferWrite(
  otTcpEndpoint *aEndpoint,
  otTcpCircularSendBuffer *aSendBuffer,
  const void *aData,
  size_t aLength,
  size_t *aWritten,
  uint32_t aFlags
)

يرسل البيانات على نقطة نهاية TCP، باستخدام المخزن المؤقت للإرسال الدائري لبروتوكول TCP المقدَّم لإدارة التخزين المؤقت.

بعد استدعاء هذه الدالة، يتم اعتبار aSendBuffer وaEndpoint "مرتبطتين" ببعضهما البعض. في حين أنها مرفقة، يجب إجراء جميع عمليات الإرسال لـ aEndpoint باستخدام aSendBuffer ويجب أن ترتبط جميع العمليات على aSendBuffer بـ aEndpoint .

الطريقة الوحيدة "لفصل" المخزن المؤقت للإرسال الدائري في بروتوكول التحكم بالنقل ونقطة نهاية TCP هي الانتظار حتى يصبح المخزن المؤقت للإرسال فارغًا تمامًا. يمكن أن يحدث ذلك بطريقتين: (1) يتم إرسال جميع البيانات في المخزن المؤقت للإرسال والاعتراف بها خلال المسار الطبيعي لتشغيل بروتوكول TCP أو (2) إنهاء الاتصال.

يتمثّل نمط الاستخدام الموصى به في استخدام مخزن إرسال مؤقت دائري واحد لبروتوكول TCP مع نقطة نهاية بروتوكول التحكم بالنقل، وإرسال البيانات على نقطة نهاية TCP هذه فقط عبر المخزن المؤقت الدائري لبروتوكول TCP المرتبط بها. يتجنّب نمط الاستخدام المقترَح هذا المشاكل الموضَّحة أعلاه، وذلك من خلال استخدام نقطة نهاية بروتوكول التحكم بالنقل والتخزين المؤقت للإرسال الدائري لبروتوكول التحكم في الإرسال معًا.

إذا وصل المخزن المؤقت للإرسال الدائري إلى السعة، يتم نسخ بادئة البيانات المتوفرة فقط إلى المخزن المؤقت للإرسال الدائري.

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP التي يجب إرسال البيانات عليها.
[in] aSendBuffer
المخزن المؤقت للإرسال الدائري لبروتوكول التحكم في الإرسال (TCP) يتم نسخ البيانات إليه.
[in] aData
مؤشر إلى البيانات المراد نسخها إلى المخزن المؤقت للإرسال الدائري لبروتوكول التحكم بالنقل.
[in] aLength
طول البيانات المشار إليها بواسطة aData للنسخ في المخزن المؤقت للإرسال الدائري لبروتوكول التحكم بالنقل.
[out] aWritten
تتم تعبئتها بكمية البيانات المنسوخة في المخزن المؤقت للإرسال، والذي قد يكون أقل من aLength في حال وصول المخزن المؤقت للإرسال إلى السعة.
[in] aFlags
علامات تحدد الخيارات لهذه العملية (راجع التعداد أعلاه).
قيم الإرجاع
OT_ERROR_NONE
تم نسخ البيانات بنجاح إلى المخزن المؤقت للإرسال وإرسالها إلى نقطة نهاية بروتوكول التحكم بالنقل.
OT_ERROR_FAILED
تعذَّر إرسال البيانات على نقطة نهاية TCP.

otTcpMbedTlsSslRecvCallback

int otTcpMbedTlsSslRecvCallback(
  void *aCtx,
  unsigned char *aBuf,
  size_t aLen
)

يتم معاودة الاتصال بدون حظر لتمريره إلى mbedtls_ssl_set_bio.

التفاصيل
المَعلمات
[in] aCtx
مؤشر يشير إلى otTcpEndpointAndCircularSendBuffer.
[out] aBuf
المورد الاحتياطي المراد تلقي البيانات عليه.
[in] aLen
تمثّل هذه السمة الحد الأقصى لحجم البيانات التي يمكن تلقّيها.
المرتجعات
عدد وحدات البايت التي تم استلامها أو رمز خطأ mbedtls.

otTcpMbedTlsSslSendCallback

int otTcpMbedTlsSslSendCallback(
  void *aCtx,
  const unsigned char *aBuf,
  size_t aLen
)

يتم إرسال معاودة الاتصال بدون حظر لتمريرها إلى mbedtls_ssl_set_bio.

التفاصيل
المَعلمات
[in] aCtx
مؤشر يشير إلى otTcpEndpointAndCircularSendBuffer.
[in] aBuf
البيانات المطلوب إضافتها إلى المخزن المؤقت للإرسال
[in] aLen
مقدار البيانات المطلوب إضافته إلى المخزن المؤقت للإرسال.
المرتجعات
عدد وحدات البايت التي تم إرسالها أو رمز خطأ mbedtls.

المراجِع

تنشأ المواضيع المرجعية لواجهة برمجة تطبيقات OpenThread من رمز المصدر المتاح على GitHub. للحصول على مزيد من المعلومات أو للمساهمة في مستنداتنا، يمكنك الاطّلاع على المراجع.