透過集合功能整理內容 你可以依據偏好儲存及分類內容。

nl::編織::裝訂

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

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

總結

binding 物件可識別 Weave 通訊的預期目標 (也稱為「對等節點」),以及一組說明要如何與對等點通訊的方式。繫結與雙方之間所說的應用程式通訊協定無關。因此,他們會傳達「溝通」與「溝通」,而不是「什麼」。

設定

應用程式必須設定 繫結,使用所需的通訊管道類型專用參數。繫結支援多種網路傳輸功能,包括 TCP、UDP、具備穩定傳輸訊息的 UDP 以及透過 BLE (WoBLE) 傳輸的 Weave。應用程式也可以要求使用特定的安全機制,保護雙方之間的訊息。包括 CASE 和 PASE 工作階段,以及應用程式群組金鑰。設定「繫結」的介面使用宣告式 API 樣式,讓應用程式能夠以簡單的方式說明其對通訊的需求條件。

詳情請參閱 binding::Configuration 的說明文件。

準備

通訊開始之前,「繫結」必須是「準備中」。在準備「繫結」的過程中,您必須建立必要的通訊狀態,以便溝通。這可能包括:解析對等點的網路位址、建立網路連線,以及協商安全金鑰。設定應用程式之後,「繫結」會負責準備通訊所需的所有步驟,並在程序完成時返回應用程式。因此,繫結會隱藏通訊機制,讓應用程式能夠專心處理高階互動。

通訊

完成繫結後,就可以開始使用。在這種情況下,應用程式 (或代表應用程式運作的通訊協定層程式碼) 會要求 binding 來指派 Weave 交換內容。結果交換程序已預先設定通訊內容,可讓應用程式立即啟動與對等互連的 Weave 交換作業。應用程式可以繼續從 約束 要求交換背景資訊,直到繫結關閉,或者某些事件 (例如網路故障) 終止基礎通訊管道。

繫結狀態變更

在使用過程中,繫結會將 API 事件傳送給應用程式,通知繫結狀態發生變化。例如,在準備成功時,應用程式將收到一則通知,告知繫結可以使用了。同樣地,如果基礎通訊管道發生錯誤,就會傳送事件至應用程式,通知繫結不再處於就緒狀態。

API 事件會透過分配到 binding 時提供的事件回呼函式,傳送至應用程式。

繫結生命週期

「繫結」指的是參照多個軟體元件共用的情形,分配 binding 時,會建立繫結繫結的單一參照。應用程式必須負責在日後某個時間發布此參考資料,如此 繫結即可免費用於後續重複使用。

使用繫結完成應用程式時,可能會呼叫繫結上的 Close()。這會讓應用程式參照 繫結的參照,並封鎖所有後續傳送的 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
代表應用程式使用繫結,為通訊協定圖層程式碼設定事件回呼函式。

公開的靜態函式

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

類別

nl::Weave::binding:: 設定

提供可宣告及準備 binding 物件的宣告式介面。

結構

nl::Weave::繫結::InEventParam

binding API 事件輸入參數。

nl::Weave::繫結::OutEventParam

將參數輸出到 binding API 事件。

公開類型

@23

 @23
屬性
kGetPeerDescription_MaxLength

GetPeerDescription() 傳回的字串長度 (包括 NUL 字元)。

事件回呼

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

公開屬性

應用程式狀態

void * AppState

公開函式

新增參考資料

void AddRef(
  void
)

保留繫結物件的參照。

AdjustResponseTimeout

WEAVE_ERROR AdjustResponseTimeout(
  ExchangeContext *apExchangeContext
) const 

重新設定現有的 Exchange 內容,以便調整回應逾時。

詳細資料
參數
[in] apExchangeContext
指向要重新設定的 Exchange 結構定義物件的指標

AllocateRightSizedBuffer

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

開始設定

Configuration BeginConfiguration()

設定 繫結的程序。

應用程式必須先呼叫 StartConfiguration() 來設定 binding,才能設定與對等互連通訊前的準備作業。

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

可預備

bool CanBePrepared(
  void
) const 

關閉

void Close(
  void
)

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

呼叫這個方法時,會使繫結進入關閉狀態。系統會取消繫結的所有進行中的準備動作,並解除繫結保存的所有外部通訊資源。

