nl::Weave::Profiles::Echo_Next::WeaveEchoClient

#include <src/lib/profiles/echo/Next/WeaveEchoClient.h> 

Provides the ability to send Weave EchoRequest messages to a peer node and receive
the corresponding EchoResponse messages.

Tóm tắt

Lớp WeaveEchoClient triển khai phía trình khởi tạo của giao thức Weave Echo. Tương tự như giao thức ping ICMP, giao thức Weave Echo có thể được dùng để kiểm tra tính hoạt động và khả năng kết nối của nút Weave.

Các ứng dụng có thể dùng lớp WeaveEchoClient để gửi thông báo EchoRequest một lần hoặc lặp lại tới một nút ngang hàng được xác định bằng đối tượng Binding. Một lớp tương ứng tồn tại để phản hồi các yêu cầu tiếng vọng (xem WeaveEchoServer).

Liên kết ứng dụng

WeaveEchoClient lấy một đối tượng Weave Binding dùng để xác định và thiết lập hoạt động giao tiếp với người nhận dự kiến của các yêu cầu tiếng vọng. Ứng dụng có thể định cấu hình và chuẩn bị Binding trước khi khởi chạy đối tượng WeaveEchoClient hoặc có thể không chuẩn bị được. Trong trường hợp đó, WeaveEchoClient sẽ yêu cầu chuẩn bị liên kết theo yêu cầu (xem Binding::RequestPrepare() để biết thông tin chi tiết).

Yêu cầu chuẩn bị Liên kết theo yêu cầu cũng sẽ được yêu cầu nếu không thành công sau khi chuyển sang trạng thái Sẵn sàng.

Chế độ Gửi Lặp lại

Bạn có thể sử dụng phương thức SendRepeating() để đặt WeaveEchoClient vào chế độ SendRepeating. Ở chế độ này, đối tượng ứng dụng sẽ gửi một trình tự lặp lại các thông báo EchoRequest tới ứng dụng ngang hàng theo một khoảng thời gian được định cấu hình. Bạn có thể huỷ chế độ SendRepeating bằng cách gọi phương thức Stop().

Phát đa hướng và truyền tin

Có thể dùng đối tượng WeaveEchoClient để gửi EchoRequests đến nhiều người nhận cùng lúc bằng cách định cấu hình đối tượng Binding với một địa chỉ đa hướng IPv6 thích hợp hoặc địa chỉ truyền tin trên mạng cục bộ IPv4 (255.255.255.255). Khi phát hiện một địa chỉ ngang hàng phát sóng hoặc truyền đa hướng, đối tượng WeaveEchoClient sẽ tự động chuyển sang chế độ MultiResponse sau khi gửi EchoRequest.

Ở chế độ này, đối tượng tiếp tục nghe và gửi tất cả thông báo EchoResponse đến trong cùng một lần trao đổi. Đối tượng vẫn ở chế độ MultiResponse cho đến khi: 1) ứng dụng gọi Stop() hoặc Send(), 2) ở chế độ SendRepeating, đã đến lúc gửi một yêu cầu khác hoặc 3) không nhận được phản hồi nào và hết thời gian chờ nhận.

Sự kiện API

Trong quá trình hoạt động, đối tượng WeaveEchoClient sẽ gọi đến ứng dụng để yêu cầu các thao tác cụ thể hoặc gửi thông báo về các sự kiện quan trọng. Các lệnh gọi sự kiện API này được thực hiện đến hàm callback hiện được định cấu hình trên đối tượng ứng dụng. Ngoại trừ những trường hợp có lưu ý, các ứng dụng có thể tuỳ ý thay đổi trạng thái của ứng dụng trong khi gọi lại sự kiện. Một ngoại lệ chung là phương thức Shutdown() của đối tượng. Phương thức này có thể không bao giờ được gọi trong lệnh gọi lại.

Các sự kiện API sau đây được xác định:

PreparePayload

