本頁面由 Cloud Translation API 翻譯而成。

nl::Weave::Binding

#include <src/lib/core/WeaveBinding.h>

擷取 Weave 通訊的預期目標和相關設定資訊。

摘要

Binding 物件可識別 Weave 通訊的預期目標 (也稱為「同業」)，以及一組描述應如何與對等點通訊的設定參數。繫結獨立於雙方間通說的應用程式通訊協定。因此自動鎖定「對象」「做法」而不是「什麼」

應用程式必須設定繫結，其中包含所需通訊管道類型專用的參數。繫結支援多種網路傳輸，包括 TCP、UDP、UDP 搭配 Weave Reliable Messaging 和 BLE 的 Weave (WoBLE)。應用程式也可以要求使用特定的安全性機制，以保護雙方之間傳送的訊息。其中包括 CASE 和 PASE 工作階段，以及應用程式群組金鑰。設定 Binding 的介面使用宣告式 API 樣式，可讓應用程式以簡單的術語說明通訊的需求。

詳情請參閱 Binding::Configuration 文件。

準備

進行通訊之前，您必須「備妥」繫結。準備繫結的行動涉及建立通訊所需的必要的狀態。這可能包括：解析對等點的網路位址、建立網路連線，以及交涉安全金鑰。應用程式設定後，Binding 會負責準備通訊的所有必要步驟，並在程序完成後回呼應用程式。這樣一來，Binding 就能隱藏通訊機制，讓應用程式專注於高階互動。

通訊

繫結準備就緒後即可使用。在這個狀態下，應用程式 (或更常是代表應用程式運作的通訊協定層程式碼) 會要求 Binding 來分配 Weave 交換結構定義。結果交換背景已預先設定為通訊，可讓應用程式立即與對等點啟動 Weave 交換。應用程式可以繼續要求交換結構定義，直到繫結關閉等時間，或是某些事件 (例如網路故障) 終止基礎通訊管道。

繫結狀態變更

在使用過程中，繫結會將 API 事件傳送至應用程式，通知應用程式 Binding 的狀態變更。舉例來說，準備成功時，應用程式會收到事件，告知 Binding 已可供使用。同樣地，如果基礎通訊管道失敗，系統會將事件傳送至應用程式，告知應用程式 Binding 已處於就緒狀態。

在分配 Binding 時，系統會透過所提供的事件回呼函式，將 API 事件傳送至應用程式。

繫結生命週期

計算繫結時，允許多個軟體元件共用此類資源。當系統配置繫結時，即會建立該繫結的單一參照。應用程式會負責於日後的某個時間點釋出此參照，讓 Binding 免費供後續重複使用。

應用程式完成繫結時，可以在繫結上呼叫 Close()。這樣做會釋出應用程式對 Binding 的參照，並封鎖所有進一步的 API 事件提交。釋放最後一個參照繫結時，系統會自動關閉該參照。

公開類型
`@23{ kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength }`	列舉
`EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)`	typedef `void(*`
`EventType{ kEvent_ConnectionEstablished = 1, kEvent_BindingReady = 2, kEvent_PrepareFailed = 3, kEvent_BindingFailed = 4, kEvent_PrepareRequested = 5, kEvent_PASEParametersRequested = 6, kEvent_TAKEParametersRequested = 7, kEvent_DefaultCheck = 100 }`	列舉
`State`	列舉

公開屬性
`AppState`	`void *`

