L2DBUS

• Index

Contents

• Functions
• Tables
• Service
• ReplyContext

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.service

Service Module.

This module provides a higher-level abstraction over the low level ServiceObject class. This abstraction makes it easier to implement a D-Bus service in Lua and is consequently the preferred method for developing D-Bus services in Lua.

Functions

new (objPath, introspectable, defaultHandler)	Constructs a new Service instance.
convertXmlToIntfMeta (intfName, xmlStr)	Converts a D-Bus XML description of an interface to a Lua equivalent.

Tables

DbusInterfaceMetadata

The Lua Table Representation of a D-Bus Interface Description.

Service

attach (svc, conn)	Attaches a D-Bus service with associated object path to the connection.
detach (svc, conn)	Detach a D-Bus service with associated object path from the connection.
addInterface (svc, name, metadata)	Adds an interface to the D-Bus service.
removeInterface (svc, name)	Removes an interface from the D-Bus service.
registerMethodHandler (svc, intfName, methodName, handler)	Registers a handler for a D-Bus interface/method combination.
unregisterMethodHandler (svc, intfName, methodName)	Unregisters a handler for D-Bus interface/method handler combination.
emit (svc, conn, intfName, signalName, ...)	Provides a method to emit a signal on a specific connection.

ReplyContext

getConnection (ctx)	Returns the D-Bus connection associated with the context.
getMessage (ctx)	Returns the request message associated with the context.
needsReply (ctx)	Returns an indication of whether the request expects a reply message.
reply (ctx, ...)	Returns a response to the associated method request.
error (ctx, errName, errMsg)	Returns an error response to the associated method request.

Functions

new (objPath, introspectable, defaultHandler)

Constructs a new Service instance.

The constructor creates a Service instance. One or more D-Bus interfaces can be associated with Service.

Parameters:

• objPath string The D-Bus object path this service is implementing. It must be a valid path.
• introspectable bool If set to true this service will support D-Bus introspection by implementing org.freedesktop.DBus.Introspectable on behalf of the service. If false then the resulting service cannot be introspected.
• defaultHandler func The default (global) handler for this object. This is called if none of the associated interface handlers can process a request. It is the request handler of last resort.

Returns:

table A Service instance.

convertXmlToIntfMeta (intfName, xmlStr)

Converts a D-Bus XML description of an interface to a Lua equivalent.

This function takes a D-Bus XML introspection description of an interface and converts it to a Lua table representation that can be used to register the interface with a D-Bus service. If the D-Bus XML description lists multiple interfaces then only the interface with the specified name will be decoded into an equivalent Lua table.

Parameters:

• intfName string The D-Bus interface name to be converted. The name should be defined in the XML description.
• xmlStr string The D-Bus introspection XML for the interface.

Returns:

table or nil A Lua table representation of the D-Bus XML interface description. Returns nil if the XML could not be converted or the interface name was not found.

Tables

DbusInterfaceMetadata

The Lua Table Representation of a D-Bus Interface Description.

The metadata describing a D-Bus interface can be specified using one of two different formats. This first form is the direct D-Bus XML introspection description. The other format describes the D-Bus interface using a Lua table. Internally, the XML format is always transformed into the more efficiently manipulated Lua table-based representation described here.

An example Lua table representation of a D-Bus interface is shown below:

    {
        interface = "org.example.Interface",
        properties = {                  -- Array of properties
            {                           -- IntrospectProp[1] (Prop1)
                name = "Prop1",
                sig = "s",
                access = "rw"
            },
            ...                         -- IntrospectProp[N] (PropN)
        },
        signals = {                     -- Array of signals
            {                           -- IntrospectItem[1] (Signal1)
                name = "Signal1",
                args = {                -- Signal1 arguments
                    {                   -- IntrospectArg[1]
                        sig = "s",
                        name = "arg1",
                    },
                    ...                 -- IntrospectArg[N]
                }
            },
            ...                         -- IntrospectItem[N] (SignalN)
        },
        methods = {                     -- Array of methods
            {                           -- IntrospectItem[1] (Method1)
                name = "Method1",
                args = {                -- Method1 arguments
                    {                   -- IntrospectArg[1]
                        sig = "s",
                        name = "arg1",
                        dir = "in"
                    },
                    ...                 -- IntrospectArg[N]
                }
            },
            ...                         -- IntrospectItem[N] (MethodN)
        }
    }

The key fields for the Lua table include:

Fields:

• interface The valid D-Bus interface name
• methods An array of methods of type IntrospectItem
• signals An array of signals of type IntrospectItem
• properties An array of properties of type IntrospectProp

Service

attach (svc, conn)

Attaches a D-Bus service with associated object path to the connection.

This method is used to attach and register the service's object path with the D-Bus connection. Once attached the service can receive messages sent to its object path.

Parameters:

• svc userdata The Service instance.
• conn userdata The D-Bus connection.

Returns:

bool Returns true if the service is attached and false otherwise.

detach (svc, conn)

Detach a D-Bus service with associated object path from the connection.

This method is used to detach and unregister the service's object path from the D-Bus connection. Once detached the service will no longer receive messages sent to its object path.

Parameters:

• svc userdata The Service instance.
• conn userdata The D-Bus connection.

Returns:

bool Returns true if the service is detached and false otherwise.

addInterface (svc, name, metadata)

Adds an interface to the D-Bus service.

This method is used to add the interface described by the provided metadata to the service. If this service is introspectable then the interface will appear to be implemented by the service with the associated object path. The metadata can be in one of two formats: D-Bus introspection XML or a Lua table equivalent. The function convertXmlToIntfMeta can be used to convert XML to the Lua equivalent but is typically unnecessary for this method.
If the interface that is being added contains D-Bus properties then the D-Bus property interface org.freedesktop.DBus.Properties will automatically be added to this service. It is required that handlers for the Get, Set, and GetAll methods will be registered to handle inquires on the object properties.