WeaveEchoClient sắp tạo thông báo EchoRequest và đang yêu cầu ứng dụng cung cấp tải trọng. Nếu muốn, ứng dụng có thể trả về một PacketBuffer mới chứa dữ liệu tải trọng. Nếu ứng dụng không xử lý sự kiện này, thì một EchoRequest có tải trọng độ dài bằng 0 sẽ được gửi tự động. Ứng dụng KHÔNG THỂ thay đổi trạng thái của WeaveEchoClient trong lệnh gọi lại này.

RequestSent

Một thông báo EchoRequest đã được gửi đến ứng dụng ngang hàng.

ResponseReceived

Đã nhận được tin nhắn EchoResponse từ ứng dụng ngang hàng. Các đối số cho sự kiện này chứa tải trọng phản hồi và thông tin meta về thông báo phản hồi.

CommunicationError

Đã xảy ra lỗi khi tạo hoặc gửi EchoRequest hoặc trong khi chờ phản hồi. Ví dụ về lỗi có thể xảy ra trong khi chờ phản hồi là các lỗi chính hoặc đóng kết nối ngoài dự kiến. Các đối số cho sự kiện này chứa lý do xảy ra lỗi.

ResponseTimeout

Không nhận được EchoResponse trong thời gian phân bổ. Thời gian chờ phản hồi do thuộc tính DefaultResponseResponse kiểm soát trên đối tượng Binding.

RequestAborted

Quá trình trao đổi Echo đang diễn ra đã bị huỷ bỏ vì có yêu cầu gửi một EchoRequest khác trước khi nhận được phản hồi cho thư trước. Vấn đề này có thể phát sinh ở chế độ SendRepeating khi đã đến thời điểm gửi EchoRequest tiếp theo. Điều này cũng có thể xảy ra nếu ứng dụng gọi Send() sau khi EchoRequest đã được gửi, nhưng trước khi nhận được bất kỳ phản hồi nào.

Khi đối tượng ở chế độ Nhiều phản hồi, sự kiện sẽ bị chặn nếu nhận được ít nhất một thông báo EchoResponse.

Hàm khởi tạo và phá huỷ
WeaveEchoClient(void)