公開函式
`AddRef(void)`	`void` 保留繫結物件的參照。
`AdjustResponseTimeout(ExchangeContext *apExchangeContext) const`	`WEAVE_ERROR` 重新設定現有的 Exchange 情境以調整回應逾時時間。
`AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)`	`WEAVE_ERROR`
`BeginConfiguration()`	`Configuration` 執行設定繫結的程序。
`CanBePrepared(void) const`	`bool`
`Close(void)`	`void` 關閉繫結物件並釋出參照。
`GetConnection() const`	`WeaveConnection *` 取得與繫結相關聯的 Weave 連線物件。
`GetDefaultResponseTimeout() const`	`uint32_t` 取得與對等點通訊時使用的預設廣告交易平台回應逾時時間。
`GetDefaultWRMPConfig(void) const`	`const WRMPConfig &` 取得與對等點通訊時使用的預設 WRMP 設定。
`GetEncryptionType(void) const`	`uint8_t` 擷取與對等端之間的訊息加密時，要使用的郵件加密類型。
`GetEventCallback() const`	`EventCallback` 取得將在 Binding 發生 API 事件時呼叫的函式。
`GetExchangeManager() const`	`WeaveExchangeManager *`
`GetKeyId(void) const`	`uint32_t` 擷取與對等端之間的訊息加密時，要使用的郵件加密金鑰 ID。
`GetLogId(void) const`	`uint16_t` 取得繫結的專屬 ID。
`GetMaxWeavePayloadSize(const System::PacketBuffer *msgBuf)`	`uint32_t` 取得隨附在提供的 PacketBuffer 內的 Weave 酬載大小上限。
`GetPeerDescription(char *buf, uint32_t bufSize) const`	`void` 建構用來說明對等節點及其關聯位址 / 連線資訊的字串。
`GetPeerIPAddress(nl::Inet::IPAddress & address, uint16_t & port, InterfaceId & interfaceId) const`	`void` 擷取對等點的 IP 位址資訊 (如果有的話)。
`GetPeerNodeId(void) const`	`uint64_t` 擷取繫結對等點的節點 ID。
`GetProtocolLayerCallback(EventCallback & callback, void *& state) const`	`void`
`GetState(void) const`	`State` 擷取繫結的目前狀態。
`IsAuthenticMessageFromPeer(const WeaveMessageInfo *msgInfo)`	`bool` 判斷特定收到的郵件是否來自設定的對等郵件，並且是否可通過驗證。
`IsConnectionTransport() const`	`bool`
`IsPreparing(void) const`	`bool`
`IsReady(void) const`	`bool`
`IsUDPTransport() const`	`bool`
`IsUnreliableUDPTransport() const`	`bool`
`IsWRMTransport() const`	`bool`
`NewExchangeContext(ExchangeContext *& appExchangeContext)`	`WEAVE_ERROR` 分配新的 Exchange 情境，以與繫結為目標的對等體進行通訊。
`Release(void)`	`void` 釋出繫結物件的參照。
`RequestPrepare()`	`WEAVE_ERROR` 要求應用程式設定和準備繫結。
`Reset(void)`	`void` 將繫結重設為未設定的狀態。
`SetDefaultResponseTimeout(uint32_t msec)`	`void` 設定與對等點通訊時使用的預設廣告交易平台回應逾時時間。
`SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)`	`void` 設定與對等點通訊時要使用的預設 WRMP 設定。
`SetEventCallback(EventCallback aEventCallback)`	`void` 設定在 Binding 發生 API 事件時要呼叫的應用程式定義函式。
`SetProtocolLayerCallback(EventCallback callback, void *state)`	`void` 使用 Binding 代表應用程式，為通訊協定層程式碼設定事件回呼函式。

公開的靜態函式
`DefaultEventHandler(void *apAppState, EventType aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)`	`void` 繫結 API 事件的預設處理常式。

類別
nl::Weave::Binding::Configuration	提供宣告式介面，用於設定及準備 Binding 物件。

Structs
nl::Weave::Binding::InEventParam	Binding API 事件的輸入參數。
nl::Weave::Binding::OutEventParam	將參數輸出至 Binding API 事件。

公開類型

23 次

@23

屬性
`kGetPeerDescription_MaxLength`	GetPeerDescription() 傳回的字串長度上限 (包括 NUL 字元)。

EventCallback

void(* EventCallback)(void *apAppState, EventType aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)

EventType

 EventType

