nl::Weave::Profiles::DataManagement_Current::SubscriptionClient

สรุป

ประเภทสาธารณะ

@130 enum
EventCallback)(void *const aAppState, EventID aEvent, const InEventParam &aInParam, OutEventParam &aOutParam) typedef
void(*
โค้ดเรียกกลับเพื่อส่งกิจกรรมการสมัครใช้บริการไปยังแอปพลิเคชัน
EventID{
  kEvent_OnSubscriptionTerminated = 1,
  kEvent_OnExchangeStart = 2,
  kEvent_OnSubscribeRequestPrepareNeeded = 3,
  kEvent_OnSubscriptionEstablished = 4,
  kEvent_OnNotificationRequest = 5,
  kEvent_OnNotificationProcessed = 6,
  kEvent_OnEventStreamReceived = 7,
  kEvent_OnSubscriptionActivity = 8,
  kEvent_OnUpdateComplete = 9,
  kEvent_OnNoMorePendingUpdates = 10
}
enum
ResubscribePolicyCallback)(void *const aAppState, ResubscribeParam &aInParam, uint32_t &aOutIntervalMsec) typedef
void(*
โทรกลับเพื่อเรียกข้อมูลช่วงเวลาที่ต้องรอก่อนสมัครอีกครั้งครั้งถัดไป

ฟังก์ชันแบบคงที่แบบสาธารณะ

DefaultEventHandler(EventID aEvent, const InEventParam & aInParam, OutEventParam & aOutParam)
void
DefaultResubscribePolicyCallback(void *const aAppState, ResubscribeParam & aInParam, uint32_t & aOutIntervalMsec)
void
การใช้นโยบายเริ่มต้นจะเลือกช่วงเวลาแบบสุ่มที่มีความละเอียดเป็นมิลลิวินาทีในกรอบเวลาที่เพิ่มขึ้นเรื่อยๆ ตามลําดับ Fibonacci จนถึง WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX

ฟังก์ชันสาธารณะ

AbortSubscription(void)
void
ยกเลิกการสมัครใช้บริการ
ClearUpdated(TraitUpdatableDataSink *aDataSink, PropertyPathHandle aPropertyHandle)
DisableResubscribe(void)
void
ปิดใช้กลไกการสมัครใช้บริการอีกครั้ง
DiscardUpdates()
void
บอกให้ SubscriptionClient ให้ล้างชุด TraitPath ที่รอการอัปเดตและล้มเลิกคำขออัปเดตที่กำลังดำเนินการ หากมี
EnableResubscribe(ResubscribePolicyCallback aCallback)
void
เปิดใช้การสมัครรับข้อมูลอีกครั้งอัตโนมัติ
EndSubscription(void)
สิ้นสุดการสมัครใช้บริการ
FlushUpdate()
สัญญาณที่แจ้งว่าแอปพลิเคชันได้เปลี่ยนแปลง TraitUpdatableDataSinks ทั้งหมดแล้ว
FlushUpdate(bool aForce)
Free(void)
void
ทำให้ออบเจ็กต์ SubscriptionClient นี้ใช้งานได้ฟรี
GetBinding(void) const
GetLivenessTimeoutMsec(void) const
uint32_t
GetPeerNodeId(void) const
uint64_t
GetSubscriptionId(uint64_t *const apSubscriptionId)
IndicateActivity(void)
void
InitiateCounterSubscription(const uint32_t aLivenessTimeoutSec)
void
InitiateSubscription(void)
void
กำหนดค่า SubscriptionClient ในฐานะผู้เริ่ม (ไม่ใช่ผู้สมัครใช้บริการที่ตัวนับ) และนำการสมัครใช้บริการกลับมาหากไม่ใช่
IsCanceling() const
bool
IsEstablished()
bool
IsEstablishedIdle()
bool
IsFree()
bool
IsInProgressOrEstablished()
bool
IsInResubscribeHoldoff()
bool
IsRetryEnabled()
bool
IsTerminated()
bool
IsUpdatePendingOrInProgress()
bool
LockUpdateMutex(void)
void
OnCatalogChanged()
void
ควรเรียกเมธอดนี้เมื่อมีการแก้ไขแคตตาล็อก TraitDataSink
ResetResubscribe(void)
void
เริ่มกลไกการสมัครรับข้อมูลอีกครั้ง
SetLivenessTimeoutMsec(uint32_t val)
void
SetUpdated(TraitUpdatableDataSink *aDataSink, PropertyPathHandle aPropertyHandle, bool aIsConditional)
SuspendUpdateRetries()
void
แจ้ง SubscriptionClient ให้หยุดคำขออัปเดตอีกครั้ง
UnlockUpdateMutex(void)
void

โครงสร้าง

nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::LastObservedEvent
nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::ResubscribeParam

สหภาพ

nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::InEventParam
nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::OutEventParam

ประเภทสาธารณะ

@130

 @130

EventCallback

void(* EventCallback)(void *const aAppState, EventID aEvent, const InEventParam &aInParam, OutEventParam &aOutParam)

โค้ดเรียกกลับเพื่อส่งกิจกรรมการสมัครใช้บริการไปยังแอปพลิเคชัน

รายละเอียด
พารามิเตอร์
[in] aAppState
มีการตั้งค่าตัวชี้สถานะแอประหว่างการเริ่มต้น SubscriptionClient
[in] aEvent
ระบุว่ากิจกรรมใดกำลังเกิดขึ้น
[in] aInParam
จัดโครงสร้างพร้อมรายละเอียดเพิ่มเติมเกี่ยวกับกิจกรรม
[out] aOutParam
ข้อมูลที่แอปพลิเคชันส่งคืน

EventID

 EventID
พร็อพเพอร์ตี้
kEvent_OnEventStreamReceived

สร้างเมื่อ SubscriptionEngine นับสตรีมเหตุการณ์ภายในข้อความ NotificationRequest

ณ จุดนี้ แอปพลิเคชันอาจเรียก EndSubscription(), AbortSubscription() หรือ Free()

kEvent_OnExchangeStart

สร้างขึ้นหลังจากเตรียมการผูกข้อมูลและตั้งค่า ExchangeContext แล้ว แต่ก่อนที่จะส่งข้อความ

นี่เป็นโอกาสสุดท้ายสำหรับแอปพลิเคชันในการปรับการตั้งค่า ExchangeContext เพราะ mEC ถูกต้องและสามารถปรับค่าระยะหมดเวลาได้ แอปพลิเคชันต้องไม่แตะช่องอื่นๆ ในไคลเอ็นต์ และต้องไม่ปิด ExchangeContext

kEvent_OnNoMorePendingUpdates

เหตุการณ์ที่ระบุว่าเส้นทางทั้งหมดในชุดการอัปเดตได้รับการประมวลผลโดยเพียร์ และไม่จำเป็นต้องอัปเดตเส้นทางอีก

kEvent_OnNotificationProcessed

สร้างขึ้นเมื่อ SubscriptionEngine ประมวลผลข้อความ NotificationRequest เรียบร้อยแล้ว

ณ จุดนี้ แอปพลิเคชันอาจเรียก EndSubscription(), AbortSubscription() หรือ Free()

kEvent_OnNotificationRequest

สร้างขึ้นจากการแจ้งเตือนของ NotificationRequest

ณ จุดนี้ แอปพลิเคชันอาจเรียก EndSubscription(), AbortSubscription() หรือ Free()

kEvent_OnSubscribeRequestPrepareNeeded

ส่งเมื่อเครื่องมือพร้อมที่จะส่ง SubscriptionRequest

โดยคาดหวังให้แอปพลิเคชันอยู่ในเส้นทางที่ต้องการสมัครใช้บริการ

kEvent_OnSubscriptionActivity

เหตุการณ์ที่ระบุถึงกิจกรรมการสมัครใช้บริการ

ระบบจะสร้างการแจ้งเตือนขึ้นเมื่อใดก็ตามที่ลูกค้าได้รับสัญญาณบอกสถานะเกี่ยวกับกิจกรรมการสมัครรับข้อมูล ซึ่งรวมถึงการสมัครเป็นสมาชิกที่ประสบความสำเร็จ การรับ NotificationRequest หรือการได้รับรายงานสถานะตามข้อความที่ได้จากการสมัครรับข้อความ

kEvent_OnSubscriptionEstablished

สร้างขึ้นเมื่อสมัครใช้บริการสำเร็จ

ณ จุดนี้ แอปพลิเคชันอาจเรียก EndSubscription(), AbortSubscription() หรือ Free()

kEvent_OnSubscriptionTerminated

เป็นการสิ้นสุดการสมัครใช้บริการนี้

พารามิเตอร์ที่ส่งไปยัง nl::Weave::Profiles::DataManagement_Current::SubscriptionClient::EventCallback จะระบุว่าระบบจะพยายามสมัครใช้บริการอีกครั้งโดยอัตโนมัติหรือไม่

ในระหว่างการเรียกตัวแฮนเดิลเหตุการณ์ สถานะของไคลเอ็นต์จะเป็น Terminated หากไม่ได้พยายามดำเนินการอีกครั้ง สถานะของไคลเอ็นต์จะเปลี่ยนเป็น Initialized เมื่อตัวแฮนเดิลเหตุการณ์กลับมา มิฉะนั้น รัฐจะเปลี่ยนเป็น ResubscribeHoldoff และจะพยายามหยุดการสมัครใช้บริการอีกครั้งหลังจากเวลาถูกระงับ

แอปพลิเคชันอาจเรียก AbortSubscription() หรือ Free() ในสถานะนี้

พารามิเตอร์ที่ส่งจะมีรหัสข้อผิดพลาดที่ระบุเหตุผลในการสิ้นสุดการสมัครใช้บริการด้วย

การสมัครอาจถูกยกเลิกด้วยเหตุผลหลายประการ (WRM ACK, จัดสรรไม่สำเร็จ, ExchangeContext, หมดเวลาการตอบสนอง,...) รหัสข้อผิดพลาดที่อาจเกิดขึ้นได้ซึ่งไคลเอ็นต์สร้างขึ้น:

รหัสข้อผิดพลาด ความหมาย
WEAVE_ERROR_INVALID_MESSAGE_TYPE ได้รับข้อความที่ไม่รู้จัก
WEAVE_ERROR_TIMEOUT ไม่ได้รับแอคหรือตรวจสอบความพร้อมใช้งานไม่สำเร็จ
WEAVE_ERROR_INCORRECT_STATE ได้รับข้อความในสถานะที่ไม่คาดคิด
WEAVE_ERROR_STATUS_REPORT_RECEIVED ได้รับรายงานสถานะแล้ว
WEAVE_ERROR_INVALID_ARGUMENT ฟิลด์คำขอสมัครรับข้อมูลไม่ถูกต้อง

kEvent_OnUpdateComplete

กิจกรรมที่แสดงถึงการอัปเดตเสร็จสมบูรณ์

พารามิเตอร์เหตุการณ์จะระบุว่าการอัปเดตเส้นทางลักษณะหนึ่งๆ สำเร็จหรือล้มเหลว

ResubscribePolicyCallback

void(* ResubscribePolicyCallback)(void *const aAppState, ResubscribeParam &aInParam, uint32_t &aOutIntervalMsec)

โทรกลับเพื่อเรียกข้อมูลช่วงเวลาที่ต้องรอก่อนสมัครอีกครั้งครั้งถัดไป

แอปพลิเคชันจะล้มเลิก/ฟรีในฟังก์ชันนี้ได้หากผู้ใช้ตัดสินใจที่จะยกเลิกการสมัครใช้บริการใหม่

รายละเอียด
พารามิเตอร์
[in] aAppState
มีการตั้งค่าตัวชี้สถานะแอประหว่างการเริ่มต้น SubscriptionClient
[in] aInParam
จัดโครงสร้างโดยใส่รายละเอียดเพิ่มเติมเกี่ยวกับการลองอีกครั้ง
[out] aOutIntervalMsec
เวลาที่ต้องรอเป็นมิลลิวินาทีก่อนที่จะลองอีกครั้ง

ฟังก์ชันแบบคงที่แบบสาธารณะ

DefaultEventHandler

void DefaultEventHandler(
  EventID aEvent,
  const InEventParam & aInParam,
  OutEventParam & aOutParam
)

DefaultResubscribePolicyCallback

void DefaultResubscribePolicyCallback(
  void *const aAppState,
  ResubscribeParam & aInParam,
  uint32_t & aOutIntervalMsec
)

การใช้นโยบายเริ่มต้นจะเลือกช่วงเวลาแบบสุ่มที่มีความละเอียดเป็นมิลลิวินาทีในกรอบเวลาที่เพิ่มขึ้นเรื่อยๆ ตามลําดับ Fibonacci จนถึง WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX

ค่าเฉลี่ยของเวลารอโดยเฉลี่ยที่ผ่าน WDM_RESUBSCRIBE_MAX_FIBONACCI_STEP_INDEX คือประมาณ 1 ชั่วโมง เมื่อจำนวนการทำซ้ำรีเซ็ตเป็น 0 ลำดับจะเริ่มต้นจากจุดเริ่มต้นอีกครั้ง

ฟังก์ชันสาธารณะ

AbortSubscription

void AbortSubscription(
  void
)

ยกเลิกการสมัครใช้บริการ

ล้มเลิกการสมัครใช้บริการของลูกค้า

หยุดยอมรับการเข้าชมทั้งหมดที่เกี่ยวข้องกับการสมัครใช้บริการทันที และปล่อยทรัพยากรการสื่อสารที่สำคัญทั้งหมด ส่วนออบเจ็กต์ SubscriptionClient เองยังคงใช้งานได้และอาจใช้ได้อีกครั้ง

ยุติการสมัครใช้บริการของลูกค้าโดยไม่แจ้งผู้เผยแพร่การสมัครใช้บริการ และไม่ส่งเหตุการณ์ OnSubscriptionTerminated ไปยังเครื่องจัดการเหตุการณ์ของแอปพลิเคชัน หากมีการสมัครใช้บริการร่วมกัน การสมัครใช้บริการที่โต้แย้งจะสิ้นสุดลงด้วย

เมื่อเรียก AbortSubscription() ออบเจ็กต์ SubscriptionClient จะเข้าสู่สถานะ Terminated เมื่อกระบวนการสิ้นสุดเสร็จสมบูรณ์แล้ว ออบเจ็กต์จะเข้าสู่สถานะ Initialized การเปลี่ยนทั้ง 2 แบบจะเกิดขึ้นพร้อมกันภายในการเรียกใช้ AbortSubscription()

หลังจาก AbortSubscription() กลับมาแล้ว ระบบอาจใช้ออบเจ็กต์ SubscriptionClient เพื่อเริ่มการสมัครใช้บริการอื่น หรือระบบอาจยกเลิกได้โดยเรียกใช้เมธอด Free()

ClearUpdated

WEAVE_ERROR ClearUpdated(
  TraitUpdatableDataSink *aDataSink,
  PropertyPathHandle aPropertyHandle
)

DisableResubscribe

void DisableResubscribe(
  void
)

ปิดใช้กลไกการสมัครใช้บริการอีกครั้ง

ระบบจะล้มเลิกการสมัครใช้บริการใหม่ที่รอดำเนินการอยู่

DiscardUpdates

void DiscardUpdates()

บอกให้ SubscriptionClient ให้ล้างชุด TraitPath ที่รอการอัปเดตและล้มเลิกคำขออัปเดตที่กำลังดำเนินการ หากมี

เมธอดนี้สามารถเรียกใช้จากโค้ดเรียกกลับใดก็ได้

EnableResubscribe

void EnableResubscribe(
  ResubscribePolicyCallback aCallback
)

เปิดใช้การสมัครรับข้อมูลอีกครั้งอัตโนมัติ

แนบโค้ดเรียกกลับเพื่อระบุเวลาลองอีกครั้งที่ไม่สำเร็จในครั้งถัดไป

รายละเอียด
พารามิเตอร์
[in] aCallback
โค้ดเรียกกลับ (ไม่บังคับ) ที่จะดึงข้อมูลระยะเวลาที่ต้องรอก่อนลองอีกครั้งหลังจากล้มเหลว หาก NULL ใช้นโยบายเริ่มต้น

EndSubscription

WEAVE_ERROR EndSubscription(
  void
)

สิ้นสุดการสมัครใช้บริการ

สิ้นสุดการสมัครใช้บริการของลูกค้าอย่างสง่างาม

เมื่อเปิดใช้ตัวเลือกเวลาคอมไพล์ WDM_ENABLE_SUBSCRIPTION_CANCEL แล้ว ให้ยุติการสมัครใช้บริการอย่างมีชั้นเชิงโดยส่งคำขอ cancelRequest ไปยังเพียร์ ทรัพยากรที่เชื่อมโยงกับการสมัครใช้บริการจะมีอิสระเมื่อตอบสนองจากเพียร์หรือเมื่อหมดเวลา เมื่อปิดใช้ตัวเลือกนี้อยู่ การเรียกใช้จะมีค่าเท่ากับ AbortSubscription()

สิ้นสุดการสมัครใช้บริการของลูกค้าอย่างมีชั้นเชิง หากเปิดใช้การสนับสนุนการยกเลิกการสมัครรับข้อมูล ระบบจะส่งข้อความ SubscriptionCancelRequest ไปยังผู้เผยแพร่ที่สมัครใช้บริการ และระบบจะรอการตอบกลับก่อนที่จะสิ้นสุดการสมัครใช้บริการ มิฉะนั้นระบบจะยุติการสมัครใช้บริการทันทีในลักษณะเดียวกันกับ AbortSubscription() ถ้ามีการสมัครสมาชิกแบบร่วมกันอยู่ การสมัครใช้บริการที่ยื่นเรื่องโต้แย้งจะสิ้นสุดลงด้วย

ขณะรอการตอบกลับ SubscriptionCancelRequest นั้น SubscriptionClient จะเข้าสู่สถานะ Canceling

เมื่อกระบวนการยุติเริ่มต้นขึ้น ออบเจ็กต์ SubscriptionClient จะเข้าสู่สถานะ Terminated และส่งเหตุการณ์ OnSubscriptionTerminated ไปยังเครื่องจัดการเหตุการณ์ของแอปพลิเคชัน โปรดทราบว่าหากไม่ได้เปิดใช้การยกเลิกการสนับสนุน อาจมีการเรียกใช้เครื่องจัดการเหตุการณ์แบบพร้อมกันภายในการเรียก EndSubscription()

หลังจากที่เครื่องจัดการเหตุการณ์ของแอปพลิเคชันแสดงผลแล้ว ออบเจ็กต์ SubscriptionClient จะเข้าสู่สถานะ Initialized ณ จุดนี้อาจมีการใช้ออบเจ็กต์ SubscriptionClient เพื่อเริ่มการสมัครใช้บริการอื่น หรือออบเจ็กต์อาจมีการใช้งานโดยการเรียกใช้เมธอด Free()

FlushUpdate

WEAVE_ERROR FlushUpdate()

สัญญาณที่แจ้งว่าแอปพลิเคชันได้เปลี่ยนแปลง TraitUpdatableDataSinks ทั้งหมดแล้ว

เว้นแต่การแลกเปลี่ยนการอัปเดตครั้งก่อนดำเนินอยู่ ไคลเอ็นต์จะนำข้อมูลทั้งหมดที่ทำเครื่องหมายว่าอัปเดตแล้วส่งไปยังผู้ตอบในคำขออัปเดตครั้งเดียว เมธอดนี้สามารถเรียกใช้จากชุดข้อความใดก็ได้

รายละเอียด
พารามิเตอร์
[in] aForce
หาก "จริง" จะทำให้มีการส่งการอัปเดตทันที แม้ว่าจะมีการกำหนดเวลาสำหรับลองอีกครั้งในอนาคตก็ตาม ระบบจะถือว่าพารามิเตอร์นี้เป็นเท็จโดยค่าเริ่มต้น
การส่งคืน
WEAVE_NO_ERROR ในกรณีสำเร็จ รหัส WEAVE_ERROR อื่นๆ ในกรณีที่ล้มเหลว

FlushUpdate

WEAVE_ERROR FlushUpdate(
  bool aForce
)

ฟรี

void Free(
  void
)

ทำให้ออบเจ็กต์ SubscriptionClient นี้ใช้งานได้ฟรี

ปล่อยออบเจ็กต์ SubscriptionClient ว่าง

เรียกใช้ AbortSubscription() หากจำเป็น และเผยแพร่การนับการอ้างอิงในออบเจ็กต์ SubscriptionClient นี้ ภายใต้การใช้งานที่ถูกต้อง ควรทำให้ระบบส่งออบเจ็กต์กลับไปยังพูลออบเจ็กต์ได้

ปล่อยออบเจ็กต์ SubscriptionClient ขึ้น หากการสมัครใช้บริการมีการใช้งานอยู่หรืออยู่ระหว่างดำเนินการ การสมัครใช้บริการจะสิ้นสุดลงทันทีในลักษณะเดียวกับการเรียกใช้ AbortSubscription() หากคำขออัปเดตใดอยู่ระหว่างดำเนินการ คำขอเหล่านั้นก็จะถูกล้มเลิกในทำนองเดียวกัน

แอปพลิเคชันจะมีหน้าที่เรียก Free() เพียงครั้งเดียวตลอดอายุของออบเจ็กต์ SubscriptionClient หลังจากเรียก Free() แล้ว ไม่ควรมีการสร้างการอ้างอิงไปยังออบเจ็กต์อีก

GetBinding

Binding * GetBinding(
  void
) const 

GetLivenessTimeoutMsec

uint32_t GetLivenessTimeoutMsec(
  void
) const 

GetPeerNodeId

uint64_t GetPeerNodeId(
  void
) const 

GetSubscriptionId

WEAVE_ERROR GetSubscriptionId(
  uint64_t *const apSubscriptionId
)

IndicateActivity

void IndicateActivity(
  void
)

InitiateCounterSubscription

void InitiateCounterSubscription(
  const uint32_t aLivenessTimeoutSec
)

InitiateSubscription

void InitiateSubscription(
  void
)

กำหนดค่า SubscriptionClient ในฐานะผู้เริ่ม (ไม่ใช่ผู้สมัครใช้บริการที่ตัวนับ) และนำการสมัครใช้บริการกลับมาหากไม่ใช่

IsCanceling

bool IsCanceling() const 

IsEstablished

bool IsEstablished()

IsEstablishedIdle

bool IsEstablishedIdle()

IsFree

bool IsFree()

IsInProgressOrEstablished

bool IsInProgressOrEstablished()

IsInResubscribeHoldoff

bool IsInResubscribeHoldoff()

IsRetryEnabled

bool IsRetryEnabled()

IsTerminated

bool IsTerminated()

IsUpdatePendingOrInProgress

bool IsUpdatePendingOrInProgress()

LockUpdateMutex

void LockUpdateMutex(
  void
)

OnCatalogChanged

void OnCatalogChanged()

ควรเรียกเมธอดนี้เมื่อมีการแก้ไขแคตตาล็อก TraitDataSink

ResetResubscribe

void ResetResubscribe(
  void
)

เริ่มกลไกการสมัครรับข้อมูลอีกครั้ง

การดำเนินการนี้จะเริ่มต้นการลองอีกครั้งทันที

SetLivenessTimeoutMsec

void SetLivenessTimeoutMsec(
  uint32_t val
)

SetUpdated

WEAVE_ERROR SetUpdated(
  TraitUpdatableDataSink *aDataSink,
  PropertyPathHandle aPropertyHandle,
  bool aIsConditional
)

SuspendUpdateRetries

void SuspendUpdateRetries()

แจ้ง SubscriptionClient ให้หยุดคำขออัปเดตอีกครั้ง

อนุญาตให้แอปพลิเคชันระงับการอัปเดตเป็นระยะเวลาหนึ่งโดยไม่ทิ้งข้อมูลเมตาทั้งหมด การอัปเดตและการส่งซ้ำจะกลับมาทำงานอีกครั้งเมื่อมีการเรียกใช้ FlushUpdate เมื่อมีการขอให้ระงับการอัปเดตขณะดำเนินการอัปเดต ระบบจะไม่ยกเลิกการอัปเดต แต่ในกรณีที่ไม่สำเร็จ ระบบจะไม่พยายามย้ายอีกจนกว่าจะมีการเรียกใช้ FlushUpdate อีกครั้ง

UnlockUpdateMutex

void UnlockUpdateMutex(
  void
)