=====
连接状态事件
=====

通过API获取设备连接状态事件。

参考 `Get Device Connection Status <https://github.com/CassiaNetworks/CassiaSDKGuide/wiki/RESTful-API#get-device-connection-status>`_。

.. note:: 

   - 注意如果设备已经处于连接状态时，连接API响应成功，连接事件并不会上报

示例
=====

.. literalinclude:: ../../../../example/cassiablue/state.py
   :language: python
   :linenos:

API
=====

.. py:function::  cassiablue.start_recv_connection_state() -> tuple[ok: bool, result: str]
   :async:

   开启获取设备连接状态事件，用于实时获取设备连接状态变化，目前支持同时开启1个

   :returns: 
      - ok: 是否执行成功
      - result: 执行结果，消息数据请参考 ``BLEConnectionResult``

.. py:function:: cassiablue.connection_result() -> BLEConnectionResult
   :async:

   获取连接状态事件

   :returns: ``class BLEConnectionResult``

.. py:class:: BLEConnectionResult

   异步可迭代对象，用于流式接收 BLE 连接状态事件。

   .. py:method:: __aiter__() -> BLEConnectionResult
      :async:

      返回自身，使实例可直接用于 ``async for`` 循环。

   .. py:method:: __anext__() -> dict
      :async:

      从全局 ``state_sse_client.queue`` 中异步获取下一条消息并返回。

      当队列为空时会一直等待，直到有新数据到达。


      .. csv-table:: 数据字段说明
         :header: 字段,类型,说明,示例

         connectionState,str,事件类型,``connected`` ``disconnected``
         rssi,int,RSSI,-65
         handle,str,设备MAC地址,20:00:00:00:00:01
         reason,str,断连原因（disconnected有效）,host disconnect
         packetLossRate,int,丢包率（disconnected有效）,3

      .. note:: 

         - reason参考 `Error Messages <https://github.com/CassiaNetworks/CassiaSDKGuide/wiki/Error-Messages>`_