屬性
`kEvent_BindingFailed`	繫結失敗，無法再用於與對等點通訊。
`kEvent_BindingReady`	繫結的準備動作已成功執行，繫結現在可以用來與對等點通訊。
`kEvent_ConnectionEstablished`	要求的 Weave 連線已建立。
`kEvent_DefaultCheck`	用於驗證應用程式中正確的預設事件處理方式。
`kEvent_PASEParametersRequested`	應用程式要求提供參數，以便在建立 PASE 工作階段時使用。
`kEvent_PrepareFailed`	無法對繫結執行準備動作。
`kEvent_PrepareRequested`	應用程式要求為設定及準備繫結，以供網路堆疊使用。
`kEvent_TAKEParametersRequested`	應用程式要求提供參數，以便在 TAKE 工作階段建立期間使用。

州

 State

公開屬性

AppState

void * AppState

公開函式

AddRef

void AddRef(
  void
)

保留繫結物件的參照。

AdjustResponseTimeout

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const

重新設定現有的 Exchange 情境以調整回應逾時時間。

詳細資料

參數

[in] apExchangeContext

指向要重新設定的 Exchange Context 物件的指標

AllocateRightSizedBuffer

WEAVE_ERROR AllocateRightSizedBuffer(
  PacketBuffer *& buf,
  const uint32_t desiredSize,
  const uint32_t minSize,
  uint32_t & outMaxPayloadSize
)

BeginConfiguration

Configuration BeginConfiguration()

執行設定繫結的程序。

應用程式必須先呼叫 BeginConfiguration() 設定 Binding，然後再準備與對等點通訊。

詳細資料
傳回	可用來設定繫結的 Binding::Configuration 物件。

CanBePrepared

bool CanBePrepared(
  void
) const

關閉

void Close(
  void
)

關閉繫結物件並釋出參照。

呼叫此方法時，繫結會進入封閉狀態。系統會取消繫結正在進行的準備動作，並釋出繫結持有的所有外部通訊資源。

呼叫 Close() 可減少與繫結相關的參考計數，並在參照計數變成零時釋出物件。

GetConnection

WeaveConnection * GetConnection() const

取得與繫結相關聯的 Weave 連線物件。

詳細資料
傳回	指向 WeaveConnection 物件的指標；如果繫結沒有相關聯的連線，則指向 NULL。

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const

取得與對等點通訊時使用的預設廣告交易平台回應逾時時間。

詳細資料
傳回	回應逾時時間 (以毫秒為單位)。

GetDefaultWRMPConfig

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const

取得與對等點通訊時使用的預設 WRMP 設定。

詳細資料
傳回	包含預設設定值的 WRMPConfig 結構參照。

GetEncryptionType

uint8_t GetEncryptionType(
  void
) const

擷取與對等端之間的訊息加密時，要使用的郵件加密類型。

GetEventCallback

EventCallback GetEventCallback() const

取得將在 Binding 發生 API 事件時呼叫的函式。

詳細資料
傳回	回呼函式的指標。

GetExchangeManager

WeaveExchangeManager * GetExchangeManager() const

GetKeyId

uint32_t GetKeyId(
  void
) const

擷取與對等端之間的訊息加密時，要使用的郵件加密金鑰 ID。

GetLogId

uint16_t GetLogId(
  void
) const

取得繫結的專屬 ID。

GetMaxWeavePayloadSize

uint32_t GetMaxWeavePayloadSize(
  const System::PacketBuffer *msgBuf
)

取得隨附在提供的 PacketBuffer 內的 Weave 酬載大小上限。

如果是 UDP (包括搭配 WRM 的 UDP)，傳回的酬載大小上限可確保產生的 Weave 訊息不會溢位已設定的 UDP MTU。

此外，這個方法能確保 Weave 有效負載不會溢位提供的 PacketBuffer。

詳細資料

參數

[in] msgBuf

要寫入訊息酬載的 PacketBuffer 指標。

傳回

Weave 酬載大小上限。

GetPeerDescription

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const

建構用來說明對等節點及其關聯位址 / 連線資訊的字串。

詳細資料

參數

`[in] buf`	指向應寫入字串的緩衝區指標。提供的緩衝區至少應該與 kGetPeerDescription_MaxLength 一樣大。如果提供的緩衝區較小，字串將截斷以符合尺寸。所有案例的輸出內容都會包含 NUL 終止字元。
`[in] bufSize`	以 buf 指向的緩衝區大小。

