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 khả năng kết nối và khả năng tiếp cận của nút Weave.

Các ứng dụng có thể sử dụng lớp WeaveEchoClient để gửi thông báo EchoRequest một lần hoặc lặp lại đến nút ngang hàng được xác định bằng đối tượng Binding. Có một lớp tương ứng để 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 đối tượng Binding của Weave dùng để xác định và thiết lập hoạt động giao tiếp với người nhận yêu cầu tiếng vọng dự định. Ứ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 được chuẩn bị. Trong trường hợp đó, WeaveEchoClient sẽ yêu cầu chuẩn bị liên kết theo yêu cầu (xem phần Binding::Request Prepare() để biết thông tin chi tiết).

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

Chế độ lặp lại

Bạn có thể sử dụng phương thức SendRepeating() để đặt WeaveEchoClient ở chế độ SendRepeating. Ở chế độ này, đối tượng ứng dụng gửi một chuỗi thông báo EchoRequest lặp lại đến ứng dụng ngang hàng theo khoảng thời gian đã đị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 phát

Bạn có thể sử dụng đối tượng WeaveEchoClient để gửi EchoRequests tới 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 địa chỉ phát đa hướng IPv6 hoặc địa chỉ phát sóng mạng cục bộ IPv4 (255.255.255.255). Khi đối tượng WeaveEchoClient phát hiện thấy một địa chỉ ngang hàng truyền phát hoặc phát đa hướng, đối tượng này sẽ tự động chuyển sang chế độ MultiResponse khi gửi EchoRequest.

Ở chế độ này, đối tượng sẽ tiếp tục lắng nghe và gửi tất cả tin nhắn 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, thời gian sẽ gửi 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 hành động 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 đang được định cấu hình trên đối tượng ứng dụng. Ngoại trừ trường hợp được lưu ý, các ứng dụng có thể tự do thay đổi trạng thái ứng dụng trong lệnh gọi lại sự kiện. Một trường hợp 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 một 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 có 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 có độ dài bằng 0 sẽ được gửi tự động. Ứng dụng KHÔNG ĐƯỢC 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

Ứng dụng ngang hàng đã nhận được một thông báo EchoResponse. Đối số cho sự kiện 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 khi chờ phản hồi. Ví dụ về lỗi có thể xảy ra trong khi chờ phản hồi là lỗi chính hoặc lỗi đóng kết nối ngoài dự kiến. Các đối số cho sự kiện có chứa lý do lỗi.

ResponseTimeout

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

RequestAborted

Quá trình trao đổi Echo đang diễn ra đã bị huỷ do bạn đã yêu cầu gửi một EchoRequest khác trước khi nhận được phản hồi cho tin nhắn trước đó. Điều này có thể phát sinh trong chế độ SendRepeating khi đến thời gian để 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 một 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ế độ MultiResponse, 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à hàm phá
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

Thuộc tính công khai
AppState
void *
Con trỏ tới 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 đố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ề giá trị 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 cho ứng dụng ngang hàng.
Send(PacketBuffer *payloadBuf)
Gửi tin nhắn EchoRequest cho ứ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 thông báo EchoRequest lặp lại cho ứ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 trao đổi tiếng Echo đang diễn ra và hủy 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 API WeaveEchoClient.

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

Xuất 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 giao tiếp 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 này đượ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ỷ do hệ thống đã gửi 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

Ứng dụng ngang hàng đã nhận được một thông báo EchoResponse.

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 ở trạng thái rảnh.

kState_NotInitialized

Đối tượng ứng dụng chưa được khởi tạo.

kState_PreparingBinding

Đối tượng ứng dụng đ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

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

Thuộc tính công khai

AppState

void * AppState

Con trỏ tới 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.

Bắt đầu

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

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

Khởi động đối tượng WeaveEchoClient để chuẩn bị gửi thông báo tiếng vọng cho ứng dụng ngang hàng.

Thông tin chi tiết
Thông số
[in] binding
Đối tượng Binding (Liên kết) sẽ được dùng để thiết lập hoạt động giao tiếp với nút ngang hàng.
[in] eventCallback
Con trỏ đến một hàm sẽ được đối tượng WeaveEchoClient gọi để phân phối các sự kiện API đến ứng dụng.
[in] appState
Con trỏ đến một đối tượng do ứng dụng xác định 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ề giá trị 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 cho ứng dụng ngang hàng.

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

Khi tạo thông báo EchoRequest, WeaveEchoClient sẽ gửi yêu cầu đến ứ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 phương thức này được gọi, thì hệ thống sẽ gửi yêu cầu đến phương thức Binding::Request Prepare() để bắt đầu quá trình chuẩn bị theo yêu cầu. Sau đó, thao tác gửi sẽ được đưa 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ó một lệnh gửi trước đó trong hàng đợi sẽ chỉ dẫn đến việc chỉ gửi một EchoRequest.

Việc gọi Send() trong khi WeaveEchoClient đang ở chế độ gửi lặp lại (tức là do lệnh gọi trước đó đến SendRepeating()) 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ế độ gửi lặp lại.

Gửi

WEAVE_ERROR Send(
  PacketBuffer *payloadBuf
)

Gửi tin nhắn EchoRequest cho ứ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 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 và khi người dùng nhận được thông báo EchoResponse tương ứng, thông báo đó sẽ được gửi đến ứ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 sang đối tượng WeaveEchoClient. Đối tượng này có trách nhiệm giải phóng đối tượng đó. Điều này luôn xảy ra bất kể phương thức 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ì hệ thống sẽ gửi yêu cầu đến phương thức Binding::Request Prepare() để 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ó một lệnh gửi trước đó trong hàng đợi sẽ chỉ dẫn đến việc chỉ gửi một EchoRequest.

Việc gọi Send() trong khi WeaveEchoClient đang ở chế độ gửi lặp lại (tức là do lệnh gọi trước đó đến SendRepeating()) 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ế độ gửi lặp lại.

Thông tin chi tiết
Thông số
[in] payloadBuf
Một đố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ẽ chuyển đến đối tượng WeaveEchoClient.

SendRepeating

WEAVE_ERROR SendRepeating(
  uint32_t sendIntervalMS
)

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

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

Khi SendRepeating() được gọi, WeaveEchoClient sẽ chuyển sang chế độ gửi lặp lại, trong đó chế độ này sẽ duy trì cho đến khi Stop() được gọi hoặc xảy ra lỗi Binding. 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 ban đầu của một trình tự xảy ra tại thời điểm SendRepeating() được gọi 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 đã chỉ định.

Mỗi khi một lượt gửi xảy ra, WeaveEchoClient sẽ gửi yêu cầu đến ứ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::Request Prepare() để bắt đầu quá trình chuẩn bị theo yêu cầu. Các lần gửi tin nhắn lặp lại khác 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 bạn chỉ có thể gọi phương thức này nếu phương thức Init() đã được gọi trước đó.

Dừng

void Stop(
  void
)

Dừng mọi trao đổi tiếng Echo đang diễn ra và hủy 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.

Ứng dụng bắt buộc 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ý. Tham số được cung cấp phải giống với tham số mà đối tượng ứng dụng truyền đến hàm trình xử lý sự kiện của ứng dụng.

Thông tin chi tiết
Thông số
[in] appState
Con 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 được lệnh gọi lại sự kiện chuyển qua
[in] inParam
Mã tham chiếu cho các thông số sự kiện đầu vào được lệnh gọi lại sự kiện chuyển đi
[in] outParam
Mã tham chiếu đến các thông số sự kiện đầu ra được lệnh gọi lại sự kiện chuyển đi