Namespace l2dbus.ServiceObject
L2DBUS ServiceObject
This section describes a Lua ServiceObject class.
A D-Bus service object is an instance of a D-Bus object that appears on the bus with a specific object path. Typically a service object will implement one or more interfaces which define the methods, properties, and signals exposed by the service (e.g. its application programming interface, or API). The handling of requests for a service object from client applications can be delegated to the interfaces themselves since they can handle request from more than one service object. Interfaces can be shared by multiple service objects. Likewise service object themselves can be shared across more than one connection. In this way it's possible for a service object to span multiple buses (e.g. have the same object appear on both a system and session bus).
If the interfaces themselves don't have handlers to process requests (or they chose not to handle a specific request) then any registered object handler gets the opportunity to process the request. If no suitable handler is found then an appropriate error message is returned to the client application.
Note: Although possible, a more convenient method is available to implement custom D-Bus services. The l2dbus.service module provides a friendlier interface for instantiating D-Bus services and internally leverages the ServiceObject. It is recommended that new services are implemented using l2dbus.service methods instead.
Functions
| new (objPath, handler, userToken) |
ServiceObject
| path (object) | |
| setData (object, userToken) | |
| data (object) | |
| addInterface (object, interface) | |
| removeInterface (object, interface) | |
| introspect (object, conn) |
Functions
- new (objPath, handler, userToken)
-
Creates a new ServiceObject.
Creates a new service object used to implement a D-Bus object that can respond to requests, emit signals, and expose properties. The service object can be associated a handler that can process client requests. The signature of the handler has the form:
DBusHandlerResult function onRequest(svcObj, conn, msg, userToken)Where:
- svcObj - The D-Bus service object
- conn - The D-Bus connection from which the request was received
- msg - The D-Bus request message
- userToken - A value specified by the user when the object was created.
The handler function should return one of the following values:
- HANDLER_RESULT_HANDLED - Request handled
- HANDLER_RESULT_NOT_YET_HANDLED - Request not handled
- HANDLER_RESULT_NEED_MEMORY - Request not handled due to lack of memory
For all cases except HANDLER_RESULT_HANDLED the client application will receive an appropriate error message for an unhandled request.
Parameters:
- objPath string A valid D-Bus object path.
- handler func or nil An optional object handler function or nil if none desired.
- userToken optional any Optional client data associated with the handler. Will be passed to the handler when its invoked.
Returns:
-
userdata
The userdata object representing the ServiceObject.
ServiceObject
- path (object)
-
Returns the object path associated with the object.
Parameters:
- object userdata The userdata representing the ServiceObject.
Returns:
-
string or nil
A string with the object path or nil if it
is unset.
- setData (object, userToken)
-
Sets the user data to be passed back in the object request handler.
Parameters:
- object userdata The userdata representing the ServiceObject.
- userToken any A value to pass back in the object request handler callback.
- data (object)
-
Retrieves the data that will be passed to the object request handler.
Parameters:
- object userdata The userdata representing the ServiceObject.
Returns:
-
any
The value that will be returned in the object request handler
callback.
- addInterface (object, interface)
-
Adds an interface to the service object.
A service object can implement more than one interface but the interface names must be unique (e.g. no two interfaces with the same name). This method will fail if you try to add the same interface twice.
Parameters:
- object userdata The userdata representing the ServiceObject.
- interface userdata The interface to add to the object.
Returns:
-
bool
Returns true if the interface was added successfully or
false otherwise.
- removeInterface (object, interface)
-
Removes an interface from the service object.
The same interface instance that was originally added must be used to remove it since the framework keeps a strong reference to that interface until it is removed. If the same instance is not used (e.g. different interface instance with the same name) then the Lua VM will never be able to garbage collect the original interface.
Parameters:
- object userdata The userdata representing the ServiceObject.
- interface userdata The interface to remove from the object.
Returns:
-
bool
Returns true if the interface was removed successfully or
false otherwise.
- introspect (object, conn)
-
Introspects the object and returns the D-Bus XML introspection data.
This method generates the D-Bus introspection XML data for a service object and returns it as a string. Each interface associated with this object will be introspected as well.
Parameters:
- object userdata The userdata representing the ServiceObject.
- conn userdata The userdata representing the Connection.
Returns:
-
string or nil
Returns the D-Bus XML introspection data or nil
if it is unavailable.