นามธรรม TCP

โมดูลนี้มีบทคัดย่อที่ใช้งานง่ายที่ด้านบนของ TCP API พื้นฐาน

สรุป

การแจกแจง
anonymous enum	enum ระบุแฟล็กที่ส่งไปยัง otTcpCircularSendBufferWrite

Typedef
otTcpCircularSendBuffer	typedef struct otTcpCircularSendBuffer แสดงบัฟเฟอร์การส่งแบบวงกลมเพื่อใช้กับปลายทาง TCP
otTcpEndpointAndCircularSendBuffer	typedef struct otTcpEndpointAndCircularSendBuffer โครงสร้างบริบทที่จะใช้กับ mbedtls_ssl_set_bio

ฟังก์ชัน
otTcpCircularSendBufferDeinitialize(otTcpCircularSendBuffer *aSendBuffer)	otError ยกเลิกค่าเริ่มต้นบัฟเฟอร์ส่งที่เป็นวงกลม TCP โดยจะถอดออกหากมีการเชื่อมต่อ
otTcpCircularSendBufferForceDiscardAll(otTcpCircularSendBuffer *aSendBuffer)	void บังคับทิ้งข้อมูลทั้งหมดในบัฟเฟอร์ส่งแบบวงกลม
otTcpCircularSendBufferGetFreeSpace(const otTcpCircularSendBuffer *aSendBuffer)	size_t แสดงผลปริมาณพื้นที่ว่างในบัฟเฟอร์การส่งแบบวงกลม TCP
otTcpCircularSendBufferHandleForwardProgress(otTcpCircularSendBuffer *aSendBuffer, size_t aInSendBuffer)	void จัดการ Circlar-send-buffer ที่เฉพาะเจาะจงในการเรียกกลับ otTcpForwardProgress
otTcpCircularSendBufferInitialize(otTcpCircularSendBuffer *aSendBuffer, void *aDataBuffer, size_t aCapacity)	void เริ่มต้นบัฟเฟอร์การส่งแบบวงกลม TCP
otTcpCircularSendBufferWrite(otTcpEndpoint *aEndpoint, otTcpCircularSendBuffer *aSendBuffer, const void *aData, size_t aLength, size_t *aWritten, uint32_t aFlags)	otError ส่งข้อมูลบนปลายทาง 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	แสดงบัฟเฟอร์การส่งแบบวงกลมเพื่อใช้กับปลายทาง TCP
otTcpEndpointAndCircularSendBuffer	โครงสร้างบริบทที่จะใช้กับ mbedtls_ssl_set_bio

การแจกแจง

enum ที่ไม่ระบุตัวตน

 anonymous enum

ระบุแฟล็กที่ส่งไปยัง otTcpCircularSendBufferWrite

Typedef

otTcpCircularSendBuffer

struct otTcpCircularSendBuffer otTcpCircularSendBuffer

แสดงบัฟเฟอร์การส่งแบบวงกลมเพื่อใช้กับปลายทาง TCP

คุณจะใช้บัฟเฟอร์การส่งแบบวงกลมหรือไม่ก็ได้ แอปพลิเคชันใช้ปลายทาง TCP เพื่อส่งข้อมูลโดยการจัดการ otLinkedBuffers ได้โดยตรง อย่างไรก็ตาม บางแอปพลิเคชันอาจสะดวกกว่าการใช้บัฟเฟอร์ส่งแบบวงกลม แอปพลิเคชันดังกล่าวสามารถเรียก otTcpCircularSendBufferWrite() เพื่อ "แนบ" บัฟเฟอร์ส่งแบบวงกลมไปยังปลายทาง TCP และส่งข้อมูลไปยังปลายทาง TCP โดยใช้บัฟเฟอร์การส่งแบบวงกลมเพื่อจัดการ otLinkedBuffers ที่สำคัญ

otTcpCircularSendBuffer ผสานรวมเพิ่มเติมจาก API ที่ใช้ otLinkedBuffer ซึ่งมาจาก otTcpEndpoint เมื่อต่อเชื่อม otTcpEndpoint แล้ว otTcpCircularSendBuffer จะดําเนินการทั้งหมดในการจัดการ otLinkedBuffers สําหรับการเชื่อมต่อ ซึ่งหมายความว่าเมื่อแนบ otTcpCircularSendBuffer กับ otTcpEndpoint แอปพลิเคชันไม่ควรเรียกใช้ otTcpSendByReference() หรือ otTcpSendByExtension() ใน otTcpEndpoint ดังกล่าว แต่แอปพลิเคชันควรใช้ otTcpCircularSendBufferWrite() เพื่อเพิ่มข้อมูลลงในบัฟเฟอร์ที่ส่ง

