# 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`事件循環而不斷開連接。你將需要重新進入循環以保持連接。
* * * * *