Namespace l2dbus.Interface

L2DBUS Interface

This section describes a Lua Interface class.

This class is used to define an interface in D-Bus terms so that services can be offered on the D-Bus that support a specific API.

Once created, interfaces are typically associated with one (or more) D-Bus service objects. The interface itself can be configured to receive and handle client requests. If not handled by the interface the associated service object is given the opportunity to handle the request.

Functions

new (interface, handler, userToken)

Tables

IntrospectProp This table that defines an individual D-Bus property item in an interface description.
IntrospectArg This table that defines an individual method/signal argument in an interface description.
IntrospectItem This table that defines a D-Bus method or signal exposed by an interface.

Interface

name (interface)
setData (interface, data)
getData (interface)
registerMethods (interface, methods)
clearMethods (interface)
registerSignals (interface, signals)
clearSignals (interface)
registerProperties (interface, properties)
clearProperties (interface)
introspect (interface)


Functions

new (interface, handler, userToken)

Creates a new Interface.

Creates an empty D-Bus Interface used to describe the API of of a service. With the interface there can be associated a handler that can process client requests. The signature of the handler has the form:

 DBusHandlerResult function onRequest(interface, conn, msg, userToken)

Where:

  • interface - The D-Bus interface associated with the handler
  • 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 interface was created.

The handler function should return one of the following values:

For all cases except HANDLER_RESULT_HANDLED the service object (if it has a handler) will be given the opportunity to process the request. If there are no handlers to satisfy the request or an error occurs the client will receive an appropriate error message.

Parameters:

  • interface string A valid D-Bus interface name to assign to the interface.
  • handler func or nil An optional interface 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 Interface.

Tables

IntrospectProp
This table that defines an individual D-Bus property item in an interface description. An individual property is typically one of many in an array that is associated with an interface.

Possible values for the access field include r (read), w (write), rw or wr (read/write).

Fields:

  • name (string) [Req] The name of the D-Bus property.
  • sig (string) [Req] The D-Bus signature of the property.
  • access (string) [Req] The access permissions for the property (r, w, or rw).

see also:

IntrospectArg
This table that defines an individual method/signal argument in an interface description. An individual argument is typically one of many in an array that is associated with a method/signal.

The field dir can be either in or out but not inout. For D-Bus signal arguments this field isn't required because they are always out. For method arguments if the direction is omitted then it is assumed to be in.

Fields:

  • name (string) [Opt] The name of the argument.
  • sig (string) [Req] The D-Bus signature of the argument.
  • dir (string) [Opt] The direction of the argument (in or out).

see also:

IntrospectItem
This table that defines a D-Bus method or signal exposed by an interface. An array of these tables is passed to the registerMethods or registerSignals to register the methods/signals an interface exposes.

Fields:

  • name (string) [Req] The name of the method or signal
  • args (array) [Opt] An array of arguments of type IntrospectArg

Interface

name (interface)

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:

  • interface userdata The Interface from which to retrieve the name.

Returns:

    string or nil A string with the interface name or nil if it is unset.
setData (interface, data)

Sets the user data to be passed to the request handler.

Parameters:

  • interface userdata The Interface to set the user data.
  • data any The user data. Can be any value.
getData (interface)

Gets the user data associated with the handler.

Parameters:

  • interface userdata The Interface to get the user data.

Returns:

    any The user data associated with the interface handler.
registerMethods (interface, methods)

Registers methods supported by the interface.

This method registers D-Bus methods exposed by this interface. It does not support incremental registration of methods one at a time. Repeated calls will erase the previous methods before adding the new ones. The interface description should be encoded into a Lua table with the following structure:

 {
     {                      -- IntrospectItem[1]
         name = "SetPosition",
         args =
             {
                 {          -- IntrospectArg[1]
                 name = "x",
                 sig = "i",
                 dir = "in"
                 },
                 {          -- IntrospectArg[2]
                 name = "y"
                 sig = "i",
                 dir = "in"
                 },
                 ...        -- IntrospectArg[N]
              }
      },
      ...                   -- IntrospectItem[N]
  }

See IntrospectItem and IntrospectArg for the definition of the individual elements of the introspection table. Any error parsing or registering the methods will result in a Lua error being thrown.

Parameters:

  • interface userdata The Interface on which to register methods.
  • methods table The introspection data for the methods being registered with this interface.
clearMethods (interface)

Clears or erases the methods supported by the interface.

Parameters:

  • interface userdata The Interface on which to clear the methods.

Returns:

    bool Returns true if the methods are cleared successfully, false otherwise.
registerSignals (interface, signals)

Registers signal emitted by the interface.

This method registers D-Bus signals emitted by this interface. It does not support incremental registration of signals one at a time. Repeated calls will erase the previous signals before adding the new ones. The description of the signals should be encoded into a Lua table with the following structure:

 {
     {                      -- IntrospectItem[1]
         name = "PositionUpdate",
         args =
             {
                 {          -- IntrospectArg[1]
                 name = "x",
                 sig = "i",
                 },
                 {          -- IntrospectArg[2]
                 name = "y"
                 sig = "i",
                 },
                 ...        -- IntrospectArg[N]
              }
      },
      ...                   -- IntrospectItem[N]
  }

See IntrospectItem and IntrospectArg for the definition of the individual elements of the introspection table. Any error parsing or registering the signals will result in a Lua error being thrown.

Parameters:

  • interface userdata The Interface on which to register signals.
  • signals table The introspection data for the signals being registered with this interface.
clearSignals (interface)

Clears or erases the signals supported by the interface.

Parameters:

  • interface userdata The Interface on which to clear the signals.

Returns:

    bool Returns true if the signals are cleared successfully, false otherwise.
registerProperties (interface, properties)

Registers properties supported by the interface.

This method registers D-Bus properties supported by this interface. It does not support incremental registration of properties one at a time. Repeated calls will erase the previous properties before adding the new ones. The properties should be encoded into a Lua table with the following structure:

 {
     {                      --  IntrospectProp[1]
         name = "Time",
         sig = "i",
         access = "r"
     },
     {                      --  IntrospectProp[2]
         name = "Velocity",
         sig = "d",
         access = "rw"
     },
     ...                    --  IntrospectProp[N]
  }

See IntrospectProp for the definition of the individual elements of the introspective properties table. Any error parsing or registering the properties will result in a Lua error being thrown. Although these properties will appear as part of the D-Bus Introspection data if a client should introspect a service implementing this interface, it is implied that the service must also implement the Properties interface in order for the client to directly access them.

Parameters:

  • interface userdata The Interface on which to register properties.
  • properties table The introspection data for the properties being registered with this interface.
clearProperties (interface)

Clears or erases the properties supported by the interface.

Parameters:

  • interface userdata The Interface on which to clear the properties.

Returns:

    bool Returns true if the properties are cleared successfully, false otherwise.
introspect (interface)

Returns the D-Bus XML introspection data for this interface only.

This isn't usually called directly by client code but is is collected by a service implementing the Introspectable interface. See l2dbus.Introspection for more details.

Parameters:

  • interface userdata The Interface to be introspected.

Returns:

    string Returns D-Bus XML introspection data if the interface has registered methods, signals, or properties, otherwise nil.
generated by LDoc 1.3