Loại công khai
EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam) typedef
void(*
EventType{
  kEvent_PreparePayload = 1,
  kEvent_RequestSent = 2,
  kEvent_ResponseReceived = 3,
  kEvent_CommunicationError = 4,
  kEvent_ResponseTimeout = 5,
  kEvent_RequestAborted = 6,
  kEvent_DefaultCheck = 100
} 		enum
State{
  kState_NotInitialized = 0,
  kState_Idle = 1,
  kState_PreparingBinding = 2,
  kState_RequestInProgress = 3,
  kState_WaitingToSend = 4
} 		enum

Các thuộc tính công khai
AppState
void *
Con trỏ trỏ đến dữ liệu dành riêng cho ứng dụng.

Hàm công khai
GetBinding(void) const
Trả về một con trỏ đến đối tượng Binding (Liên kết) được liên kết với WeaveEchoClient.
GetEventCallback(void) const
EventCallback
Trả về một con trỏ đến hàm callback sự kiện API hiện được định cấu hình trên đối tượng WeaveEchoClient.
GetState(void) const
Truy xuất trạng thái hiện tại của đối tượng WeaveEchoClient.
Init(Binding *binding, EventCallback eventCallback, void *appState)
Khởi động một đối tượng WeaveEchoClient.
IsSendRrepeating() const
bool
Trả về true nếu đối tượng WeaveEchoClient hiện đang ở chế độ gửi lặp lại.
RequestInProgress() const
bool
Trả về true nếu một EchoRequest đã được gửi và đối tượng WeaveEchoClient đang chờ phản hồi.
Send(void)
Gửi tin nhắn EchoRequest đến ứng dụng ngang hàng.
Send(PacketBuffer *payloadBuf)
Gửi thông báo EchoRequest đến ứng dụng ngang hàng có tải trọng cụ thể.
SendRepeating(uint32_t sendIntervalMS)
Bắt đầu gửi một chuỗi các thông báo EchoRequest lặp lại tới ứng dụng ngang hàng.
SetEventCallback(EventCallback eventCallback)
void
Đặt hàm callback sự kiện API trên đối tượng WeaveEchoClient.
Shutdown(void)
void
Tắt đối tượng WeaveEchoClient đã khởi tạo trước đó.
Stop(void)
void
Dừng mọi quá trình trao đổi Echo đang diễn ra và huỷ chế độ gửi lặp lại.

Hàm tĩnh công khai
DefaultEventHandler(void *appState, EventType eventType, const InEventParam & inParam, OutEventParam & outParam)
void
Trình xử lý mặc định cho các sự kiện API WeaveEchoClient.

Cấu trúc
nl::Weave::Profiles::Echo_Next::WeaveEchoClient::InEventParam

Nhập các tham số vào sự kiện của API WeaveEchoClient.

nl::Weave::Profiles::Echo_Next::WeaveEchoClient::OutEventParam

Xuất các tham số cho sự kiện API WeaveEchoClient.

Loại công khai

EventCallback

void(* EventCallback)(void *appState, EventType eventType, const InEventParam &inParam, OutEventParam &outParam)

EventType

 EventType
Thuộc tính
kEvent_CommunicationError

Đã xảy ra lỗi kết nối khi gửi EchoRequest hoặc chờ phản hồi.

kEvent_DefaultCheck

Dùng để xác minh cách xử lý sự kiện mặc định chính xác trong ứng dụng.

kEvent_PreparePayload

Ứng dụng được yêu cầu chuẩn bị tải trọng cho yêu cầu Echo.

kEvent_RequestAborted

Một quá trình trao đổi Echo đang diễn ra đã bị huỷ vì có yêu cầu bắt đầu một lượt trao đổi khác.

kEvent_RequestSent

Một thông báo EchoRequest đã được gửi đến ứng dụng ngang hàng.

kEvent_ResponseReceived

Đã nhận được tin nhắn EchoResponse từ ứng dụng ngang hàng.

kEvent_ResponseTimeout

Không nhận được EchoResponse trong thời gian phân bổ.

Tiểu bang

 State
Thuộc tính
kState_Idle

Đối tượng ứng dụng đang ở trạng thái rảnh.

kState_NotInitialized

Chưa khởi chạy đối tượng ứng dụng khách.

kState_PreparingBinding

Đối tượng ứng dụng khách đang chờ liên kết sẵn sàng.

kState_RequestInProgress

Một thông báo EchoRequest đã được gửi và đối tượng ứng dụng đang chờ phản hồi.

kState_WaitingToSend

Đã gọi SendRepeating() và đối tượng ứng dụng đang chờ lần tiếp theo để gửi EchoRequest.

Các thuộc tính công khai

AppState

void * AppState

Con trỏ trỏ đến dữ liệu dành riêng cho ứng dụng.

Hàm công khai

GetBinding

Binding * GetBinding(
  void
) const

Trả về một con trỏ đến đối tượng Binding (Liên kết) được liên kết với WeaveEchoClient.

GetEventCallback

EventCallback GetEventCallback(
  void
) const

Trả về một con trỏ đến hàm callback sự kiện API hiện được định cấu hình trên đối tượng WeaveEchoClient.

GetState

State GetState(
  void
) const

Truy xuất trạng thái hiện tại của đối tượng WeaveEchoClient.

Init

WEAVE_ERROR Init(
  Binding *binding,
  EventCallback eventCallback,
  void *appState
)

Khởi động một đối tượng WeaveEchoClient.

Khởi chạy đối tượng WeaveEchoClient để chuẩn bị gửi thông báo lặp lại đến một ứng dụng ngang hàng.

Thông tin chi tiết
Tham số
[in] binding
Đối tượng Binding (Liên kết) được dùng để thiết lập hoạt động giao tiếp với nút ngang hàng.
[in] eventCallback
Con trỏ trỏ đến một hàm sẽ được đối tượng WeaveEchoClient gọi để gửi các sự kiện API đến ứng dụng.
[in] appState
Con trỏ trỏ đến một đối tượng do ứng dụng xác định và sẽ được trả về cho ứng dụng mỗi khi có sự kiện API xảy ra.

IsSendRrepeating

bool IsSendRrepeating() const

Trả về true nếu đối tượng WeaveEchoClient hiện đang ở chế độ gửi lặp lại.

RequestInProgress

bool RequestInProgress() const

Trả về true nếu một EchoRequest đã được gửi và đối tượng WeaveEchoClient đang chờ phản hồi.

Gửi

WEAVE_ERROR Send(
  void
)

Gửi tin nhắn EchoRequest đến ứng dụng ngang hàng.

Phương thức này sẽ bắt đầu quá trình gửi một thông báo EchoRequest đến nút ngang hàng. Nếu nhận được một thông báo EchoResponse tương ứng, thì thông báo đó sẽ được gửi tới ứng dụng thông qua sự kiện API ResponseReceived.

Khi hình thành thông báo EchoRequest, WeaveEchoClient sẽ gửi yêu cầu tới ứng dụng thông qua sự kiện PreparePayload API (API chuẩn bị) để chuẩn bị tải trọng của thông báo.

Nếu đối tượng Binding không ở trạng thái Sẵn sàng khi phương thức này được gọi, thì một yêu cầu sẽ được gửi đến phương thức Binding::RequestPrepare() để bắt đầu quá trình chuẩn bị theo yêu cầu. Sau đó, thao tác gửi sẽ được xếp vào hàng đợi cho đến khi quá trình này hoàn tất. Độ sâu tối đa của hàng đợi này là 1. Do đó, mọi lệnh gọi đến Send() trong khi có lệnh gửi trước đó trong hàng đợi sẽ chỉ dẫn đến một EchoRequest duy nhất được gửi.

Việc gọi Send() trong khi WeaveEchoClient đang ở chế độ gửi lặp lại (tức là do lệnh gọi đến SendRepeating() trước đó) có tác dụng tăng tốc và đặt lại chu kỳ gửi nhưng không đưa WeaveEchoClient ra khỏi chế độ lặp lại gửi.

Gửi

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Gửi thông báo EchoRequest đến ứng dụng ngang hàng có tải trọng cụ thể.

Phương thức này sẽ bắt đầu quá trình gửi một thông báo EchoRequest đến nút ngang hàng. Nội dung của vùng đệm tải trọng đã cung cấp sẽ được gửi đến ứng dụng ngang hàng dưới dạng tải trọng của thông báo EchoRequest. Nếu nhận được một thông báo EchoResponse tương ứng, thì thông báo đó sẽ được gửi tới ứng dụng thông qua sự kiện API ResponseReceived.

Khi gọi phương thức này, quyền sở hữu vùng đệm tải trọng đã cung cấp sẽ chuyển đến đối tượng WeaveEchoClient. Đối tượng này có trách nhiệm giải phóng vùng đệm đó. Điều này luôn đúng bất kể phương thức hoàn tất thành công hay có lỗi.

Nếu đối tượng Binding không ở trạng thái Sẵn sàng khi phương thức này được gọi, thì một yêu cầu sẽ được gửi đến phương thức Binding::RequestPrepare() để bắt đầu quá trình chuẩn bị theo yêu cầu. Sau đó, thao tác gửi sẽ được xếp vào hàng đợi cho đến khi quá trình này hoàn tất. Độ sâu tối đa của hàng đợi này là 1. Do đó, mọi lệnh gọi đến Send() trong khi có lệnh gửi trước đó trong hàng đợi sẽ chỉ dẫn đến một EchoRequest duy nhất được gửi.

Việc gọi Send() trong khi WeaveEchoClient đang ở chế độ gửi lặp lại (tức là do lệnh gọi SendRepeating() trước đó) có tác dụng tăng tốc và đặt lại chu kỳ gửi nhưng không đưa WeaveEchoClient ra khỏi chế độ lặp lại gửi.

Thông tin chi tiết
Tham số
[in] payloadBuf
Đối tượng PacketBuffer chứa dữ liệu tải trọng sẽ được gửi đến ứng dụng ngang hàng. Trong mọi trường hợp, quyền sở hữu vùng đệm này sẽ truyền đến đối tượng WeaveEchoClient.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

Bắt đầu gửi một chuỗi các thông báo EchoRequest lặp lại tới ứng dụng ngang hàng.

Phương thức này sẽ bắt đầu một quá trình lặp lại gửi thông báo EchoRequest đến ứng dụng ngang hàng. Khi thông báo EchoResponse nhận được từ ứng dụng ngang hàng, chúng sẽ được gửi đến ứng dụng qua sự kiện API ResponseReceived.

Khi gọi SendRepeating(), WeaveEchoClient sẽ chuyển sang chế độ gửi-lặp lại, trong đó hàm này vẫn ở đó cho đến khi Stop() được gọi hoặc lỗi Binding (Liên kết) xảy ra. Việc gọi SendRepeating() nhiều lần có tác dụng đặt lại chu kỳ gửi và cập nhật khoảng thời gian.

Lần gửi chuỗi ban đầu xảy ra tại thời điểm gọi SendRepeating() hoặc bất cứ khi nào Binding sẵn sàng sau khi SendRepeating() được gọi (xem bên dưới). Các lần gửi tiếp theo sẽ diễn ra sau đó vào khoảng thời gian được chỉ định.

Mỗi khi xảy ra một lượt gửi, WeaveEchoClient sẽ gửi một yêu cầu tới ứng dụng thông qua sự kiện PreparePayload API, để chuẩn bị tải trọng của thông báo.

Nếu đối tượng Binding không ở trạng thái Sẵn sàng khi đến lúc gửi thư, thì yêu cầu sẽ được gửi đến phương thức Binding::RequestPrepare() để bắt đầu chuẩn bị theo yêu cầu. Các lần gửi tin nhắn lặp lại tiếp theo sẽ bị tạm dừng cho đến khi quá trình này hoàn tất. Lỗi trong quá trình chuẩn bị Liên kết theo yêu cầu sẽ khiến WeaveEchoClient rời khỏi chế độ gửi lặp lại.

SetEventCallback

void SetEventCallback(
  EventCallback eventCallback
)

Đặt hàm callback sự kiện API trên đối tượng WeaveEchoClient.

Tắt

void Shutdown(
  void
)

Tắt đối tượng WeaveEchoClient đã khởi tạo trước đó.

Lưu ý rằng phương thức này chỉ có thể được gọi nếu phương thức Init() đã được gọi trước đó.

Dừng

void Stop(
  void
)

Dừng mọi quá trình trao đổi Echo đang diễn ra và huỷ chế độ gửi lặp lại.

WeaveEchoClient

 WeaveEchoClient(
  void
)

Hàm tĩnh công khai

DefaultEventHandler

void DefaultEventHandler(
  void *appState,
  EventType eventType,
  const InEventParam & inParam,
  OutEventParam & outParam
)

Trình xử lý mặc định cho các sự kiện API WeaveEchoClient.

Các ứng dụng cần phải gọi phương thức này cho mọi sự kiện API mà ứng dụng không nhận dạng hoặc xử lý được. Các tham số được cung cấp phải giống với tham số mà đối tượng ứng dụng chuyển đến hàm trình xử lý sự kiện của ứng dụng.

Thông tin chi tiết
Tham số
[in] appState
Con trỏ trỏ đến thông tin trạng thái do ứng dụng xác định được liên kết với đối tượng ứng dụng.
[in] eventType
Mã sự kiện bị lệnh gọi lại sự kiện truyền
[in] inParam
Tham chiếu các thông số sự kiện đầu vào được lệnh gọi lại sự kiện truyền
[in] outParam
Tham chiếu đến các thông số sự kiện đầu ra được lệnh gọi lại sự kiện truyền