呼叫 Close() 會減少與繫結相關的參照計數,如果參照計數為零,則捨棄物件。

取得連線

WeaveConnection * GetConnection() const 

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

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

GetDefaultResponseTimeout

uint32_t GetDefaultResponseTimeout() const 

取得在對等節點通訊時使用的預設交換回應逾時時間。

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

GetDefaultWRMPConfig

const WRMPConfig & GetDefaultWRMPConfig(
  void
) const 

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

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

取得加密類型

uint8_t GetEncryptionType(
  void
) const 

擷取要在加密/從對等點加密郵件時要使用的郵件加密類型。

取得事件回呼

EventCallback GetEventCallback() const 

取得繫結發生 API 事件時呼叫的函式。

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

取得廣告交易平台管理員

WeaveExchangeManager * GetExchangeManager() const 

取得金鑰 ID

uint32_t GetKeyId(
  void
) const 

擷取郵件加密金鑰 ID,以便在對對等點進行加密或接收訊息時加以使用。

取得紀錄 ID

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 的酬載大小上限。

取得同類群組說明

void GetPeerDescription(
  char *buf,
  uint32_t bufSize
) const 

建構一個字串,用來描述對等節點及其關聯位址 / 連線資訊。

詳細資料
參數
[in] buf
指向字串的寫入指標。提供的緩衝區不得低於 kGetPeerDescription_MaxLength。如果指定的緩衝區較小,字串就會遭到截斷,以符合適合的大小。在任何情況下,輸出結果都會包含 NUL 終止字元。
[in] bufSize
buf 指向的緩衝區大小。

取得對等點 IP 位址

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

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

對等端 IP 位址資訊的可用性取決於繫結的狀態和設定。只有在使用 IP 型傳輸 (TCP、UDP 或 WRMP 的 UDP) 時,才能使用 IP 位址資訊。在開始準備之前,只有當應用程式已在設定期間明確設定地址資訊時,才可以使用這項資訊。在準備階段期間,當地址準備作業完成時 (例如,DNS 解析完成後),就可以取得地址資訊。「繫結」準備就緒後,在重設「繫結」前,地址資訊仍會提供。

詳細資料
參數
[out] address
接收 IP 位址物件的參照,用來接收對等點的 IP 位址。如果對等點的 IP 位址資訊無法使用,這個值將設為「IPAddress::Any」
[out] port
可接收對等互連通訊埠編號的整數參照。如果對等點的 IP 位址資訊無法使用,這個值即為未定義的值。
[out] interfaceId
一個整數,用於接收可連上對等點的網路介面 ID。如果對等點的 IP 位址資訊無法使用,這個值即為未定義的值。

取得對等節點 ID

uint64_t GetPeerNodeId(
  void
) const 

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

只有在完成繫結物件準備後,才有效。

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

取得通訊協定層呼叫回呼

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

GetState

State GetState(
  void
) const 

擷取繫結目前的狀態。

詳細資料
傳回
繫結狀態。

IsAuthenticMessageFromPeer

bool IsAuthenticMessageFromPeer(
  const WeaveMessageInfo *msgInfo
)

判斷特定外來郵件是否來自設定的對等點,並經過妥善驗證。

這個方法會針對以下訊息,確認下列詳細資料:

  • 郵件來自繫結的對等節點
  • 系統會透過與繫結相同的傳輸類型接收郵件。如果您是透過連結接收郵件,此方法也會確認郵件是透過與繫結相關聯的確切連線來接收。
  • 用於加密郵件的加密金鑰和類型,與繫結中設定的設定一致。對於未設定安全設定的繫結,該方法可確認收到的郵件「未」經過加密。

這種方法旨在用於 WDM 等通訊協定,因為對等節點可以在節點從對等互連點對點的初始交換過程中,以隨機方式啟動本機節點。在這種情況下,該方法可允許本機節點確認相關對等端傳送的來路不明的訊息。(當然,對於沒有使用郵件加密功能設定的繫結,這種安全性機制並不具安全性考量。只會確認寄件者節點 ID 和傳輸類型相符)。

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

