qmi.core.messaging

Sending and receiving messages between QMI objects and between QMI contexts.

The classes defined in this module are for the most part used internally by QMI. Application programs should typically not interact with these classes directly.

Classes

`MessageRouter`(context_name, workgroup_name)	Sends and delivers messages within a QMI context and between contexts.
`QMI_ErrorReplyMessage`(source_address, ...)	Special reply message, sent when a request can not be processed.
`QMI_InitialHandshakeMessage`(context_name, ...)	Initial handshake message exchanged for a new TCP connection.
`QMI_Message`(source_address, destination_address)	Base class for all messages sent via QMI.
`QMI_MessageHandler`(address)	Base class for QMI classes which can receive messages.
`QMI_MessageHandlerAddress`(context_id, object_id)	Unique address associated with a specific message handler.
`QMI_ReplyMessage`(source_address, ...)	Base class for reply messages in QMI.
`QMI_RequestMessage`(source_address, ...)	Base class for request messages in QMI.

class qmi.core.messaging.QMI_MessageHandlerAddress(context_id: str, object_id: str)

Unique address associated with a specific message handler.

context_id

Name of the context that contains the message handler.

Type:: str

object_id

Unique name for the message handler within the context. In many cases, this is simply the RPC object name.

Type:: str

context_id: str: Alias for field number 0

object_id: str: Alias for field number 1

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class qmi.core.messaging.QMI_Message(source_address: QMI_MessageHandlerAddress, destination_address: QMI_MessageHandlerAddress)

Base class for all messages sent via QMI.

source_address: Address of the object which sent this message.

destination_address: Address of the object which should receive this message.

class qmi.core.messaging.QMI_RequestMessage(source_address: QMI_MessageHandlerAddress, destination_address: QMI_MessageHandlerAddress)

Base class for request messages in QMI.

Request messages are used when a reply is expected. When an object sends a request message, it expects to receive exactly one corresponding reply message.

The association between request messages and reply messages is tracked explicitly via the request_id attribute.

request_id: Unique ID for this message. Automatically initialized to a random 64-bit integer.

class qmi.core.messaging.QMI_ReplyMessage(source_address: QMI_MessageHandlerAddress, destination_address: QMI_MessageHandlerAddress, request_id: str)

Base class for reply messages in QMI.

A reply message is a response to a request message. When an object receives a request message, it is expected to send exactly one corresponding reply message.

The destination of the reply message is taken from the source of the corresponding request message. The request_id attribute of the reply message must be equal to the request_id of the corresponding request message.

request_id: Request ID of the QMI_RequestMessage to which this message is a reply.

class qmi.core.messaging.QMI_ErrorReplyMessage(source_address: QMI_MessageHandlerAddress, destination_address: QMI_MessageHandlerAddress, request_id: str, error_msg: str)

Special reply message, sent when a request can not be processed.

An instance of QMI_ErrorReplyMessage is generated when a request message can not be delivered, or when the associated connection is lost before a reply is received. This message will then be delivered in place of the actual reply to the pending request.

error_msg: Short string, describing the reason why the request could not be processed.

class qmi.core.messaging.QMI_InitialHandshakeMessage(context_name: str, version: str, is_server_handshake: bool): Initial handshake message exchanged for a new TCP connection.

class qmi.core.messaging.QMI_MessageHandler(address: QMI_MessageHandlerAddress)

Base class for QMI classes which can receive messages.

A message handler instance has a unique address and is registered with the QMI context.

handle_message(message: QMI_Message) → None

Called by the QMI message router when a message for this object is received.

This method is responsible for handling the received message. This method should not raise exceptions other than QMI_MessageDeliveryException.

Subclasses must implement this method.

Raises:: QMI_MessageDeliveryException – If the message can not be accepted.

shutdown() → None

Called by the QMI message router during unregistering of the handler.

After this call, no more messages will be received.

Subclasses can implement this method to free resources they are using. The default implementation does nothing.

Do not call this method explicitly. It will be called automatically during unregistering of the message handler.

class qmi.core.messaging.MessageRouter(context_name: str, workgroup_name: str)

Sends and delivers messages within a QMI context and between contexts.

Each QMI context owns one MessageRouter instance to handle messaging. The MessageRouter provides methods to send messages and to register QMI objects as message receivers.

The MessageRouter will create a background thread to handle network connections.

This class is intended for internal use within QMI. Application programs should not interact with this class directly.

property suppress_version_mismatch_warnings: bool: If set to True, no warnings will be issued when connecting to a peer that runs a different version of QMI.

set_peer_context_callbacks(cb_peer_context_added: Callable[[str], None] | None, cb_peer_context_removed: Callable[[str], None] | None) → None

Register callback functions to be invoked when a peer context is added or removed.

cb_peer_context_added(peer_context_name) is invoked when a new outgoing connection to a peer context is established. This callback is not invoked for new incoming peer connections.

cb_peer_context_removed(peer_context_name) is invoked when a peer connection (outgoing or incoming) is removed.

The callbacks run in the socket manager thread. These callbacks are typically handled by the SignalManager to manage its remote signal subscriptions.

This function must not be called after starting the message router.

start() → None: Start the socket manager thread.

stop() → None: Disconnect all peer connections, stop servers and stop the socket manager thread.

register_message_handler(message_handler: QMI_MessageHandler) → None: Register a local message handler.

unregister_message_handler(message_handler: QMI_MessageHandler) → None: Unregister a previously registered message handler.

start_tcp_server(tcp_server_port: int) → None

Start TCP server for incoming connections from remote contexts.

Parameters:: tcp_server_port – TCP server port, or 0 to assign a free port.

start_udp_responder(udp_server_port: int) → None: Start UDP responder on the specified UDP port.

connect_to_peer(peer_context_name: str, peer_address: str) → None: Connect as a client to a remote QMI context at the specified peer address.

disconnect_from_peer(peer_context_name: str) → None

Disconnect from the specified remote QMI context.

Raises:: QMI_UnknownNameException – If the specified context is not connected.

notify_peer_context_added(context_name: str) → None

Called by the SocketManager when an outgoing peer connection is added.

This method runs in the socket manager thread.

notify_peer_context_removed(context_name: str) → None

Called by the SocketManager when a peer connection is removed.

This method runs in the socket manager thread.

deliver_message(message: QMI_Message) → None

Deliver a message to a local message handler.

This function may be called via send_message() for direct local delivery of locally originated messages. Alternatively, this function may be called by the socket manager when a message is received from a peer connection.

This method is thread-safe. It can be called from any thread.

Raises:: QMI_MessageDeliveryException – If the message can not be delivered.

send_message(message: QMI_Message) → None

Send the message to its destination.

If the destination is within the local context, this function delivers the message to the local message handler. Otherwise, this function sends the message to the correct peer context.

This method is thread-safe. It can be called from any thread.

Raises:: QMI_MessageDeliveryException – If the message can not be routed.

get_peer_context_names() → list[str]: Return a list of currently connected peer context names.