โค้ดเรียกกลับ otTcpForwardProgress() เป็นวิธีที่จะช่วยให้ผู้ใช้ทราบได้เมื่อมีพื้นที่ว่างในบัฟเฟอร์การส่งแบบวงกลม ใน otTcpEndpoint ที่มีการแนบ otTcpCircularSendBuffer แอปพลิเคชันต้องติดตั้งโค้ดเรียกกลับ otTcpForwardProgress() และเรียก otTcpCircularSendBufferHandleForwardProgress() บน otTcpCircularSendBuffer ที่แนบมาที่จุดเริ่มต้นของฟังก์ชันเรียกกลับ ขอแนะนำไม่ให้ผู้ใช้ติดตั้งโค้ดเรียกกลับ otTcpSendDone() เนื่องจากการจัดการ otLinkedBuffers ทั้งหมดจะจัดการโดยบัฟเฟอร์ส่งแบบวงกลม

แอปพลิเคชันไม่ควรตรวจสอบช่องต่างๆ ของโครงสร้างนี้โดยตรง และควรโต้ตอบกับช่องผ่านฟังก์ชัน TCP Circular Send Buffer API ที่มีลายเซ็นอยู่ในไฟล์นี้เท่านั้น

otTcpEndpointAndCircularSendBuffer

struct otTcpEndpointAndCircularSendBuffer otTcpEndpointAndCircularSendBuffer

โครงสร้างบริบทที่จะใช้กับ mbedtls_ssl_set_bio

ฟังก์ชัน

otTcpCircularSendBufferDeinitialize

otError otTcpCircularSendBufferDeinitialize(
  otTcpCircularSendBuffer *aSendBuffer
)

ยกเลิกค่าเริ่มต้นบัฟเฟอร์ส่งที่เป็นวงกลม TCP โดยจะถอดออกหากมีการเชื่อมต่อ

หากบัฟเฟอร์การส่งแบบวงกลม TCP ไม่ว่างเปล่า การดำเนินการนี้จะล้มเหลว

รายละเอียด
พารามิเตอร์	[in] aSendBuffer บัฟเฟอร์การส่งแบบวงกลม TCP เพื่อยกเลิกการเริ่มต้น
แสดงผลค่า	OT_ERROR_NONE ยกเลิกการเริ่มต้นบัฟเฟอร์ที่ส่งแบบวงกลม TCP สำเร็จแล้ว OT_ERROR_BUSY บัฟเฟอร์แบบวงกลมมีข้อมูลอยู่และไม่สามารถลบค่าเริ่มต้นได้

otTcpCircularSendBufferForceDiscardAll

void otTcpCircularSendBufferForceDiscardAll(
  otTcpCircularSendBuffer *aSendBuffer
)

บังคับทิ้งข้อมูลทั้งหมดในบัฟเฟอร์ส่งแบบวงกลม

แอปพลิเคชันควรเรียกใช้ฟังก์ชันนี้เมื่อการเชื่อมต่อ TCP สิ้นสุดลงโดยไม่เจตนา (เช่น หากแอปพลิเคชันเรียก otTcpEndpointAbort() หรือได้รับแจ้งเกี่ยวกับการเชื่อมต่อที่รีเซ็ตผ่าน otTcpConnectionLost() callback)

การเรียกใช้ฟังก์ชันนี้บนบัฟเฟอร์การส่งแบบวงกลม TCP ที่ไม่ว่างเปล่าซึ่งแนบอยู่กับปลายทาง TCP จะทำให้เกิดลักษณะการทำงานที่ไม่ได้กำหนด

รายละเอียด
พารามิเตอร์	[in] aSendBuffer บัฟเฟอร์การส่งแบบวงกลม TCP ที่มีข้อมูลที่จะยกเลิก

otTcpCircularSendBufferGetFreeSpace

size_t otTcpCircularSendBufferGetFreeSpace(
  const otTcpCircularSendBuffer *aSendBuffer
)

แสดงผลปริมาณพื้นที่ว่างในบัฟเฟอร์การส่งแบบวงกลม TCP

การดำเนินการนี้จะสำเร็จเสมอ

รายละเอียด
พารามิเตอร์	[in] aSendBuffer ตัวชี้ไปยังบัฟเฟอร์การส่งแบบวงกลม TCP ซึ่งมีปริมาณพื้นที่ว่างที่จะส่งคืน
การส่งคืน	ปริมาณพื้นที่ว่างในบัฟเฟอร์ที่ส่ง

otTcpCircularSendBufferHandleForwardProgress

void otTcpCircularSendBufferHandleForwardProgress(
  otTcpCircularSendBuffer *aSendBuffer,
  size_t aInSendBuffer
)

