=====
API
=====

.. py:currentmodule:: cassiamqtt

.. py:class:: CassiaMQTTClient

   与MQTT Broker建立连接，发布与订阅消息，目前最多只支持2个实例。

   .. py:method:: __init__(self, uri, username:str|None=None, password:str|None=None, client_id:str|None=None) -> CassiaMQTTClient

      返回自身，初始化参数

      :parameters:
         - uri: MQTT Broker URI
         - username: 用户名
         - password: 密码
         - client_id: Client ID

   .. py:method:: __aenter__(self)
      :async:

      建立连接，分配资源

   .. py:method:: __aexit__(self)
      :async:

      断开连接，释放资源

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

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

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

      返回订阅消息

      当队列为空时会一直等待，直到有新数据到达，连接断开时退出迭代。


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

         topic,str,Topic,/dev/down/CC:1B:E0:E4:C8:94/api
         qos,int,QoS,0
         payload,str,消息内容,{"id":"1758...
   
   .. py:method:: publish(self, topic:str, payload:str, qos:int=0, retain:bool=False) -> tuple[ok: bool, result: str]
      :async:

      向指定Topic发布消息

      :parameters:
         - topic: Topic
         - payload: 消息内容
         - qos: QoS
         - retain: 是否保留消息

      :returns: 
         - ok: 是否执行成功
         - result: 执行结果
   
   .. py:method:: subscribe(self, topic:str, qos:int=0) -> tuple[ok: bool, result: str]
      :async:

      订阅指定Topic消息

      :parameters:
         - topic: Topic
         - qos: QoS

      :returns: 
         - ok: 是否执行成功
         - result: 执行结果

   .. py:method:: unsubscribe(self, topic:str) -> tuple[ok: bool, result: str]
      :async:

      取消订阅指定Topic消息

      :parameters:
         - topic: Topic

      :returns: 
         - ok: 是否执行成功
         - result: 执行结果