TCP

تتضمن هذه الوحدة وظائف تتحكم في اتصال TCP.

ملخّص

عمليات التعداد
anonymous enum تعداد
يحدِّد العلامات التي تم تمريرها إلى otTcpConnect().
anonymous enum تعداد
يحدِّد العلامات التي تم تمريرها إلى otTcpSendByReference.
otTcpDisconnectedReason تعداد
otTcpIncomingConnectionAction{
  OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT,
  OT_TCP_INCOMING_CONNECTION_ACTION_DEFER,
  OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE
} 		تعداد
تحدد إجراءات الاتصال الوارد.

تحديدات النوع
otLinkedBuffer typedef
يشير ذلك المصطلح إلى هيكل مخزن مؤقت مرتبط للاستخدام مع بروتوكول TCP.
otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer) typedef
void(*
تشير معاودة الاتصال هذه إلى أن اتصال TCP جاهز الآن للاتصال الثنائي.
otTcpAcceptReady)(otTcpListener *aListener, const otSockAddr *aPeer, otTcpEndpoint **aAcceptInto) typedef
تشير معاودة الاتصال هذه إلى وصول اتصال وارد يطابق مستمع TCP هذا.
otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason) typedef
void(*
تشير معاودة الاتصال هذه إلى أن الاتصال قد تم قطعه ويجب عدم استخدامه مرة أخرى، أو أن الاتصال دخل في حالة الانتظار لمدة TIME-WAIT.
otTcpDisconnectedReason typedef
enum otTcpDisconnectedReason
otTcpEndpoint typedef
struct otTcpEndpoint
otTcpEndpointInitializeArgs typedef
تحتوي على وسيطات للدالة otTcpEndpointInitialize().
otTcpEstablished)(otTcpEndpoint *aEndpoint) typedef
void(*
تُعلم معاودة الاتصال هذه التطبيق باكتمال تأكيد اتصال TCP ثلاثي الاتجاه وأنه تم إنشاء الاتصال الآن.
otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog) typedef
void(*
تُعلم معاودة الاتصال هذه التطبيق في حال إحراز تقدم في إعادة توجيه البيانات من المخزن المؤقت للإرسال إلى المُستلِم.
otTcpIncomingConnectionAction typedef
تحدد إجراءات الاتصال الوارد.
otTcpListener typedef
struct otTcpListener
otTcpListenerInitializeArgs typedef
تحتوي على وسيطات للدالة otTcpListenerInitialize().
otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining) typedef
void(*
تشير معاودة الاتصال هذه إلى عدد وحدات البايت المتاحة للاستهلاك من المخزن المؤقت للاستلام.
otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData) typedef
void(*
تُعلِم معاودة الاتصال هذه التطبيق بأنّ البيانات في aData المقدَّمة قد أقرّها نظير الاتصال وأنّه يمكن للتطبيق استرداد aData والبيانات التي يحتوي عليها.

الدوال
otTcpAbort(otTcpEndpoint *aEndpoint)
إنهاء اتصال TCP المرتبط بنقطة نهاية TCP هذه بالقوة.
otTcpBind(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName)
تربط نقطة نهاية TCP بعنوان IP والمنفذ.
otTcpCommitReceive(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
تُعلِم حزمة بروتوكول التحكم بالنقل بأنّ التطبيق قد انتهى من معالجة aNumBytes بايت من البيانات عند بداية المخزن المؤقت للاستلام وأنّ حزمة بروتوكول التحكم بالنقل لا تحتاج إلى مواصلة الاحتفاظ بتلك وحدات البايت في المخزن المؤقت للاستلام.
otTcpConnect(otTcpEndpoint *aEndpoint, const otSockAddr *aSockName, uint32_t aFlags)
يتم تسجيل المضيف البعيد والمنفذ لهذا الاتصال.
otTcpEndpointDeinitialize(otTcpEndpoint *aEndpoint)
يؤدي إلى إلغاء تهيئة نقطة نهاية TCP هذه.
otTcpEndpointGetContext(otTcpEndpoint *aEndpoint)
void *
الحصول على مؤشر السياق الذي كان مرتبطًا بـ aEndpoint عند الإعداد.
otTcpEndpointGetInstance(otTcpEndpoint *aEndpoint)
يمكن الحصول على otInstance الذي كان مرتبطًا بـ aEndpoint عند الإعداد.
otTcpEndpointInitialize(otInstance *aInstance, otTcpEndpoint *aEndpoint, const otTcpEndpointInitializeArgs *aArgs)
يقوم بإعداد نقطة نهاية TCP.
otTcpGetLocalAddress(const otTcpEndpoint *aEndpoint)
const otSockAddr *
الحصول على مؤشر إلى المضيف والمنفذ المحلي لنقطة نهاية TCP.
otTcpGetPeerAddress(const otTcpEndpoint *aEndpoint)
const otSockAddr *
الحصول على مؤشر إلى مضيف ومنفذ نظير نقطة نهاية TCP.
otTcpListen(otTcpListener *aListener, const otSockAddr *aSockName)
يتسبب في أن تؤدي اتصالات TCP الواردة التي تطابق عنوان IP والمنفذ المحددَين إلى تشغيل عمليات الاستدعاء الخاصة بمستمع TCP هذا.
otTcpListenerDeinitialize(otTcpListener *aListener)
يؤدي هذا إلى إلغاء إعداد مستمع TCP هذا.
otTcpListenerGetContext(otTcpListener *aListener)
void *
الحصول على مؤشر السياق الذي كان مرتبطًا بـ aListener عند الإعداد.
otTcpListenerGetInstance(otTcpListener *aListener)
يمكن الحصول على otInstance الذي كان مرتبطًا بـ aListener عند الإعداد.
otTcpListenerInitialize(otInstance *aInstance, otTcpListener *aListener, const otTcpListenerInitializeArgs *aArgs)
تهيئة مستمع TCP.
otTcpReceiveByReference(otTcpEndpoint *aEndpoint, const otLinkedBuffer **aBuffer)
يوفر التطبيق مع سلسلة مخزن مؤقت مرتبطة تشير إلى البيانات الموجودة حاليًا في المخزن المؤقت للاستلام عبر بروتوكول التحكم بالنقل.
otTcpReceiveContiguify(otTcpEndpoint *aEndpoint)
إعادة تنظيم المخزن المؤقت للاستلام ليكون متجاورة بالكامل في الذاكرة.
otTcpSendByExtension(otTcpEndpoint *aEndpoint, size_t aNumBytes, uint32_t aFlags)
تضيف البيانات إلى المخزن المؤقت للإرسال عن طريق تمديد مدة otLinkedBuffer النهائي في المخزن المؤقت للإرسال بمقدار المبلغ المحدد.
otTcpSendByReference(otTcpEndpoint *aEndpoint, otLinkedBuffer *aBuffer, uint32_t aFlags)
تضيف البيانات التي تمت الإشارة إليها من خلال المخزن المؤقت المرتبط المشار إليه بواسطة aBuffer إلى المخزن المؤقت للإرسال.
otTcpSendEndOfStream(otTcpEndpoint *aEndpoint)
إبلاغ نظير الاتصال بأن نقطة نهاية TCP هذه لن ترسل المزيد من البيانات.
otTcpStopListening(otTcpListener *aListener)
يؤدي إلى أن يتوقف مستمع TCP هذا عن الاستماع إلى الاتصالات الواردة.

الهياكل
otLinkedBuffer

يشير ذلك المصطلح إلى هيكل مخزن مؤقت مرتبط للاستخدام مع بروتوكول TCP.

otTcpEndpoint

يمثل نقطة نهاية TCP.

otTcpEndpointInitializeArgs

تحتوي على وسيطات للدالة otTcpEndpointInitialize().

otTcpListener

يمثل مستمِع TCP.

otTcpListenerInitializeArgs

تحتوي على وسيطات للدالة otTcpListenerInitialize().

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

تعداد مجهول

 anonymous enum

يحدِّد العلامات التي تم تمريرها إلى otTcpConnect().

تعداد مجهول

 anonymous enum

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

otTcpDisconnectedReason

 otTcpDisconnectedReason

otTcpIncomingConnectionAction

 otTcpIncomingConnectionAction

تحدد إجراءات الاتصال الوارد.

وتُستخدَم هذه الطريقة في معاودة الاتصال بالرمز otTcpAcceptReady().

أماكن إقامة
OT_TCP_INCOMING_CONNECTION_ACTION_ACCEPT

اقبل الاتصال الوارد.

OT_TCP_INCOMING_CONNECTION_ACTION_DEFER

تأجيل الاتصال الوارد (تجاهل بدون صوت)

OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE

رفض الاتصال الوارد.

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

otLinkedBuffer

struct otLinkedBuffer otLinkedBuffer

يشير ذلك المصطلح إلى هيكل مخزن مؤقت مرتبط للاستخدام مع بروتوكول TCP.

تشير بنية otLinkedBuffer الفردية إلى مصفوفة من وحدات البايت في الذاكرة، وذلك باستخدام mData وmLength. يُستخدم حقل mNext لتكوين سلسلة من بُنى otLinkedBuffer.

otTcpAcceptDone

void(* otTcpAcceptDone)(otTcpListener *aListener, otTcpEndpoint *aEndpoint, const otSockAddr *aPeer)

تشير معاودة الاتصال هذه إلى أن اتصال TCP جاهز الآن للاتصال الثنائي.

وفي حالة استخدام TCP Fast Open، قد يكون ذلك قبل اكتمال تأكيد اتصال اتصال TCP فعليًا. يتم توفير التطبيق مع مؤشرات السياق لكل من مستمع TCP الذي قبل الاتصال ونقطة نهاية TCP التي تم قبول الاتصال فيها. والسياق المقدم هو السياق المرتبط بمستمع TCP.

التفاصيل
المَعلمات
[in] aListener
مستمع TCP الذي يتطابق مع الاتصال الوارد.
[in] aEndpoint
نقطة نهاية TCP التي تم قبول الاتصال الوارد فيها.
[in] aPeer
المضيف والمنفذ اللذان نشأ منهما الاتصال الوارد.

otTcpAcceptReady

otTcpIncomingConnectionAction(* otTcpAcceptReady)(otTcpListener *aListener, const otSockAddr *aPeer, otTcpEndpoint **aAcceptInto)

تشير معاودة الاتصال هذه إلى وصول اتصال وارد يطابق مستمع TCP هذا.

وعادةً ما يكون الرد أن يقبل التطبيق الاتصال الوارد. ويتم إجراء ذلك من خلال ملء aAcceptInto بمؤشر إلى otTcpEndpoint لقبول الاتصال الوارد فيه. يجب إعداد otTcpEndpoint من قبل باستخدام otTcpEndpointInitialize(). وبعد ذلك، يعرض التطبيق OT_TCP_INCOMING_CONNECTION_ACTION_قبول.

وبدلاً من ذلك، يمكن أن يرفض التطبيق قبول الاتصال الوارد. هناك طريقتان للقيام بذلك من خلال التطبيق. أولاً، إذا عرض التطبيق OT_TCP_INCOMING_CONNECTION_ACTION_DEFER، سيتجاهل OpenThread طلب إنشاء الاتصال بشكل غير ملحوظ، ومن المحتمل أن يعيد نظير الاتصال إرسال الطلب، وفي هذه المرحلة سيتم استدعاء الاتصال مرة أخرى. يُعد هذا الإجراء مفيدًا إذا لم تكن الموارد متاحة حاليًا لقبول الربط، ولكنها قد تكون متاحة عندما يُعيد نظير الاتصال نقل محاولة إنشاء الاتصال. ثانيًا، إذا عرض التطبيق OT_TCP_INCOMING_CONNECTION_ACTION_REFUSE، فسيرسل OpenThread رسالة "تم رفض الاتصال" إلى المضيف الذي حاول إنشاء اتصال. إذا رفض التطبيق الاتصال الوارد، لن يكون مطلوبًا تعبئة aAcceptInto.

التفاصيل
المَعلمات
[in] aListener
مستمع TCP الذي يتطابق مع الاتصال الوارد.
[in] aPeer
المضيف والمنفذ اللذان ينشأ منهما الاتصال الوارد.
[out] aAcceptInto
نقطة نهاية TCP التي يمكن قبول الاتصال الوارد فيها.
المرتجعات
وصف لطريقة التعامل مع الاتصال الوارد.

otTcpDisconnected

void(* otTcpDisconnected)(otTcpEndpoint *aEndpoint, otTcpDisconnectedReason aReason)

تشير معاودة الاتصال هذه إلى أن الاتصال قد تم قطعه ويجب عدم استخدامه مرة أخرى، أو أن الاتصال دخل في حالة الانتظار لمدة TIME-WAIT.

يمكن أن يحدث ذلك في حال تعذُّر محاولة إنشاء اتصال (التي بدأت من خلال استدعاء الدالة otTcpConnect())، أو في حال انتهاء مهلة الاتصال (على سبيل المثال، في حال انتهاء مهلة الاتصال أو تلقّي مقطع RST من نظير الاتصال). بعد تنشيط معاودة الاتصال هذه، يمكن استعادة جميع الموارد التي وفّرها التطبيق لهذا الاتصال (أي otLinkedBuffers والذاكرة التي يشير إليها، وليس نقطة نهاية بروتوكول التحكم بالنقل نفسها أو المساحة للمخازن المؤقتة للاستلام). في حالة دخول اتصال في حالة TIME-WAIT، يتم استدعاء معاودة الاتصال هذه مرتين، مرة عند الدخول في حالة TIME-WAIT (مع OT_TCP_DISCONNECTED_REASON_TIME_WAIT، ومرة أخرى عند انتهاء صلاحية حالة TIME-WAIT (باستخدام OT_TCP_DISCONNECTED_REASON_NORMAL).

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP التي تم فقد اتصالها.
[in] aReason
سبب انقطاع الاتصال.

otTcpDisconnectedReason

enum otTcpDisconnectedReason otTcpDisconnectedReason

otTcpEndpoint

struct otTcpEndpoint otTcpEndpoint

otTcpEndpointInitializeArgs

struct otTcpEndpointInitializeArgs otTcpEndpointInitializeArgs

تحتوي على وسيطات للدالة otTcpEndpointInitialize().

otTcpEstablished

void(* otTcpEstablished)(otTcpEndpoint *aEndpoint)

تُعلم معاودة الاتصال هذه التطبيق باكتمال تأكيد اتصال TCP ثلاثي الاتجاه وأنه تم إنشاء الاتصال الآن.

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP التي تم إنشاء الاتصال بها الآن.

otTcpForwardProgress

void(* otTcpForwardProgress)(otTcpEndpoint *aEndpoint, size_t aInSendBuffer, size_t aBacklog)

تُعلم معاودة الاتصال هذه التطبيق في حال إحراز تقدم في إعادة توجيه البيانات من المخزن المؤقت للإرسال إلى المُستلِم.

معاودة الاتصال هذه غير ضرورية لعملية TCP الصحيحة. لا يمكن لمعظم التطبيقات الاعتماد فقط على استدعاء otTcpSendDone() لاسترداد المخازن المؤقتة المرتبطة بعد انتهاء حزمة بروتوكول التحكم بالنقل من استخدامها. الغرض من معاودة الاتصال هذه هو دعم التطبيقات المتقدّمة التي تستفيد من معلومات أكثر دقة حول كيفية تقدُّم الاتصال في عملية نقل البيانات إلى نظير الاتصال.

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

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

لا يستخدم حزمة بروتوكول التحكم بالنقل سوى وحدات البايت aInSendBuffer المتوفرة في ذيل المخزن المؤقت للإرسال، وعندما ينخفض "aInSendBuffer" بمقدار x، يعني ذلك أنّ وحدات البايت الإضافية x التي كانت سابقًا في رأس المخزن المؤقت للإرسال لم تعُد جزءًا من المخزن المؤقت للإرسال ويمكن استردادها الآن (أي استبدالها) من خلال التطبيق. يُرجى العلم أنّه لا يمكن استعادة بنية otLinkedBuffer نفسها إلا عندما تصبح جميع وحدات البايت التي تشير إليها جزءًا من المخزن المؤقت للإرسال.

تندرج معاودة الاتصال ضمن البيانات otTcpSendDone() بالمعنى التالي: يمكن للتطبيقات تحديد متى يمكن استعادة المخازن المؤقتة المرتبطة من خلال مقارنة aInSendBuffer بعدد وحدات البايت المتوفّرة في كل مخزن مؤقت مرتبط. ومع ذلك، نتوقّع أن يكون استخدام الدالة otTcpSendDone() أسهل بكثير، والذي يشير مباشرةً إلى ملفات otLinkedBuffers التي يمكن استردادها. إذا تم تسجيل عمليتَي معاودة الاتصال وتم بدءهما من خلال الحدث نفسه (على سبيل المثال، تم استلام شريحة ACK نفسها)، سيتم أولاً بدء معاودة الاتصال otTcpSendDone()، متبوعًا بمعاودة الاتصال هذه.

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

بعد استدعاء الدالة otTcpSendByReference() أو otTcpSendByExtension() بعدد موجب من وحدات البايت، يمكن ضمان طلب استدعاء otTcpForwardProgress() للإشارة إلى وقت إرسال وحدات البايت التي تمت إضافتها إلى المخزن المؤقت للإرسال. قد يتم طلب otTcpForwardProgress() مباشرةً بعد إضافة وحدات البايت إلى المخزن المؤقت للإرسال (في حال إرسال بعض وحدات البايت هذه على الفور، ما يؤدي إلى تقليل قائمة المهام)، أو في وقت لاحق بعد إرسال بعض البيانات أو جميعها، ما يقلّل من قائمة المهام). ونعني بعبارة "فورًا" تحديد موعد تنفيذ معاودة الاتصال فورًا في مهمة مصغَّرة، ولتجنُّب التعقيدات المتعلقة باستعادة الدخول، لا يتم مطلقًا استدعاء استدعاء otTcpForwardProgress() مباشرةً من الدالتَين otTcpSendByReference() أو otTcpSendByExtension().

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP للاتصال.
[in] aInSendBuffer
عدد وحدات البايت في المخزن المؤقت للإرسال (مجموع المناطق "أثناء الطيران" و "قائمة المهام").
[in] aBacklog
عدد وحدات البايت المدرجة في قائمة الانتظار للإرسال ولكن لم يتم إرسالها بعد (منطقة "قائمة المهام").

otTcpIncomingConnectionAction

enum otTcpIncomingConnectionAction otTcpIncomingConnectionAction

تحدد إجراءات الاتصال الوارد.

وتُستخدَم هذه الطريقة في معاودة الاتصال بالرمز otTcpAcceptReady().

otTcpListener

struct otTcpListener otTcpListener

otTcpListenerInitializeArgs

struct otTcpListenerInitializeArgs otTcpListenerInitializeArgs

تحتوي على وسيطات للدالة otTcpListenerInitialize().

otTcpReceiveAvailable

void(* otTcpReceiveAvailable)(otTcpEndpoint *aEndpoint, size_t aBytesAvailable, bool aEndOfStream, size_t aBytesRemaining)

تشير معاودة الاتصال هذه إلى عدد وحدات البايت المتاحة للاستهلاك من المخزن المؤقت للاستلام.

ويتم استدعاؤه عند إضافة وحدات بايت إلى المخزن المؤقت للاستلام وعند الوصول إلى نهاية البث. إذا تم الوصول إلى نهاية مجموعة البث (أي إذا لم تتوفّر بيانات إضافية للقراءة بسبب إغلاق نظير الاتصال من نهاية الاتصال للكتابة)، تكون القيمة aEndOfStream صحيحة. وأخيرًا، تشير السمة aBytesRemaining إلى مقدار السعة المتبقية في المخزن المؤقت للاستلام للاحتفاظ بالبيانات الإضافية التي تصل.

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP للاتصال.
[in] aBytesAvailable
عدد وحدات البايت في المخزن المؤقت للاستلام للاتصال.
[in] aEndOfStream
يشير إلى ما إذا كان يمكن استلام بيانات إضافية، بخلاف البيانات المتوفرة بالفعل في المخزن المؤقت لاستقبال الاتصال.
[in] aBytesRemaining
عدد وحدات البايت الإضافية التي يمكن استلامها قبل امتلاء المخزن المؤقت للاستلام.

otTcpSendDone

void(* otTcpSendDone)(otTcpEndpoint *aEndpoint, otLinkedBuffer *aData)

تُعلِم معاودة الاتصال هذه التطبيق بأنّ البيانات في aData المقدَّمة قد أقرّها نظير الاتصال وأنّه يمكن للتطبيق استرداد aData والبيانات التي يحتوي عليها.

وتضمن مطابقة aData لتلك التي تم تمريرها إلى بروتوكول TCP عبر otTcpSendByReference()، بما في ذلك أي إضافات متأثرة عبر otTcpSendByExtension().

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP للاتصال.
[in] aData
مؤشر يشير إلى otLinkedBuffer الذي يمكن استرداده.

الدوال

otTcpAbort

otError otTcpAbort(
  otTcpEndpoint *aEndpoint
)

إنهاء اتصال TCP المرتبط بنقطة نهاية TCP هذه بالقوة.

ويؤدي ذلك إلى جعل نقطة نهاية TCP على الفور مجانية للاستخدام في اتصال آخر وتفرغ المخازن المؤقتة للإرسال والاستلام، ما يؤدي إلى نقل ملكية أي بيانات يوفّرها التطبيق في طلبَي otTcpSendByReference() وotTcpSendByExtension() إلى التطبيق مرة أخرى. تظل استدعاءات وذاكرة المخزن المؤقت للاستلام في نقطة نهاية TCP مرتبطة بنقطة نهاية TCP.

التفاصيل
المَعلمات
[in] aEndpoint
يشير هذا المصطلح إلى مؤشر لبنية نقطة نهاية TCP التي تمثل نقطة نهاية بروتوكول TCP المراد إلغاؤها.
قيم الإرجاع
OT_ERROR_NONE
تم إلغاء اتصال نقطة نهاية TCP بنجاح.
OT_ERROR_FAILED
تعذّر إلغاء اتصال نقطة نهاية TCP.

otTcpBind

otError otTcpBind(
  otTcpEndpoint *aEndpoint,
  const otSockAddr *aSockName
)

تربط نقطة نهاية TCP بعنوان IP والمنفذ.

التفاصيل
المَعلمات
[in] aEndpoint
يشير هذا المصطلح إلى مؤشر لبنية نقطة نهاية TCP المراد ربطها.
[in] aSockName
العنوان والمنفذ المراد ربط نقطة نهاية TCP هذه.
قيم الإرجاع
OT_ERROR_NONE
تم ربط نقطة نهاية TCP بنجاح.
OT_ERROR_FAILED
تعذّر ربط نقطة نهاية TCP.

otTcpCommitReceive

otError otTcpCommitReceive(
  otTcpEndpoint *aEndpoint,
  size_t aNumBytes,
  uint32_t aFlags
)

تُعلِم حزمة بروتوكول التحكم بالنقل بأنّ التطبيق قد انتهى من معالجة aNumBytes بايت من البيانات عند بداية المخزن المؤقت للاستلام وأنّ حزمة بروتوكول التحكم بالنقل لا تحتاج إلى مواصلة الاحتفاظ بتلك وحدات البايت في المخزن المؤقت للاستلام.

التفاصيل
المَعلمات
[in] aEndpoint
مؤشر يشير إلى بنية نقطة نهاية TCP التي تمثل نقطة نهاية TCP التي سيتم تلقي البيانات عليها.
[in] aNumBytes
عدد وحدات البايت المستهلكة.
[in] aFlags
علامات تحدد الخيارات لهذه العملية (لا شيء حتى الآن).
قيم الإرجاع
OT_ERROR_NONE
تم إكمال عملية الاستلام بنجاح.
OT_ERROR_FAILED
تعذّر إكمال عملية الاستلام.

otTcpConnect

otError otTcpConnect(
  otTcpEndpoint *aEndpoint,
  const otSockAddr *aSockName,
  uint32_t aFlags
)

يتم تسجيل المضيف البعيد والمنفذ لهذا الاتصال.

يجب تفعيل TCP Fast Open أو إيقافه باستخدام aFlags. وفي حال إيقافه، تبدأ تأكيد اتصال تأسيس اتصال TCP على الفور. وفي حال تفعيل السياسة، لا تُسجِّل هذه الدالة سوى المضيف والمنفذ البعيد، ولن تتم تأكيد اتصال إنشاء اتصال بروتوكول التحكم بالنقل (TCP) إلا عند الاتصال الأول بـ otTcpSendByReference().

في حال إيقاف TCP Fast Open، يجب أن ينتظر المتصل معاودة الاتصال بـ otTcpEstablished للإشارة إلى أنه تتم تأكيد اتصال إنشاء اتصال TCP قبل أن يتمكن من بدء إرسال البيانات، مثلاً من خلال الاتصال بـ otTcpSendByReference().

التفاصيل
المَعلمات
[in] aEndpoint
مؤشر يشير إلى بنية نقطة نهاية TCP المراد الاتصال بها.
[in] aSockName
عنوان IP ومنفذ المضيف المطلوب الاتصال به.
[in] aFlags
علامات تحدد الخيارات لهذه العملية (راجع التعداد أعلاه).
قيم الإرجاع
OT_ERROR_NONE
تم إكمال العملية بنجاح.
OT_ERROR_FAILED
تعذّر إكمال العملية.

otTcpEndpointDeinitialize

otError otTcpEndpointDeinitialize(
  otTcpEndpoint *aEndpoint
)

يؤدي إلى إلغاء تهيئة نقطة نهاية TCP هذه.

وهذا يعني أن OpenThread لم يعد يتتبع نقطة نهاية TCP هذه ويحدد جميع الموارد التي خصصها داخليًا لنقطة نهاية TCP هذه. يمكن للتطبيق إعادة استخدام النسخ الاحتياطي لنقطة نهاية TCP على النحو الملائم.

إذا كان الاتصال متوافقًا مع اتصال TCP مباشر، يتم إنهاء الاتصال بشكل غير رسمي (كما في otTcpAbort()). يتم على الفور إرجاع جميع الموارد التي وفّرها التطبيق لنقطة نهاية بروتوكول التحكم بالنقل هذه (المخازن المؤقتة المرتبطة بمخزن الإرسال المؤقت وذاكرة المخزن المؤقت للاستلام وبنية aEndpoint نفسها، وما إلى ذلك).

التفاصيل
المَعلمات
[in] aEndpoint
مؤشر يشير إلى بنية نقطة نهاية TCP التي تريد إلغاء إعدادها.
قيم الإرجاع
OT_ERROR_NONE
تم إلغاء تهيئة نقطة نهاية TCP بنجاح.
OT_ERROR_FAILED
تعذّر إلغاء إعداد نقطة نهاية TCP.

otTcpEndpointGetContext

void * otTcpEndpointGetContext(
  otTcpEndpoint *aEndpoint
)

الحصول على مؤشر السياق الذي كان مرتبطًا بـ aEndpoint عند الإعداد.

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP التي يجب الحصول على سياقها.
المرتجعات
مؤشر السياق المرتبط بـ aEndpoint.

otTcpEndpointGetInstance

otInstance * otTcpEndpointGetInstance(
  otTcpEndpoint *aEndpoint
)

يمكن الحصول على otInstance الذي كان مرتبطًا بـ aEndpoint عند الإعداد.

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP التي يجب الحصول على مثيلها.
المرتجعات
مؤشر otInstance المرتبط بـ aEndpoint.

otTcpEndpointInitialize

otError otTcpEndpointInitialize(
  otInstance *aInstance,
  otTcpEndpoint *aEndpoint,
  const otTcpEndpointInitializeArgs *aArgs
)

يقوم بإعداد نقطة نهاية TCP.

يؤدي استدعاء هذه الدالة إلى احتفاظ OpenThread بنقطة نهاية TCP وتخزين بيانات بروتوكول TCP واستردادها داخل aEndpoint. ويجب أن يتجنّب التطبيق الوصول مباشرةً إلى الحقول في aEndpoint أو تعديلها. إذا كان التطبيق بحاجة إلى استعادة النسخ الاحتياطي للذاكرة aEndpoint، يجب أن يطلب الإجراء otTcpEndpointDeinitialize().

التفاصيل
المَعلمات
[in] aInstance
يشير هذا المصطلح إلى مؤشر لمثيل OpenThread.
[in] aEndpoint
يشير هذا المصطلح إلى مؤشر لبنية نقطة نهاية TCP.
[in] aArgs
يشير ذلك المصطلح إلى بنية من الوسيطات.
قيم الإرجاع
OT_ERROR_NONE
تم فتح نقطة نهاية TCP بنجاح.
OT_ERROR_FAILED
تعذّر فتح نقطة نهاية TCP.

otTcpGetLocalAddress

const otSockAddr * otTcpGetLocalAddress(
  const otTcpEndpoint *aEndpoint
)

الحصول على مؤشر إلى المضيف والمنفذ المحلي لنقطة نهاية TCP.

قد تكون محتويات المضيف والمنفذ قديمة إذا لم يكن هذا المقبس في حالة متصلة ولم يتم ربطه بعد آخر مرة تم فيها قطع الاتصال.

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP التي يجب الحصول على المضيف والمنفذ المحلي لها.
المرتجعات
المضيف المحلي ومنفذ aEndpoint.

otTcpGetPeerAddress

const otSockAddr * otTcpGetPeerAddress(
  const otTcpEndpoint *aEndpoint
)

الحصول على مؤشر إلى مضيف ومنفذ نظير نقطة نهاية TCP.

قد تكون محتويات المضيف والمنفذ قديمة إذا لم يكن هذا المقبس في حالة متصلة.

التفاصيل
المَعلمات
[in] aEndpoint
نقطة نهاية TCP التي يجب الحصول على مضيفها ومنفذها.
المرتجعات
مضيف ومنفذ نظير الاتصال لـ aEndpoint.

otTcpListen

otError otTcpListen(
  otTcpListener *aListener,
  const otSockAddr *aSockName
)

يتسبب في أن تؤدي اتصالات TCP الواردة التي تطابق عنوان IP والمنفذ المحددَين إلى تشغيل عمليات الاستدعاء الخاصة بمستمع TCP هذا.

التفاصيل
المَعلمات
[in] aListener
يشير هذا المصطلح إلى مؤشر لبنية مستمع بروتوكول TCP التي يجب أن تبدأ عملية الاستماع.
[in] aSockName
العنوان والمنفذ الذي يتم من خلاله الاستماع إلى الاتصالات الواردة
قيم الإرجاع
OT_ERROR_NONE
تم بدء الاستماع على وحدة معالجة TCP بنجاح.
OT_ERROR_FAILED
تعذَّر بدء الاستماع على مستمِع TCP.

otTcpListenerDeinitialize

otError otTcpListenerDeinitialize(
  otTcpListener *aListener
)

يؤدي هذا إلى إلغاء إعداد مستمع TCP هذا.

وهذا يعني أن OpenThread لم يعد يتتبع مستمع TCP هذا ويحدد جميع الموارد التي خصصها داخليًا لمستمع TCP هذا. يمكن للتطبيق إعادة استخدام الذاكرة الاحتياطية لمستمع TCP على النحو الملائم.

إذا كان مستمِع TCP قيد الاستماع حاليًا، فإنه يتوقف عن الاستماع.

التفاصيل
المَعلمات
[in] aListener
يشير هذا المصطلح إلى مؤشر لتركيبة مرصد TCP التي تريد إيقافها.
قيم الإرجاع
OT_ERROR_NONE
تم إيقاف مستمع TCP بنجاح.
OT_ERROR_FAILED
تعذّر إيقاف مستمع TCP.

otTcpListenerGetContext

void * otTcpListenerGetContext(
  otTcpListener *aListener
)

الحصول على مؤشر السياق الذي كان مرتبطًا بـ aListener عند الإعداد.

التفاصيل
المَعلمات
[in] aListener
مستمع TCP الذي يتم الحصول على سياقه.
المرتجعات
مؤشر السياق المرتبط بـ aListener.

otTcpListenerGetInstance

otInstance * otTcpListenerGetInstance(
  otTcpListener *aListener
)

يمكن الحصول على otInstance الذي كان مرتبطًا بـ aListener عند الإعداد.

التفاصيل
المَعلمات
[in] aListener
مستمِع TCP الذي يجب الحصول على مثيله.
المرتجعات
مؤشر otInstance المرتبط بـ aListener.

otTcpListenerInitialize

otError otTcpListenerInitialize(
  otInstance *aInstance,
  otTcpListener *aListener,
  const otTcpListenerInitializeArgs *aArgs
)

تهيئة مستمع TCP.

يؤدي استدعاء هذه الدالة إلى احتفاظ OpenThread بتتبُّع مستمع بروتوكول التحكم بالنقل وتخزين بيانات بروتوكول التحكم بالنقل واستردادها داخل aListener. ويجب أن يتجنّب التطبيق الوصول مباشرةً إلى الحقول في aListener أو تعديلها. إذا كان التطبيق يحتاج إلى استعادة النسخ الاحتياطي للذاكرة aListener، يجب أن يطلب الإجراء otTcpListenerDeinitialize().

التفاصيل
المَعلمات
[in] aInstance
يشير هذا المصطلح إلى مؤشر لمثيل OpenThread.
[in] aListener
يشير هذا المصطلح إلى مؤشر لبنية مستمع بروتوكول التحكم بالنقل.
[in] aArgs
يشير ذلك المصطلح إلى بنية من الوسيطات.
قيم الإرجاع
OT_ERROR_NONE
تم فتح وحدة تحكّم TCP بنجاح.
OT_ERROR_FAILED
تعذّر فتح مستمِع TCP.

otTcpReceiveByReference

otError otTcpReceiveByReference(
  otTcpEndpoint *aEndpoint,
  const otLinkedBuffer **aBuffer
)

يوفر التطبيق مع سلسلة مخزن مؤقت مرتبطة تشير إلى البيانات الموجودة حاليًا في المخزن المؤقت للاستلام عبر بروتوكول التحكم بالنقل.

تكون سلسلة المخزن المؤقت المرتبطة صالحة إلى أن يتم استدعاء معاودة الاتصال "استلام الطلب" في المرة التالية، أو إلى أن يتم الاتصال التالي بـ otTcpReceiveContiguify() أو otTcpCommitReceive().

التفاصيل
المَعلمات
[in] aEndpoint
مؤشر يشير إلى بنية نقطة نهاية TCP التي تمثل نقطة نهاية TCP التي سيتم تلقي البيانات عليها.
[out] aBuffer
يشير هذا المصطلح إلى مؤشر لسلسلة المخزن المؤقت المرتبطة التي تشير إلى البيانات المتوفّرة حاليًا في المخزن المؤقت للاستلام.
قيم الإرجاع
OT_ERROR_NONE
تم إكمال العملية بنجاح.
OT_ERROR_FAILED
تعذّر إكمال العملية.

otTcpReceiveContiguify

otError otTcpReceiveContiguify(
  otTcpEndpoint *aEndpoint
)

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

هذا إجراء اختياري، حيث يمكن للتطبيق اجتياز سلسلة المخزن المؤقت المرتبطة التي تم الحصول عليها عن طريق طلب البيانات otTcpReceiveByReference. قد ترغب بعض التطبيقات في استدعاء هذه الدالة لجعل المخزن المؤقت للاستلام متجاورة لتبسيط معالجة البيانات، إلا أن هذا يأتي على حساب وقت وحدة المعالجة المركزية لإعادة تنظيم البيانات في المخزن المؤقت للاستلام.

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

otTcpSendByExtension

otError otTcpSendByExtension(
  otTcpEndpoint *aEndpoint,
  size_t aNumBytes,
  uint32_t aFlags
)

تضيف البيانات إلى المخزن المؤقت للإرسال عن طريق تمديد مدة otLinkedBuffer النهائي في المخزن المؤقت للإرسال بمقدار المبلغ المحدد.

إذا كان المخزن المؤقت للإرسال فارغًا، ستفشل العملية.

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

otTcpSendByReference

otError otTcpSendByReference(
  otTcpEndpoint *aEndpoint,
  otLinkedBuffer *aBuffer,
  uint32_t aFlags
)

تضيف البيانات التي تمت الإشارة إليها من خلال المخزن المؤقت المرتبط المشار إليه بواسطة aBuffer إلى المخزن المؤقت للإرسال.

عند استدعاء ناجح لهذه الدالة، يصبح المخزن المؤقت المرتبط والبيانات التي يشير إليها مملوكة لمكدس TCP، ويجب ألا يعدلها التطبيق إلا بعد أن يُرجع استدعاء "تم الإرسال" ملكية هذه الكائنات إلى التطبيق. من المقبول استدعاء هذه الدالة لإضافة مخزن مؤقت مرتبط آخر إلى قائمة انتظار الإرسال، حتى إذا لم يتم تنشيط استدعاء "تم الإرسال" لاستدعاء سابق لهذه الدالة بعد.

ملاحظة: يجب عدم ربط الحقل aBuffer بسلسلة، ويجب أن يكون الحقل mNext فارغًا (فارغ). إذا تمت إضافة بيانات إضافية بعد هذا الاستدعاء مباشرةً، فيجب استخدام علامة OT_TCP_SEND_MORE_TO_COME كتلميح لتنفيذ بروتوكول TCP.

التفاصيل
المَعلمات
[in] aEndpoint
مؤشر يشير إلى بنية نقطة نهاية TCP التي تمثل نقطة نهاية TCP التي سيتم إرسال البيانات عليها.
[in] aBuffer
يشير هذا المصطلح إلى مؤشر لسلسلة المخزن المؤقت المرتبطة التي تشير إلى البيانات المطلوب إضافتها إلى المخزن المؤقت للإرسال.
[in] aFlags
علامات تحدد الخيارات لهذه العملية (راجع التعداد أعلاه).
قيم الإرجاع
OT_ERROR_NONE
تمت إضافة البيانات إلى المخزن المؤقت للإرسال بنجاح.
OT_ERROR_FAILED
تعذّرت إضافة البيانات إلى المخزن المؤقت للإرسال.

otTcpSendEndOfStream

otError otTcpSendEndOfStream(
  otTcpEndpoint *aEndpoint
)

إبلاغ نظير الاتصال بأن نقطة نهاية TCP هذه لن ترسل المزيد من البيانات.

يجب استخدام هذا عندما لا يحتوي التطبيق على مزيد من البيانات لإرسالها إلى نظير الاتصال. بالنسبة إلى هذا الاتصال، ستؤدي عمليات القراءة المستقبلية على نظير الاتصال إلى شرط "نهاية البث"، وستتعذّر عمليات الكتابة المستقبلية على نقطة نهاية الاتصال هذه.

لا ينطبق شرط "نهاية البث" إلا بعد استلام أي بيانات تم تقديمها مسبقًا إلى مكدس TCP للإرسال من نظير الاتصال.

التفاصيل
المَعلمات
[in] aEndpoint
مؤشر يشير إلى بنية نقطة نهاية TCP التي تمثل نقطة نهاية TCP المراد إيقافها.
قيم الإرجاع
OT_ERROR_NONE
تم إدراج شرط "نهاية البث" في قائمة الانتظار بنجاح للنقل.
OT_ERROR_FAILED
تعذّر وضع شرط "نهاية البث" في قائمة الانتظار للنقل.

otTcpStopListening

otError otTcpStopListening(
  otTcpListener *aListener
)

يؤدي إلى أن يتوقف مستمع TCP هذا عن الاستماع إلى الاتصالات الواردة.

التفاصيل
المَعلمات
[in] aListener
يشير هذا المصطلح إلى مؤشر لبنية مستمِع TCP الذي يجب أن يتوقف عن الاستماع.
قيم الإرجاع
OT_ERROR_NONE
تم إيقاف الاستماع على مستمِع TCP بنجاح.
OT_ERROR_FAILED
تعذّر إيقاف الاستماع على مستمِع TCP.

وحدات ماكرو

OT_TCP_ENDPOINT_TCB_NUM_PTR

 OT_TCP_ENDPOINT_TCB_NUM_PTR 36

OT_TCP_ENDPOINT_TCB_SIZE_BASE

 OT_TCP_ENDPOINT_TCB_SIZE_BASE 392

يتم اختيار OT_TCP_ENDPOINT_TCB_SIZE_BASE وOT_TCP_ENDPOINT_TCB_NUM_POINTERS، بحيث يكون للحقل mTcb لـ otTcpEndpoint الحجم نفسه مثل struct tcpcb في TCPlp.

يعد ذلك ضروريًا لأن الحقل mTcb، على الرغم من أنه معتم في إعلانه، يتم التعامل معه على أنه هيكلة tcpcb في تطبيق بروتوكول التحكم بالنقل.

OT_TCP_LISTENER_TCB_NUM_PTR

 OT_TCP_LISTENER_TCB_NUM_PTR 3

OT_TCP_LISTENER_TCB_SIZE_BASE

 OT_TCP_LISTENER_TCB_SIZE_BASE 16

يتم اختيار OT_TCP_LISTENER_TCB_SIZE_BASE وOT_TCP_LISTENER_TCB_NUM_POINTERS بحيث يكون للحقل mTcbListener الخاص بـ otTcpListener حجم نفس حجم البنية tcpcb_listen في بروتوكول TCPlp.

وهذا ضروري لأن الحقل mTcbListenاء معتم في تعريفه يتم التعامل معه على أنه هيكلة tcpcb في تنفيذ بروتوكول التحكم بالنقل.

OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_FEW_HOPS 2598

حجم المخزن المؤقت الموصى به لاتصالات TCP التي تتجاوز حوالي 3 قفزات لاسلكية أو أقل.

في الأنظمة الأساسية التي تكون فيها الذاكرة محدودة بشكل خاص، وفي الحالات التي لا يكون فيها معدل نقل بيانات عالٍ ضروريًا، قد يكون من المستحسن تحديد حجم مخزن مؤقت أصغر يدويًا.

OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS

 OT_TCP_RECEIVE_BUFFER_SIZE_MANY_HOPS 4157

حجم المخزن المؤقت المقترَح لاتصالات TCP التي تجتاز العديد من القفزات اللاسلكية.

إذا تجاوز اتصال TCP عددًا كبيرًا جدًا من القفزات (أكثر من 6 قفزات أو نحو ذلك)، فقد يكون من المستحسن تحديد حجم مخزن مؤقت كبير يدويًا.

المراجِع

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