nl::Weave::Binding

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

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

摘要

Binding 物件可識別 Weave 通訊的預期目標 (也稱為「對等點」)，以及一組設定參數，說明與對等點之間的通訊方式。繫結與雙方之間所用的應用程式通訊協定無關。因此，它們擷取出溝通的「是誰」和「方式」，而不是「內容」。

設定

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

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

準備

在通訊前，繫結必須「準備」。準備繫結的行為包括建立通訊的必要狀態。這可能包括：解析對等點的網路位址、建立網路連線，以及協商安全金鑰。由應用程式設定後，Binding 會負責處理通訊準備所需的所有步驟，並在程序完成時呼叫應用程式。透過這種方式，繫結會隱藏通訊機制，讓應用程式能專注於高階互動。

通訊

備妥繫結後，即可開始使用。在這個狀態下，應用程式 (或更常見於代表應用程式工作的通訊協定層程式碼) 要求 Binding，以分配 Weave 交換內容。結果交換機制已預先設定通訊用途，讓應用程式立即啟動 Weave 與同類應用程式交換。應用程式可以繼續向繫結要求交換內容，直到 Binding 關閉或部分事件 (例如網路故障) 終止基礎通訊管道為止。

繫結狀態變更

無論在何種情況下，繫結會將 API 事件傳送給應用程式，通知應用程式 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
請重新設定現有的 Exchange 結構定義，藉此調整回應逾時時間。
AllocateRightSizedBuffer(PacketBuffer *& buf, const uint32_t desiredSize, const uint32_t minSize, uint32_t & outMaxPayloadSize)
BeginConfiguration()
設定繫結。
CanBePrepared(void) const
bool
Close(void)
void
關閉繫結物件並釋出參照。
GetConnection() const
取得與繫結相關聯的 Weave 連線物件。
GetDefaultResponseTimeout() const
uint32_t
取得與對等點通訊時，要使用的預設廣告交易平台回應逾時時間。
GetDefaultWRMPConfig(void) const
const WRMPConfig &
取得在與對等點通訊時要使用的預設 WRMP 設定。
GetEncryptionType(void) const
uint8_t
擷取加密與同類訊息時要使用的郵件加密類型。
GetEventCallback() const
EventCallback
取得在繫結發生 API 事件時要呼叫的函式。
GetExchangeManager() const
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)
分配新的 Exchange 結構定義，以便與繫結目標的對等點通訊。
Release(void)
void
釋出繫結物件的參照。
RequestPrepare()
要求應用程式設定及準備繫結。
Reset(void)
void
將繫結重設為未設定的狀態。
SetDefaultResponseTimeout(uint32_t msec)
void
設定與對等點通訊時使用的預設廣告交易平台回應逾時。
SetDefaultWRMPConfig(const WRMPConfig & wrmpConfig)
void
設定與對等點通訊時使用的預設 WRMP 設定。
SetEventCallback(EventCallback aEventCallback)
void
設定在繫結發生 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 物件。

結構
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

取得在繫結發生 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 (包括 UDP 和 WRM)，傳回的酬載大小上限可確保產生的 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
緩衝區指向的緩衝區大小。

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

詳細說明
傳回
如果 Binding 處於「就緒」狀態，則為 True。

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 或失敗狀態的繫結上呼叫這個方法。

如果應用程式不支援隨選設定/準備繫結，此方法就會失敗並發生 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
)

設定在繫結發生 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
由事件回呼傳遞的輸出事件參數參考資料