# Mosquitto 客户端
*## class Mosquitto\Client*
*### Mosquitto 客户端类*
~~~
constant LOG_DEBUG
~~~
定义调试级别的日志消息
~~~
constant LOG_INFO
~~~
定义信息级别的日志消息
~~~
constant LOG_NOTICE
~~~
定义通知级别的日志消息
~~~
constant LOG_WARNING
~~~
定义警告级别的日志消息
~~~
constant LOG_ERR
~~~
定义错误级别的日志消息
~~~
constant SSL_VERIFY_NONE
~~~
不使用` setTlsInsecure`。不会验证服务器的身份，不能保障连接的安全。
~~~
constant SSL_VERIFY_PEER
~~~
使用` setTlsInsecure`。验证服务器的身份。
* * * * *
~~~
__construct([$id = null, $cleanSession = true])
~~~
构造函数。
Parameters:
* `$id(string)` -客户端ID,如果省略或者为`null`,会随机生成一个。
* `$cleanSession (boolean)`- 如果设为` false` ，当 client 断开连接后，broker 会保留该 client 的订阅和消息，直到再次连接成功；如果设为 `true`（默认） ，client 断开连接后，broker 会将所有的订阅和消息删除。
* * * * *
~~~
setCredentials($username, $password)
~~~
设置连接到服务器的用户名和密码。必须在`connect`之前调用.
Parameters:
* $username (string) -连接到代理的用户名。
* $password (string) -连接到代理的密码。
* * * * *
~~~
setTlsCertificates($caPath[, $certFile, $keyFile, $password])
~~~
配置基于ssl / tls客户端的证书必须在之前`connect`被调用,不能与`settlspsk`一起使用。
Parameters:
* `$caPath (string)` – 指向pem编码的可信任CA证书文件的路径，或包含证书文件的目录。
* `$certFile (string) `– 可选。此客户端的pem编码证书文件的路径。
* `$keyFile (string) `–指向包含此客户端的pem编码私钥的文件的路径。如果设置了`certfile`，则为必选。
* `$password (string)` –密钥文件的密码。如果为空，则将在命令行上询问密码。
* * * * *
~~~
setTlsInsecure($value)
~~~
配置服务器证书中服务器主机名的验证。若`$value`为`true`，不能保证你所连接的主机不是在冒充你的服务器。请勿在实际生产中使用此功能。必须在`connect`之前调用。
Parameters:
* `$value (boolean) `–如果设置为`false`（默认），被执行主机名证书检查。如果设置为true，不执行主机名检查，不安全的连接。
* * * * *
~~~
setTlsOptions($certReqs, $tlsVersion, $ciphers)
~~~
设置高级的ssl / tls选项。必须在`connect`之前调用。
Parameters:
* `$certReqs (int) `– 是否验证服务器。如果是`Mosquitto\\Client::SSL_VERIFY_NONE`，禁用证书验证。如果是`Mosquitto\Client::SSL_VERIFY_PEER`（默认值），验证服务器证书。
* `$tlsVersion (string)` – 要使用的tls版本。如果为`null`，使用默认值。默认值取决于库编译的openssl的版本。openssl> = 1.0.1的可用选项是`tlsv1.2`，`tlsv1.1`和`tlsv1`。
* $cipers (string) – 描述可用密码的字符串。请参阅`openssl ciphers`工具以获取更多信息。如果为`null`，则将使用默认设置。
* * * * *
~~~
setWill($topic, $payload[, $qos = 0, $retain = false])
~~~
设置“遗嘱消息”，当 broker 检测到网络故障、客户端异常等问题，需要关闭某个客户端的连接时，向该客户端发布一条消息。必须在`connect`之前调用.
Parameters:
* $topic (string) – 发表遗嘱消息的主题。
* $payload (string) – 要发送的数据。
* $qos (int) –可选。服务质量。默认值为`0`.整数`0`,`1`或`2`。
* $retain (boolean) – 可选。默认为`false`。设置为`true`，则该消息将被保留。
* * * * *
~~~
clearWill()
~~~
删除之前设置遗嘱消息。没有参数。
* * * * *
~~~
setReconnectDelay($reconnectDelay, $exponentialDelay, $exponentialBackoff)
~~~
设置客户端在`Client::loopForever`中意外断开连接时的行为。如果不使用此方法的默认行为是反复尝试以1秒的延迟重新连接，直到连接成功。
Parameters:
* $reconnectDelay (int) – 连续重新连接尝试之间设置延迟。
* $exponentialDelay (int) – 当启用指数回退时，在连续的重新连接尝试之间设置最大延迟
* $exponentialBackoff (bool) – 通过真正的启用指数回退
* * * * *
~~~
connect($host[, $port = 1883, $keepalive = 60, $interface = null])
~~~
Parameters:
* $host (string) – 连接的主机名
* $port (int) – 可选。 要连接的端口号。默认为1883。
* $keepalive (int) – 可选。在没有收到消息的情况下，服务器应该ping客户端的部分数量。
* $interface (string) – 可选。要为此连接绑定的本地接口的地址或主机名。
* * * * *
~~~
disconnect()
~~~
从服务器断开。没有参数。
* * * * *
~~~
onConnect($callback)
~~~
设置连接回调。当代理发送`connack`消息来响应连接时被触发。
Parameters:
* `$callback (callable) `– 回调函数
回调应该采取以下形式的参数：
Parameters:
* `$rc (int) `– 来自服务器的响应代码。
* `$message (string) `– 响应代码的字符串描述。
回应码如下：
| Code | Meaning |
| --- | --- |
|0 | 成功 |
| 1 | 连接被拒绝（不可接受的协议版本） |
| 2 | 连接拒绝（标识符被拒绝） |
| 3 | 连接被拒绝（代理不可用） |
| 4-255 | 保留以供将来使用 |
* * * * *
~~~
onDisconnect($callback)
~~~
设置断开连接回调。当服务器收到断开连接命令并断开客户端连接时，会调用此命令。
Parameters:
* $callback (callable) – 回调函数
回调应该采取以下形式的参数：
Parameters:
* $rc (int) – 断开的原因。0表示客户端请求断开。其他任何值表示意外断开连接。
* * * * *
~~~
onLog($callback)
~~~
设置日志记录回调。
Parameters:
* $callback (callable) – 回调函数
回调应该采取以下形式的参数：
Parameters:
* $level (int) – 日志消息级别
* $str (string) – 消息字符串。
该级别可以是以下之一：
* `Client::LOG_DEBUG`
* `Client::LOG_INFO`
* `Client::LOG_NOTICE`
* `Client::LOG_WARNING`
* `Client::LOG_ERR`
* * * * *
~~~
onSubscribe($callback)
~~~
设置订阅回调。服务器响应订阅请求时被调用。
Parameters:
* $callback (callable) – 回调函数
回调应该采取以下形式的参数：
Parameters:
* $mid (int) – 订阅消息的消息ID。
* $qosCount (int) – 授予订阅的数量。
此功能需要返回每个订阅的授权qos，但目前不能。
* * * * *
~~~
onUnsubscribe($callback)
~~~
设置取消订阅回调。服务器响应取消订阅请求时被调用。
Parameters:
* $callback (callable) – 回调函数
回调应该采取以下形式的参数：
Parameters:
* $mid (int) – 取消订阅消息的消息ID
* * * * *
~~~
onMessage($callback)
~~~
设置消息回调。收到从服务器返回的消息时调用。
Parameters:
* $callback (callable) – 回调函数
回调应该采取以下形式的参数：
Parameters:
:param Message $message: A Message object containing the message data
* * * * *
~~~
onPublish($callback)
~~~
设置发布回调。当客户端自己发布消息时调用。
Warning: 这可能会在`publish`之前调用返回消息ID，所以，你需要创建一个队列来处理中间列表。
Parameters:
* $callback (callable) – 回调函数
回调应该采取以下形式的参数：
Parameters:
* $mid (int) –`publish` 返回的消息ID
* * * * *
~~~
setMaxInFlightMessages($maxInFlightMessages)
~~~
设置一次可以“在飞行中”的qos 1和2消息的数量。飞行中的消息是其交付流程的一部分。尝试发送进一步的消息`publish`将导致消息排队，直到飞行中的消息数量减少。
设置为0没有最大值。
Parameters:
* $maxInFlightMessages (int) –最大值
* * * * *
~~~
setMessageRetry($messageRetryPeriod)
~~~
设置重发消息之前要等待的秒数。这适用于发布qos> 0的消息。可能随时被调用。
Parameters:
* $messageRetryPeriod (int) –重发间隔
* * * * *
~~~
publish($topic, $payload[, $qos = 0, $retain = false])
~~~
发布主题消息。
Parameters:
* $topic (string) – 要发表的主题
* $payload (string) – 消息体
* $qos (int) – 服务质量，值`0,``1`或`2`
* $retain (boolean) – 是否保留此消息，默认为`false`
Returns: 服务器返回该消息ID（警告：消息ID并不是唯一的）。
Return type: int
* * * * *
~~~
subscribe($topic, $qos)
~~~
订阅一个主题。
Parameters:
* $topic (string) – 要订阅的主题。
* $qos (int) – 服务质量
Returns:订阅消息的消息ID，所以这可以在`onsubscribe`回调中匹配。
Return type:int
* * * * *
~~~
unsubscribe()
~~~
取消订阅。
Parameters:
* $topic (string) – 主题。
* $qos (int) – 服务质量
Returns:订阅消息的消息ID，所以这可以在`onsubscribe`回调中匹配。
Return type: int
* * * * *
~~~
loop([$timeout = 1000])
~~~
客户端主网络循环，必须调用该函数来保持 client 和 broker 之间的通讯。收到或者发送消息时，它会调用相应的回调函数处理。当 QoS>0 时，它还会尝试重发消息。
Parameters:
* $timeout (int) – 可选。 等待网络活动的毫秒数。传递0即时超时。默认为1000。
* * * * *
~~~
loopForever([$timeout = 1000])
~~~
在无限的阻塞循环调用`loop()`，将根据需要调用回调。这将处理重新连接，如果连接丢失。调用`disconnect`在回调断开，并从循环中返回。或者，调用`exitloop`退出循环而不断开。您将需要再次重新进入循环以保持连接。
Parameters:
* $timeout (int) – 可选。 等待网络活动的毫秒数。传递0即时超时。默认为1000。
* * * * *
~~~
exitLoop()
~~~
退出`loopforever`事件循环而不断开连接。你将需要重新进入循环以保持连接。
* * * * *
