From 0dcbe7f3c113fb49ec13ebe485348909a5c2051d Mon Sep 17 00:00:00 2001 From: Matt Brittan Date: Fri, 29 Oct 2021 18:45:26 +1300 Subject: [PATCH] Update documentation/comments to clarify when the `connect()` function returns. As per discussion in issue #521 --- README.rst | 16 ++++++++++++---- src/paho/mqtt/client.py | 3 ++- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index e060cef2..357815c2 100644 --- a/README.rst +++ b/README.rst @@ -445,8 +445,10 @@ connect() connect(host, port=1883, keepalive=60, bind_address="") -The ``connect()`` function connects the client to a broker. This is a blocking -function. It takes the following arguments: +The ``connect()`` function connects the client to a broker. ``connect()`` blocks until +the underlying connection is established and a CONNECT packet transmitted. +Note that the connection status will not be updated until a CONNACK is received and +processed (this requires a ``loop*()`` function). host the hostname or IP address of the remote broker @@ -465,11 +467,17 @@ bind_address the IP address of a local network interface to bind this client to, assuming multiple interfaces exist +Returns MQTT_ERR_SUCCESS if the underlying connection was successfully established +and an MQTT CONNECT packet sent. + Callback ........ -When the client receives a CONNACK message from the broker in response to the -connect it generates an ``on_connect()`` callback. +When the client ``loop*()`` function receives a CONNACK packet from the broker in +response to the CONNECT packet it generates an ``on_connect()`` callback. + +In most cases the connection should not be used prior to the ``on_connect()`` call +because the broker may reject the CONNECT packet. Connect Example ............... diff --git a/src/paho/mqtt/client.py b/src/paho/mqtt/client.py index 1c0236e4..ec1580d4 100644 --- a/src/paho/mqtt/client.py +++ b/src/paho/mqtt/client.py @@ -884,7 +884,8 @@ def disable_logger(self): def connect(self, host, port=1883, keepalive=60, bind_address="", bind_port=0, clean_start=MQTT_CLEAN_START_FIRST_ONLY, properties=None): - """Connect to a remote broker. + """Connect to a remote broker. This is a blocking call that establishes + the underlying connection and transmits a CONNECT packet. host is the hostname or IP address of the remote broker. port is the network port of the server host to connect to. Defaults to