myqtt.Conn — PyMyQttConn class: MQTT connection creation and management

API documentation for myqtt.Conn, an object that represents a MQTT connection.

To create a connection, you need a context where to create it. See myqtt.Ctx documenation to know about it: myqtt.Ctx

A connection is created as follows:

conn = myqtt.Conn (ctx, "localhost", "1883")
if not conn.is_ok ():
    print ("ERROR: connection failed, error was: " + conn.error_msg)
    return

Note that after creating a connection, you must check if it is ok using myqtt.Conn.is_ok() method.

Once a connection is created, you can publish (conn.pub) and subscribe (conn.pub) to topics.

Module API

class myqtt.Conn(ctx, host, port[, serverName])
Parameters:
  • ctx (myqtt.Ctx) – MyQtt context where the connection will be created.
  • host (String) – Host to connect to.
  • port (String) – Port to connect to.
  • client_identifier (String) – Client identifier
  • clean_session (Boolean) – Clean session
  • keep_alive (Integer) – Keep alive configuration
  • conn_opts (String) – Optional connection options to be used by the connection
is_ok()

Allows to check if the current instance is properly connected and available for operations. This method is used to check connection status after a failure.

Return type:True if the connection is ready, otherwise False is returned.
sub(topic[, qos, retain, wait_publish])

Allows to subscribe to a particular topic on the provided connection

Parameters:
  • topic (String) – The topic to subscribe to.
  • qos (String) – The QoS requested for this subscription
  • retain (Boolean) – Enable/disable retain flag for this subscription
  • wait_sub (Number) – Allows to configure the amount of seconds to wait for the operation to complete
Return type:

(status, sub_result) Status returns True or False if subscription finished without error and sub_result is the qos value granted by the server

pub(topic, msg, msg_size[, qos, retain, wait_publish])

Allows to publish the provided message to a particular topic on the provided connection

Parameters:
  • topic (String) – The topic to subscribe to.
  • msg (String) – The message that will be published
  • msg_size (Number) – Size of the message to be published
  • qos (String) – The QoS requested for this subscription
  • retain (Boolean) – Enable/disable retain flag for this subscription
  • wait_sub (Number) – Allows to configure the amount of seconds to wait for the operation to complete
Return type:

True or False if publish operation finished without error

ping([wait_pingresp])

Allows to ping remote server and optionally configure how long to wait for the reply

Parameters:wait_pingresp (Number) – The topic to subscribe to.
Return type:True or False if ping operation finished without error
get_next([timeout])

Allows to block the caller until the next message is returned.

Parameters:timeout (Number) – How long to wait for a reply in seconds. By default 10 seconds is internal configured if nothing is provided. 0 to just get pending message (if any) without waiting.
Return type:Returns next message receieved myqtt.Msg or None if timeout is reached and no message was received.
set_on_msg(on_msg[, on_msg_data])

Allows to configure an async notification handler that will be called every time a message is received.

Parameters:
  • on_msg (on-msg-handler.) – The handler to be executed when a message is received on the connection configured
  • on_msg_data (Object) – The user defined data to be passed to the on_msg handler along with handler corresponding parameters.
set_on_reconnect(on_reconnect[, on_reconnect_data])

Allows to configure an async notification handler that will be called every time a reconnect operation is detected on the provided connection

Parameters:
  • on_reconnect (on-reconnect-handler.) – The handler to be executed when a reconnect is detected on the connection configured
  • on_reconnect_data (Object) – The user defined data to be passed to the on_reconnect handler along with handler corresponding parameters.
set_on_close(on_close[, on_close_data])

Allows to configure a handler which will be called in the case the connection is closed. This is useful to detect broken pipe.

Parameters:
  • on_close (On connection close handler.) – The handler to be executed when the connection close is detected on the instance provided.
  • on_close_data (Object) – The user defined data to be passed to the on_close handler along with handler corresponding parameters.
Returns:

Returns a new reference to a myqtt.Handle that can be used to remove the on close handler configured using remove_on_close()

remove_on_close(handle_ref)

Allows to remove an on close handler configured using set_on_close(). The close handler to remove is identified by the handle_ref parameter which is the value returned by the set_on_close() handler.

