Namespace l2dbus.Connection
L2DBUS Connection
This namespace defines the functions/methods associated with the L2DBUS Connection class.
Functions
| open (dispatcher, address, privateConn, exitOnDisconnect) | |
| openStandard (dispatcher, busId, privateConn, exitOnDisconnect) |
Connection
Functions
- open (dispatcher, address, privateConn, exitOnDisconnect)
-
Opens a connection to a remote address.
This function opens and returns a D-Bus connection. It can be used to open an arbitrary address instead of one of the "standard" well-known ones. Optionally the connection can be opened shared (e.g. if the connection already exists then the existing connection is returned) or private. Likewise the connection can be configured to cause the application to exit on disconnect. By default the connection will be shared and will not exit on disconnect. It's recommended that all connections should be opened shared to minimize resource usage.
When the connection is no longer referenced the Lua garbage collector will either close the connection (if opened privately) or unreference the connection (if opened as shared).
Parameters:
- dispatcher userdata The Dispatcher to associate with the connection.
- address string Remote D-Bus address to open
- privateConn optional bool Optional flag indicating whether this is a private (true) or shared (false) connection. Defaults to a shared connection (false)
- exitOnDisconnect optional bool Optional flag indicating whether the application should exit on disconnect (true or false). Defaults to false.
Returns:
-
userdata
Connection userdata object
- openStandard (dispatcher, busId, privateConn, exitOnDisconnect)
-
Opens a connection to one of the standard well-known buses.
This function opens and returns a D-Bus connection to one of the standard well-known buses. The well-known buses include the BUS_SYSTEM, BUS_SESSION, and BUS_STARTER buses. The connection can optionally be opened shared (e.g. if the connection already exists then the existing connection is returned) or private. Likewise the connection can be configured to cause the application to exit on disconnect. By default the connection will be shared and will not exit on disconnect. It's recommended that all connections should be opened shared to minimize resource usage.
When the connection is no longer referenced the Lua garbage collector will either close the connection (if opened privately) or unreference the connection (if opened as shared).
Parameters:
- dispatcher userdata The Dispatcher to associate with the connection.
- busId number The constant bus identifier: BUS_SYSTEM, BUS_SESSION, or BUS_STARTER
- privateConn optional bool Optional flag indicating whether this is a private (true) or shared (false) connection. Defaults to a shared connection (false)
- exitOnDisconnect optional bool Optional flag indicating whether the application should exit on disconnect (true or false). Defaults to false.
Returns:
-
userdata
Connection userdata object
Connection
- isConnected (conn)
-
Tests whether the connection is connected to the bus.
This method can be called to detect whether or not the provided connection is in fact connected to the bus.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
bool
Returns true if connected, false otherwise.
- isAuthenticated (conn)
-
Tests whether the connection has been authenticated.
This method can be called to detect whether or not the provided connection has been authenticated.
Note: If the connection was authenticated then disconnected then this function still returns true.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
bool
Returns true if authenticated, false otherwise.
- isAnonymous (conn)
-
Tests whether the connection is not authenticated as a specific user.
If the connection is not authenticated, this function returns true, and if it is authenticated but as an anonymous user, it returns true. If it is authenticated as a specific user, then this returns false.
Note: If the connection was authenticated as anonymous then disconnected, this function still returns true.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
bool
Returns true if not authenticated or authenticated as anonymous
- getServerId (conn)
-
Gets the ID of the server address we are authenticated to on a client-side connection.
If the connection is on the server side this will always return nil. For additional details on this method see the original 'C' documentation here.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
string or nil
Returns the ID of the server if a client-side connection, nil otherwise.
- getBusId (conn)
-
Asks the bus to return its the globally unique ID as described in the D-Bus specification.
For additional details on this method see the original 'C' documentation here.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
string or nil
Returns bus ID or nil if there is an error.
- getDescriptor (conn)
-
Retrieves the underlying file descriptor for the connection.
If the underlying file descriptor is not available then nil will be returned. DO NOT read or write to this file descriptor or try to select() on it if already utilizing a D-Bus Watch for main loop integration. Exceptions may exist if attempting to integrate external main loops with the L2DBUS Dispatcher. In this scenario the run method should only be called when the external loop detects write activity on this descriptor. The run method should be called with the l2dbus.Dispatcher.DISPATCH_NO_WAIT option followed by a call to Connection:flush to dispatch any queued messages.
Parameters:
- conn userdata The D-Bus connection object.
Returns:
-
number or nil
Returns the file descriptor or nil if none is
available.
- canSendType (conn, type)
-
Tests whether a certain type can be send via the connection.
This function will always return true for all types with the exception of DBUSTYPEUNIX_FD. For additional details on this method see the original 'C' documentation here.
Parameters:
- conn userdata The D-Bus connection object
- type number or string The D-Bus type to check. The type definitions can be found here. The type can be expressed as a D-Bus integral type or as a single character string.
Returns:
-
bool
Returns true if the D-Bus type can be sent or false otherwise.
- send (conn, msg)
-
Adds a message to the outgoing message queue.
This method does not block to write the message to the network; that happens asynchronously. To force the message to be written an explicit call to flush must be made otherwise the message will be sent the next time the main loop is run.
Parameters:
- conn userdata The D-Bus connection object
- msg userdata The D-Bus message to send
Returns:
- bool Returns true if the message is queued to be sent and false otherwise.
- number If the message is queued successfully then this will be the transmitting serial number of the message otherwise this is zero (0).
- sendWithReply (conn, msg, timeout)
-
Queues a message to send as with send but returns a PendingCall to receive the reply message later.
If no reply is received in the given (optional) timeout the PendingCall expires and a synthetic error reply (generated locally, not by the remote application) is generated indicating a timeout occurred.
Parameters:
- conn userdata The D-Bus connection object
- msg userdata The D-Bus message to send
- timeout optional number An optional timeout in milliseconds to wait for a reply. Two special values are allowed as well: TIMEOUT_USE_DEFAULT and TIMEOUT_INFINITE. The default value (if none is specified) is TIMEOUT_USE_DEFAULT.
Returns:
- bool Returns true if the message is queued to be sent and false otherwise.
- userdata or nil If the message is queued successfully then a PendingCall is returned or nil on failure.
- sendWithReplyAndBlock (conn, msg, timeout)
-
Sends a message and blocks for a certain period of time while waiting for a reply.
This function does not re-enter the main loop. This means messages other than the reply (e.g. other requests, signals, etc...) are queued but not processed. This function is used to invoke method calls on a remote object. If a normal reply is received then the reply message is returned. If an error is encountered or a D-Bus error message is received then nil is returned as the first return parameter followed by an optional error name and error message.
Parameters:
- conn userdata The D-Bus connection object
- msg userdata The D-Bus message to send
- timeout optional number An optional timeout in milliseconds to wait for a reply. Two special values are allowed as well: TIMEOUT_USE_DEFAULT and TIMEOUT_INFINITE. The default value (if none is specified) is TIMEOUT_USE_DEFAULT.
Returns:
- userdata or nil The reply message or nil if there was an error. If a D-Bus error message is received then nil is returned here and the error name and message are returned in the next two parameters.
- string or nil If there was an error or a D-Bus error message was returned then a string indicating the error name may be returned or nil
- string or nil If there was an error or a D-Bus error message was returned then a string containing an optional error message may be returned or nil (if there is no message).
- flush (conn)
-
Blocks until the outgoing message queue is empty.
Parameters:
- conn userdata The D-Bus connection object
- hasMessagesToSend (conn)
-
Checks whether there are messages in the outgoing message queue.
The flush method can be used to block until all outgoing messages have been written to the underlying transport (such as a socket).
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
bool
Returns true if there are pending messages in
the outgoing queue or false otherwise.
- registerMatch (conn, rule, handler, userToken)
-
Registers a handler for messages that match a defined set of rules.
This method registers a function to receive messages that match a specific match rule. A match rule as described here is part of the message bus routing protocol. These rules describe the messages that should be delivered to a client based on the contents of a message. The rule itself is describe by a Lua table that contains specific fields that map to keywords in the D-Bus specification.
The message handler should have the following prototype:
function onMatch(match, message, userToken)Parameters:
- conn userdata The D-Bus connection object
- rule table The match rule table
- handler func The message handler for the rule
- userToken optional any Optional user defined data that is delivered to the message handler
Returns:
-
lightuserdata
Returns a match rule handle. The handle can be used
to unregister a match.
see also:
- unregisterMatch (conn, handle)
-
Unregisters a message handler for the given match rule.
This method unregisters the handler for the match rule referenced by the handle returned by the call to register a match.
Parameters:
- conn userdata The D-Bus connection object
- handle lightuserdata The match rule handle
Returns:
-
bool
Returns true if the match rule is unregistered successfully
and false if the handle is unknown or there is an error.
- registerServiceObject (conn, svcObj)
-
Registers a service object with the connection.
This method registers a service object with the connection that will receive and handle requests from clients. A service object can be registered with more than one connection if necessary. This means a service object can span multiple buses (e.g. the same instance across a session or system bus).
Parameters:
- conn userdata The D-Bus connection object
- svcObj userdata The D-Bus service object
Returns:
-
bool
Returns true if the service object is registered
successfully and false otherwise
- unregisterServiceObject (conn, svcObj)
-
Unregisters a service object from the connection.
This method unregisters a service object from the specified D-Bus connection.
Parameters:
- conn userdata The D-Bus connection object
- svcObj userdata The D-Bus service object to unregister
Returns:
-
bool
Returns true if the service object is unregistered
successfully and false otherwise
- getMaxMessageSize (conn)
-
Returns the maximum size message this connection is allowed to receive.
The maximum size of an individual message that this connection is allowed to receive in bytes.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
number
Returns the maximum size of an individual message that this
connection is allowed to received in bytes.
- setMaxMessageSize (conn, size)
-
Sets the maximum size message this connection is allowed to receive.
Sets the maximum size (in bytes) of an individual message that this connection is allowed to receive.
Parameters:
- conn userdata The D-Bus connection object
- size number The maximum message size in bytes
- getMaxReceivedSize (conn)
-
Gets the value set by setMaxReceivedSize.
This is the maximum total number of bytes that can be used for all messages received on this connection. Messages are counted toward the maximum until they are finalized (e.g. collected by the Lua garbage collector). When the maximum limit is reached the connection will not read more data until some messages are finalized. For additional semantic information see the description here.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
number
Returns the maximum total number of bytes that can be used
for all messages received on this connection.
- setMaxReceivedSize (conn, size)
-
Sets the the maximum total number of bytes that can be used for all messages received on this connection.
This is the maximum total number of bytes that can be used for all messages received on this connection. Messages are counted toward the maximum until they are finalized (e.g. collected by the Lua garbage collector). When the maximum limit is reached the connection will not read more data until some messages are finalized. For additional semantic information see the description here.
Parameters:
- conn userdata The D-Bus connection object
- size number The maximum total number of bytes that can be used for all messages received on this connection.
- getOutgoingSize (conn)
-
Gets the approximate size in bytes of all messages in the outgoing message queue.
This is only an approximate value and shouldn't be considered a precise amount.
Parameters:
- conn userdata The D-Bus connection object
Returns:
-
number
Returns the approximate size (in bytes) of all the messages
in the outgoing queue.