GetPeerIPAddress

void GetPeerIPAddress(
  nl::Inet::IPAddress & address,
  uint16_t & port,
  InterfaceId & interfaceId
) const

擷取對等點的 IP 位址資訊 (如果有的話)。

對等點 IP 位址資訊的可用性取決於繫結的狀態和設定。只有在使用 IP 型傳輸方式 (TCP、UDP 或 UDP 搭配 WRMP) 時，才能使用 IP 位址資訊。在開始準備之前，地址資訊只有在應用程式在設定期間明確設定的情況下才能使用。在準備階段，系統會在地址準備完成時 (例如 DNS 解析完成後)，提供地址資訊。繫結設定完成後，地址資訊仍會持續顯示，直到繫結重設為止。

詳細資料

參數

`[out] address`	要接收對等點 IP 位址的 IPAddress 物件參照。如果無法取得對等點的 IP 位址資訊，這個值將設為 IPAddress::Any。
`[out] port`	接收對等通訊埠號碼的整數參照。如果無法取得對等點的 IP 位址資訊，表示這個值未定義。
`[out] interfaceId`	整數的參照，用於接收可連上對等點的網路介面 ID。如果無法取得對等點的 IP 位址資訊，表示這個值未定義。

GetPeerNodeId

uint64_t GetPeerNodeId(
  void
) const

擷取繫結對等點的節點 ID。

只有在繫結物件準備就緒後才會生效。

詳細資料
傳回	對等點的 Weave 節點 ID

GetProtocolLayerCallback

void GetProtocolLayerCallback(
  EventCallback & callback,
  void *& state
) const

GetState

State GetState(
  void
) const

擷取繫結的目前狀態。

詳細資料
傳回	繫結狀態。

IsAuthenticMessageFromPeer

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

判斷特定收到的郵件是否來自設定的對等郵件，並且是否可通過驗證。

這個方法會確認指定訊息的下列詳細資料：

訊息來自繫結的對等節點
透過繫結接收到與繫結相同的傳輸類型訊息。如果是透過連線收到訊息，此方法也會確認使用者是透過與繫結相關聯的確切連線收到訊息。
用來加密訊息的加密金鑰和類型與繫結中設定的金鑰和類型相符。如果是未設定安全性的繫結，此方法會確認傳入的訊息「未」加密。

此方法適用於在 WDM 等通訊協定中使用，讓對等端在從節點到對等點的初始交換後，自行啟動交換回本機節點。在這種情況下，此方法可讓本機節點確認傳入的垃圾訊息是否由相關聯的對等節點傳送。(當然，對於未採用郵件加密機制的繫結進行設定，這個斷言從安全性的角度而言並沒有任何價值。只是確認傳送方節點 ID 和傳輸類型相符。)

請注意，如果繫結未處於「就緒」狀態，此方法一律會傳回 false。

詳細資料

參數

[in] msgInfo

所收訊息的 Weave 訊息資訊。

傳回

如果訊息真實可靠，則為「是」。

IsConnectionTransport

bool IsConnectionTransport() const

IsPreparing

bool IsPreparing(
  void
) const

詳細資料
傳回	如果正在準備 Binding，則為 True。

IsReady

bool IsReady(
  void
) const

詳細資料
傳回	如果繫結處於「就緒」狀態，則為「是」。

IsUDPTransport

bool IsUDPTransport() const

IsUnreliableUDPTransport

bool IsUnreliableUDPTransport() const

IsWRMTransport

bool IsWRMTransport() const

NewExchangeContext

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

分配新的 Exchange 情境，以與繫結為目標的對等體進行通訊。

詳細資料

參數

[out] appExchangeContext

指標的參照，用於接收新分配的 Exchange Context 物件。在方法失敗的事件中，指標會設為 NULL。

傳回值

`WEAVE_NO_ERROR`	已成功分配廣告交易平台背景。
`WEAVE_ERROR_NO_MEMORY`	如果沒有可用的記憶體，無法分配交換環境。
`WEAVE_ERROR_INCORRECT_STATE`	如果繫結並非處於「就緒」狀態。
`other`	根據繫結設定設定交換情境的其他相關錯誤。