詳細資料
參數
[in] msgInfo
傳入訊息的 Weave 訊息資訊。
傳回
如果訊息的對等點是正版內容,則傳回 true。

IsConnectionTransport

bool IsConnectionTransport() const 

準備中

bool IsPreparing(
  void
) const 

詳細資料
傳回
如果正在準備 binding,則值為 True。

就緒

bool IsReady(
  void
) const 

詳細資料
傳回
如果 binding 處於就緒狀態,則值為 True。

是 UDP 傳輸

bool IsUDPTransport() const 

屬於不可靠的 UDP 傳輸

bool IsUnreliableUDPTransport() const 

伊斯蘭運輸

bool IsWRMTransport() const 

新廣告交易平台內容

WEAVE_ERROR NewExchangeContext(
  ExchangeContext *& appExchangeContext
)

分配新的 Exchange 結構定義,與具備繫結目標的對等點通訊。

詳細資料
參數
[out] appExchangeContext
可接收新分配的 Exchange Context 物件的指標參照。如果這個方法失敗,則指標將設為 NULL。
傳回值
WEAVE_NO_ERROR
如果已成功分配廣告交易平台內容,
WEAVE_ERROR_NO_MEMORY
如果沒有可用的記憶體來分配交換內容。
WEAVE_ERROR_INCORRECT_STATE
如果繫結處於就緒狀態,
other
其他有關設定 Exchange 背景資訊的錯誤;這些錯誤會根據繫結的設定進行設定。

版本

void Release(
  void
)

釋出繫結物件的參照。

如果繫結物件沒有其他參照,系統將關閉並釋出繫結。

要求準備

WEAVE_ERROR RequestPrepare()

要求應用程式進行設定並準備繫結

通訊協定層程式碼可在尚未設定或失敗的繫結中使用這個方法,藉此觸發應用程式 (kEvent_PrepareRequested) 來要求將事件設定為應用程式,並準備要使用的繫結。

只有在「NotConfigured」或「Failed」的繫結中才能呼叫此方法。

如果應用程式不支援繫結/準備繫結,則執行 WEAVE_ERROR_NOT_IMPLEMENTED 方法將會失敗。

重設

void Reset(
  void
)

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

呼叫 reset() 時,所有繫結的進行中準備動作都會取消,且繫結的所有外部通訊資源都會釋出。重設() 會將繫結設定在「未設定」狀態,此狀態之後可以重新設定與準備。

重設() 不會改變繫結的參照計數。

SetDefaultResponseTimeout

void SetDefaultResponseTimeout(
  uint32_t msec
)

設定與對等點通訊時要使用的預設交換回應逾時。

詳細資料
參數
[in] timeout
新的回應逾時時間 (以毫秒為單位)。

SetDefaultWRMPConfig

void SetDefaultWRMPConfig(
  const WRMPConfig & wrmpConfig
)

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

詳細資料
參數
[in] aWRMPConfig
WRMPConfig 結構的參照,其中包含新的預設設定。

設定事件回呼

void SetEventCallback(
  EventCallback aEventCallback
)

設定應用程式繫結函式,以在繫結發生 API 事件時呼叫。

詳細資料
參數
[in] aEventCallback
回呼函式的指標。

設定通訊協定層回呼

void SetProtocolLayerCallback(
  EventCallback callback,
  void *state
)

代表應用程式使用繫結,為通訊協定圖層程式碼設定事件回呼函式。

binding 發生 API 事件時,除了應用程式定義的回呼函式以外,也會呼叫此函式。

詳細資料
參數
[in] callback
回呼函式的指標。
[in] state
指向通訊協定層的指標,會在通訊協定層的回呼發生時,提供給通訊協定層程式碼。

公開的靜態函式

預設事件處理常式

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

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

如果應用程式無法辨識或處理任何 API 事件,則必須呼叫這個方法。提供的參數必須與繫結至應用程式事件處理常式函式的參數相同。

詳細資料
參數
[in] apAppState
指向繫結繫結的應用程式定義狀態資訊。
[in] aEvent
事件回呼傳送的事件 ID
[in] aInParam
事件回呼傳送的輸入事件參數參考資料
[in] aOutParam
事件回呼傳送的輸出事件參數參考資料