จัดการ Circlar-send-buffer ที่เฉพาะเจาะจงในการเรียกกลับ otTcpForwardProgress

แอปพลิเคชันควรติดตั้งโค้ดเรียกกลับ otTcpForwardProgress() บน otTcpEndpoint และเรียกใช้ฟังก์ชันนี้ที่จุดเริ่มต้นของฟังก์ชันเรียกกลับสำหรับการประมวลผลแบบ Cirir-send-buffer

ในฟังก์ชันเรียกกลับ แอปพลิเคชันสามารถระบุปริมาณพื้นที่ว่างในบัฟเฟอร์การส่งแบบวงกลมด้วยการเรียกใช้ otTcpCircularSendBufferFreeSpace() หรือเปรียบเทียบ aInSendBuffer กับความจุของบัฟเฟอร์การส่ง ซึ่งผู้ใช้เลือกเมื่อเรียกใช้ otTcpCircularSendBufferInitialize()

รายละเอียด
พารามิเตอร์	[in] aSendBuffer ตัวชี้ไปยังบัฟเฟอร์การส่งแบบวงกลม TCP สำหรับปลายทางที่มีการเรียกใช้ otTcpForwardProgress() [in] aInSendBuffer ส่งค่า aInSendBuffer ไปยังโค้ดเรียกกลับ otTcpForwardProgress()

otTcpCircularSendBufferInitialize

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

เริ่มต้นบัฟเฟอร์การส่งแบบวงกลม TCP

รายละเอียด
พารามิเตอร์	[in] aSendBuffer ตัวชี้ไปยังบัฟเฟอร์ส่งวงกลม TCP เพื่อเริ่มต้น [in] aDataBuffer ตัวชี้ไปยังหน่วยความจำที่จะใช้เก็บข้อมูลในบัฟเฟอร์การส่งแบบวงกลม TCP [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 และปลายทาง TCP คือการรอให้บัฟเฟอร์ที่ส่งว่างเปล่าโดยสิ้นเชิง ซึ่งเกิดขึ้นได้ 2 ทาง คือ (1) มีการส่งและรับทราบข้อมูลทั้งหมดในบัฟเฟอร์ที่ส่งและได้รับในระหว่างการดำเนินการของโปรโตคอล TCP ตามปกติ หรือ (2) การเชื่อมต่อสิ้นสุดลง

รูปแบบการใช้งานที่แนะนำคือการใช้บัฟเฟอร์ส่งแบบวงกลม TCP เดียวที่มีปลายทาง TCP และเพื่อส่งข้อมูลบนปลายทาง TCP นั้นผ่านบัฟเฟอร์วงกลม TCP ที่เกี่ยวข้องเท่านั้น รูปแบบการใช้งานที่แนะนำนี้จะช่วยป้องกันปัญหาที่อธิบายไว้ข้างต้นด้วยการใช้ปลายทาง TCP และบัฟเฟอร์การส่งแบบวงกลม TCP ร่วมกันเสมอ

หากบัฟเฟอร์การส่งแบบวงเวียนถึงความจุ ระบบจะคัดลอกเฉพาะคำนำหน้าของข้อมูลที่ให้ไว้ลงในบัฟเฟอร์การส่งแบบวงกลมเท่านั้น

รายละเอียด
พารามิเตอร์	[in] aEndpoint ปลายทาง TCP ที่จะส่งข้อมูลออก [in] aSendBuffer บัฟเฟอร์การส่งแบบวงกลม TCP ที่จะคัดลอกข้อมูล [in] aData ตัวชี้ไปยังข้อมูลที่จะคัดลอกลงในบัฟเฟอร์การส่งแบบวงกลม TCP [in] aLength ความยาวของข้อมูลที่ชี้โดย aData เพื่อคัดลอกไปยังบัฟเฟอร์การส่งแบบวงกลม TCP [out] aWritten ป้อนข้อมูลด้วยจำนวนข้อมูลที่คัดลอกลงในบัฟเฟอร์การส่ง ซึ่งอาจน้อยกว่า aLength หากบัฟเฟอร์การส่งถึงขีดจำกัด [in] aFlags แฟล็กที่ระบุตัวเลือกสำหรับการดำเนินการนี้ (ดูการแจกแจงด้านบน)
แสดงผลค่า	OT_ERROR_NONE คัดลอกข้อมูลลงในบัฟเฟอร์การส่งและส่งไปยังปลายทาง TCP สำเร็จแล้ว 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

แหล่งข้อมูล

หัวข้ออ้างอิง API ของ OpenThread จะมาจากซอร์สโค้ดซึ่งพร้อมใช้งานใน GitHub ดูข้อมูลเพิ่มเติมหรือมีส่วนร่วมในเอกสารประกอบของเราได้ที่แหล่งข้อมูล