L2DBUS

• Index

Contents

• Functions
• MsgBusController

Modules

• l2dbus
• l2dbus-ev
• l2dbus-glib
• l2dbus.msgbusctrl
• l2dbus.proxyctrl
• l2dbus.service
• l2dbus.validate
• l2dbus.xml

Topics

• 01-introduction.md

Namespaces

• l2dbus.Connection
• l2dbus.Dbus
• l2dbus.DbusTypes
• l2dbus.Dispatcher
• l2dbus.Int64
• l2dbus.Interface
• l2dbus.Introspection
• l2dbus.Match
• l2dbus.Message
• l2dbus.PendingCall
• l2dbus.ServiceObject
• l2dbus.Timeout
• l2dbus.Trace
• l2dbus.Uint64
• l2dbus.Watch

Module l2dbus.msgbusctrl

Message Bus Controller Module.

This module provides a controller for the D-Bus Message Bus which implements the org.freedesktop.DBus interface. The controller provides methods to gain access to the proxy interface of the Message Bus where methods can be called and signals received from the service.

Functions

new (conn)

Constructs a new Message Bus Controller (MsgBusController) instance.

MsgBusController

bind (ctrl, doIntrospect)	Binds the controller to the Message Bus.
unbind (ctrl)	Unbinds the controller from the Message Bus.
getIntrospectionData (ctrl)	Returns the parsed introspection data for the Message Bus.
getProxy (ctrl)	Returns the actual proxy for the Message Bus.
setTimeout (ctrl, timeout)	Sets the timeout for accessing method/properties of the Message Bus.
getTimeout (ctrl)	Gets the global timeout value used by the Message Bus proxy.
setProxyNoReplyNeeded (ctrl, mode)	Sets whether Message Bus proxy method calls expect/need a reply.
getProxyNoReplyNeeded (ctrl)	Indicates whether Message Bus proxy calls need/expect a reply.
setBlockingMode (ctrl, mode)	Sets whether proxy calls to the Message Bus are blocking or unblocking.
getBlockingMode (ctrl)	Retrieves whether proxy calls are blocking or non-blocking.
connectSignal (ctrl, sigName, handler)	Connects a handler for a specific Message Bus signal.
disconnectSignal (ctrl, hnd)	Disconnects a handler from a specific Message Bus signal.
disconnectAllSignals (ctrl)	Disconnects from all signals of the Message Bus.

Functions

new (conn)

Constructs a new Message Bus Controller (MsgBusController) instance.

The constructor for a Message Bus Controller is used to call methods and receive signals from the D-Bus Message Bus service.

Parameters:

• conn userdata The Connection to attach the controller to.

Returns:

table A MsgBusController instance.

MsgBusController

bind (ctrl, doIntrospect)

Binds the controller to the Message Bus.

This method may throw a Lua error if an exceptional (unexpected) error occurs.

Parameters:

• ctrl userdata Message Bus controller instance.
• doIntrospect bool If set to true the controller will make an introspection call on the Message Bus service. If set to false (the default) the controller will use cached introspection data to generate the proxy interface.

Returns:

1. true or nil Returns true if the binding operation succeeds or nil on failure.
2. string or nil Returns an error name or nil if a name is unavailable and the binding operation fails.
3. string or nil Returns an error message or nil if a message is unavailable and the binding operation fails.

unbind (ctrl)

Unbinds the controller from the Message Bus.

Once unbound, methods on the Message Bus proxy should no longer be called.

Parameters:

• ctrl userdata Message Bus controller instance.

getIntrospectionData (ctrl)

Returns the parsed introspection data for the Message Bus.

The returned Lua table is a representation of the D-Bus XML data in a format that is understood by the proxy. Internally the proxy does not maintain the original D-Bus XML description.

Parameters:

• ctrl userdata Message Bus controller instance.

Returns:

table A Lua table containing the parsed introspection data for the Message Bus.

getProxy (ctrl)

Returns the actual proxy for the Message Bus.

The Message Bus Controller controls the configuration and behavior of the actual proxy implementation. The proxy object contains both the method signatures and properties of the Message Bus service itself and can be used to directly call methods or interrogate properties on the remote service.

Parameters:

• ctrl userdata Message Bus controller instance.

Returns:

table Returns the Message Bus proxy instance.

setTimeout (ctrl, timeout)

Sets the timeout for accessing method/properties of the Message Bus.