Parameters:

• svc userdata The Service instance.
• name string The D-Bus name of the interface being added to the service. It must be a valid D-Bus interface name.
• metadata string or table The meta-data description of the D-Bus interface. This can either be the D-Bus XML introspection description or the equivalent Lua table representation. If the D-Bus XML description lists multiple interfaces then only the interface with the specified name will be decoded into an equivalent Lua table representation.

Returns:

bool Returns true if the interface is added successfully and false otherwise.

removeInterface (svc, name)

Removes an interface from the D-Bus service.

This method removes the named D-Bus interface from the service. Handlers for this interface will no longer be called.

Parameters:

• svc userdata The Service instance.
• name string The D-Bus interface name to remove.

Returns:

bool Returns true if the interface is removed and false otherwise.

registerMethodHandler (svc, intfName, methodName, handler)

Registers a handler for a D-Bus interface/method combination.

This method registers a handler that will be called when a service request directed to a given object path/interface/method combination is received.
The signature of the handler function will be of the form:

    function onRequest(ctx, arg1, arg2, ..., argN)

Where the first argument of the handler will always be a context instance that can used to reply either immediately or at some point int the future (outside the scope of the handler if a reference to the context is maintained). A Lua error may be thrown if an error is encountered registering a handler.

Parameters:

• svc userdata The Service instance.
• intfName string The D-Bus interface name to associate the handler.
• methodName string The D-Bus method name assocated with the handler.
• handler func The handler function which will receive the message. If a handler for this interface/method combination was already specified then it will be replaced by this handler.

unregisterMethodHandler (svc, intfName, methodName)

Unregisters a handler for D-Bus interface/method handler combination.

This method disassociates the method handler from the method so that it will no longer be called when a matching method request is received by the service. If the D-Bus interface name is unknown a Lua error will be thrown.

Parameters:

• svc userdata The Service instance.
• intfName string The D-Bus interface name owning the method.
• methodName string The name of the D-Bus method to unregister the handler.

Returns:

bool Returns true if the handler is removed and false otherwise.

emit (svc, conn, intfName, signalName, ...)

Provides a method to emit a signal on a specific connection.

This method provides a means to send a D-Bus signal with the given interface name and signal name over the provided connection. Since a service can exist on more than one connection (or D-Bus bus) the actual connection on which the signal should be sent needs to be specified explicitly. Connections host services and not vice-versa. This method can throw Lua errors if the parameters are invalid or problems occur encoding parameters or sending the signal.
Note: The interface specified by this method must be implemented by this service. It is an error if the interface is unknown (e.g. an arbitrary interface name cannot be specified). Also, signals are only queued to be sent and are not immediately delivered. Call the flush method on the connection to block until the message has been sent.

Parameters:

• svc userdata The Service instance.
• conn userdata The D-Bus connection on which to emit the signal.
• intfName string The D-Bus interface name owning the signal.
• signalName string The name of the D-Bus signal.
• ... any The list of arguments associated with the signal being sent. The signature of the signal (as specified in the D-Bus interface description) is used to map the Lua types to their underlying D-Bus types.

Returns:

1. bool Returns true if the signal is enqueued to be sent and false otherwise.
2. number Returns the serial number of the enqueued signal or zero (0) if it cannot be queued.

ReplyContext

getConnection (ctx)

Returns the D-Bus connection associated with the context.

Returns the D-Bus connection on which the original request message arrived. This will be the connection on which the response is sent.

Parameters:

• ctx table The reply context.

Returns:

userdata The D-Bus connection associated with the context.

getMessage (ctx)

Returns the request message associated with the context.

Returns the original D-Bus request message for which there should be a reply.

Parameters:

• ctx table The reply context.

Returns:

userdata The D-Bus request message associated with the context.

needsReply (ctx)

Returns an indication of whether the request expects a reply message.

The method returns a boolean value indicating whether or not the original request expects a reply (or not). If no reply is needed/expected then message traffic can be reduced by not sending a reply. Typically most requests expect a reply. Technically, even if a reply is not needed it is not an error to send one anyway. The client will likely ignore the reply.

Parameters:

• ctx table The reply context.

Returns:

bool Returns true if the request expects a reply, false if a reply is not needed.

reply (ctx, ...)

Returns a response to the associated method request.

The method queues the response to a request associated with the context. The parameters are marshalled into a response message which is then enqueued into the out-going message queue. If it's critical that the response is delivered immediately (rather than during the next iteration of the dispatch loop) call the flush method on the connection to block until the response message has been sent. It is considered an error to respond to the same request more than once. An error reply is considered a response as well.

Parameters:

• ctx table The reply context.
• ... any The list of arguments associated with the response. The signature of these arguments is taken from the D-Bus interface specification for the return (out) parameters. This signature is used to guide the conversion from Lua types to D-Bus types.

Returns:

1. bool Returns true if the response is enqueued to be sent and false otherwise.
2. number Returns the serial number of the enqueued response message or zero (0) if it cannot be queued.

error (ctx, errName, errMsg)

Returns an error response to the associated method request.

The method queues an error response to the request associated with the context. The error is enqueued into the out-going message queue. If it's critical that the D-Bus error is delivered immediately (rather than during the next iteration of the dispatch loop) call the flush method on the connection to block until the response message has been sent. An error reply is considered a valid response to a request and fullfills the request. An additional response is unnecessary.

Parameters:

• ctx table The reply context.
• errName string The D-Bus error name.
• errMsg string or nil An optional error message.

Returns:

1. bool Returns true if the error is enqueued to be sent and false otherwise.
2. number Returns the serial number of the enqueued error message or zero (0) if it cannot be queued.