版本

void Release(
  void
)

釋出繫結物件的參照。

如果繫結物件沒有任何參照，則會關閉並釋出繫結。

RequestPrepare

WEAVE_ERROR RequestPrepare()

要求應用程式設定和準備繫結。

通訊協定層程式碼可在未設定或失敗的 Binding 上使用這個方法，向應用程式 (kEvent_PrepareRequested) 觸發事件並要求其設定及準備繫結以供使用。

只有處於「NotConfigured」或「Failed」狀態的繫結，才能呼叫這個方法。

如果應用程式不支援繫結的隨選設定/準備，此方法就會因 WEAVE_ERROR_NOT_IMPLEMENTED 而失敗。

重設

void Reset(
  void
)

將繫結重設為未設定的狀態。

呼叫 Reset() 時，將取消繫結所有進行中的準備動作，並釋出繫結持有的所有外部通訊資源。Reset() 將繫結置於「未設定」狀態，之後，系統就能重新設定並準備繫結。

Reset() 不會變更繫結的參考計數。

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

設定與對等點通訊時使用的預設廣告交易平台回應逾時時間。

詳細資料

參數

[in] timeout

新回應逾時時間 (以毫秒為單位)。

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

設定與對等點通訊時要使用的預設 WRMP 設定。

詳細資料

參數

[in] aWRMPConfig

WRMPConfig 結構的參照，其中包含新的預設設定。

SetEventCallback

void SetEventCallback(
  EventCallback aEventCallback
)

設定在 Binding 發生 API 事件時要呼叫的應用程式定義函式。

詳細資料

參數

[in] aEventCallback

回呼函式的指標。

SetProtocolLayerCallback

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

使用 Binding 代表應用程式，為通訊協定層程式碼設定事件回呼函式。

當 Binding 發生 API 事件時，除了應用程式定義的回呼函式外，系統也會呼叫這個函式。

詳細資料

參數

`[in] callback`	回呼函式的指標。
`[in] state`	狀態物件的指標，會在發生通訊協定層回呼時提供給通訊協定層程式碼。

公開的靜態函式

DefaultEventHandler

void DefaultEventHandler(
  void *apAppState,
  EventType aEvent,
  const InEventParam & aInParam,
  OutEventParam & aOutParam
)

繫結 API 事件的預設處理常式。

應用程式必須針對應用程式無法識別或處理的任何 API 事件呼叫這個方法。提供的參數必須與繫結傳遞至應用程式事件處理常式函式的參數相同。

詳細資料

參數

`[in] apAppState`	這個指標指向與繫結相關聯的應用程式定義狀態資訊。
`[in] aEvent`	事件回呼傳遞的事件 ID
`[in] aInParam`	事件回呼傳遞的輸入事件參數參照
`[in] aOutParam`	事件回呼傳遞的輸出事件參數參照

nl::Weave::Binding

摘要

公開類型

公開屬性

公開函式

公開的靜態函式

類別

Structs

公開類型

23 次

EventCallback

EventType

州

公開屬性

AppState

公開函式

AddRef

AdjustResponseTimeout

AllocateRightSizedBuffer

BeginConfiguration

CanBePrepared

關閉

GetConnection

GetDefaultResponseTimeout

GetDefaultWRMPConfig

GetEncryptionType

GetEventCallback

GetExchangeManager

GetKeyId

GetLogId

GetMaxWeavePayloadSize

GetPeerDescription

GetPeerIPAddress

GetPeerNodeId

GetProtocolLayerCallback

GetState

IsAuthenticMessageFromPeer

IsConnectionTransport

IsPreparing

IsReady

IsUDPTransport

IsUnreliableUDPTransport

IsWRMTransport

NewExchangeContext

版本

RequestPrepare

重設

SetDefaultResponseTimeout

SetDefaultWRMPConfig

SetEventCallback

SetProtocolLayerCallback

公開的靜態函式

DefaultEventHandler