The timeout (in milliseconds) controls how long the proxy will wait to hear from the Message Bus service before timing out. All calls through the proxy interface will use this global timeout when a D-Bus request message is issued on the bus. The controller does not offer a per method/property timeout but instead applies the timeout to all future requests.

The timeout value may be set to two well-know special values: TIMEOUT_USE_DEFAULT or TIMEOUT_INFINITE

Parameters:

• ctrl userdata Message Bus controller instance.
• timeout number The time in milliseconds to set as the timeout for future calls to the Message Bus. This value applies globally to all method/property calls. The timeout value must be non-negative.

getTimeout (ctrl)

Gets the global timeout value used by the Message Bus proxy.

Returns the timeout value used by the proxy when making method calls or manipulating properties.

Parameters:

• ctrl userdata Message Bus controller instance.

Returns:

number The timeout (in milliseconds) used by the proxy. It may be one of the special values: TIMEOUT_USE_DEFAULT or TIMEOUT_INFINITE.

setProxyNoReplyNeeded (ctrl, mode)

Sets whether Message Bus proxy method calls expect/need a reply.

This method determines whether proxy calls to the Message Bus need a response. Specifically, if set to true, out-going messages are marked to indicate that a reply is not needed so that the Message Bus can decide whether or not to reply to the message. The Message Bus can always reply regardless of the flag but it means the near-end will ignore the reply. The default setting for the controller is false which means replies are expected from the far-end. If set to true out-going messages are marked to indicate a reply is not needed. This setting applies to all subsequent proxy method calls made after the value is changed. The behavior of individual proxy method calls can only be controlled by calling this method before making the method call on the Message Bus proxy.

Parameters:

• ctrl table The Message Bus controller instance.
• mode bool Set to true if no reply is needed/expected, false to indicate a reply is expected.

getProxyNoReplyNeeded (ctrl)

Indicates whether Message Bus proxy calls need/expect a reply.

This method returns an indication of whether Message Bus proxy method calls expect a reply. If this returns true then no reply is needed and proxy method calls will not wait to hear the reply to a request. If false is returned (the default behavior) then it is expected that proxy method calls will return a reply message.

Parameters:

• ctrl table The Message Bus controller instance.

Returns:

bool Returns true if no reply is expected from the Message Bus, false (the default) if every proxy request expects a reply.

setBlockingMode (ctrl, mode)

Sets whether proxy calls to the Message Bus are blocking or unblocking.

This option determines whether calls made through the proxy are blocking (synchronous) or non-blocking (asynchronous) calls. A blocking call will block waiting for the reply or a timeout error before returning. A non-blocking call will return a PendingCall object which can be used to wait for a reply or for registering a handler that will be called when the reply or error is returned. Once set this option applies globally to all methods/properties of the Message Bus proxy.

Parameters:

• ctrl userdata Message Bus controller instance.
• mode bool Set to true if proxy calls should be blocking and false for non-blocking (asynchronous) calls.

getBlockingMode (ctrl)

Retrieves whether proxy calls are blocking or non-blocking.

Returns the current option for call to methods/properties of the Message Bus service.

Parameters:

• ctrl userdata Message Bus controller instance.

Returns:

bool Returns true for blocking mode and false for non-blocking mode.

connectSignal (ctrl, sigName, handler)

Connects a handler for a specific Message Bus signal.

This method registers a signal handler for the specified Message Bus signal name. When a matching signal is emitted by the Message Bus the handler function will be called as a result. The signature of the handler function should match the signature specified by the D-Bus XML signal description for the Message Bus.

Parameters:

• ctrl userdata Message Bus controller instance.
• sigName string The name of the Message Bus signal to receive.
• handler func The signal handler function which is called with the same arguments as specified for the signal in the D-Bus XML description for the org.freedesktop.DBus interface.

Returns:

lightuserdata or nil Returns an opaque handle that can be used to disconnect the handler. Can be nil if there was an error connecting to the signal.

disconnectSignal (ctrl, hnd)

Disconnects a handler from a specific Message Bus signal.

This method disconnects the signal handler with the specified handle returned by connectSignal.

Parameters:

• ctrl userdata Message Bus controller instance.
• hnd lightuserdata The opaque handle originally returned by the call to connectSignal.

Returns:

bool Returns true if the handler was disconnected successfully otherwise false.

disconnectAllSignals (ctrl)

Disconnects from all signals of the Message Bus.

This method makes a best effort to disconnects all the signal handlers for all Message Bus signals.

Parameters:

• ctrl userdata Message Bus controller instance.