Parameters:handle_ref – Reference to the on close handler to remove (value returned by set_on_close()).
Returns:True in the case the handler was found and removed, otherwise False is returned.
set_data(key, object)

Allows to store arbitrary references associated to the connection. See also get_data.

Parameters:
  • key (String) – The key index to which the data gets associated.
  • object (Object) – The object to store associated on the connection index by the given key.
get_data(key)

Allows to retreive a previously stored object using set_data

Parameters:key (String) – The index for the object looked up
Return type:Returns the object stored or None if fails.
block([block=True])

Allows to block all incoming content on the provided connection by skiping connection available data state. This method binds myqtt_connection_block C API.

Parameters:block (Boolean (True if not configured)) – Optional boolean value that configure if the connection must be blocked (True) or unblocked (False). If not configured the connection is blocked (True).
is_blocked()
Return type:Returns if the connection is blocked (due to block()) or not.
close()

Allows to close the connection using full MQTT close negotation procotol.

shutdown()

Allows to close the connection by shutting down the transport layer supporting it. This causes the connection to be closed without taking place MQTT close indication.

incref()

Allows to increment python reference count. This is used in cases where the connection reference is automatically collected by python GC but the MyQttConnection reference that it was representing is still working (and may receive notifications, like frame received). Note that a call to this method, requires a call to decref().

decref()

Allows to decrement python reference count. See incref() for more information.

skip_conn_close([skip])

Allows to configure this connection reference to not call to shutdown its associated reference when the python connection is collected. This method is really useful when it is required to keep working a connection that was created inside a function but that has finished.

By default, any myqtt.Conn object created will be finished when its environment finishes. This means that when the function that created the connection finished, then the connection will be finished automatically.

In many situations this is a desirable behaviour because your python application finishes automatically all the stuff opened. However, when the connection is created inside a handler or some method that implements connection startup but do not waits for the reply (asynchronous replies), then the connection must be still running until reply arrives. For these scenarios you have to use skip_conn_close().

gc([disable_gc = True])

Allows to disable automatic memory collection for python references finished. By default, PyMyQtt closes connections, releases messages and finishes contexts when they are no longer used (as notified by Python engine via _dealloc internal C funciton).

In general this is the recommended approach and in most of the cases you’ll notice any problem.

However, in some cases where it might be needed to disable this deallocation (causing an automatic connection close, context close, etc) when the scope where that variable is finished, then use this function.

Note using this function is very rare and highly not recommended.

NOTE: using this code is really only recommended in very few cases where myqtt usage is being done from a process that starts and finishes on every requests, thus, resource deallocation is not an issue. However, it is highly not recommended.

id

(Read only attribute) (Integer) returns the connection unique identifier.

ctx

(Read only attribute) (myqtt.Ctx) returns the context where the connection was created.

error_msg

(Read only attribute) (String) returns the last error message found while using the connection.

status

(Read only attribute) (Integer) returns an integer status code representing the textual error string returned by attribute error_msg.

host

(Read only attribute) (String) returns the host string the connection is connected to.

host_ip

(Read only attribute) (String) returns the host IP string the connection is connected to.

port

(Read only attribute) (String) returns the port string the connection is using to connected to.

server_name

(Read only attribute) (String) returns connection’s configured serverName

local_addr

(Read only attribute) (String) returns the local address used by the connection.

local_port

(Read only attribute) (String) returns the local port string used by the connection.

role

(Read only attribute) (String) returns a string representing the connection role. Allowed connection role strings are: initiator (client connection), listener (connection that was accepted due to a listener installed), master-listener (the master listener that is waiting for new incoming requests).

ref_count

(Read only attribute) (Integer) returns reference counting current state.

socket

(Read only attribute) (Integer) returns the socket associated to the cnonection

client_id

(Read only attribute) (String) returns the connection client id configured

last_err

(Read only attribute) (Integer) returns last connection error found

username

(Read only attribute) (String) returns the username that was used by this connection (if any) during CONNECT

password

(Read only attribute) (String) returns the password that was used by this connection (if any) during CONNECT. It may not be defined later (because engine clears this value once used). In the case reconnect support is enabled, it will remain available.

ref_count

(Read only attribute) (Integer) returns reference counting current state.