Namespace l2dbus.Message

L2DBUS Message

This section describes the Message class which is used to encapsulate D-Bus messages in Lua.

Functions

new (msgType)
newMethodCall (destination, path, interface, member)
newMethodReturn (callMsg)
newSignal (path, interface, name)
newError (callMsg, errName, errMsg)
copy (origMsg)
msgTypeToString (msgType)
unmarshallToMessage (msgBuf)
validateSignature (signature)

Tables

MethodCallInitializer A D-Bus method call message "initializer" table.
SignalInitializer A D-Bus signal message "initializer" table.

Message Types

INVALID
METHOD_CALL
METHOD_RETURN
ERROR
SIGNAL

l2dbus.Message

getType (msg)
setNoReply (msg, flag)
getNoReply (msg)
setAutoStart (msg, flag)
getAutoStart (msg)
setObjectPath (msg, path)
getObjectPath (msg)
hasObjectPath (msg, path)
getDecomposedObjectPath (msg)
setInterface (msg, interface)
getInterface (msg)
hasInterface (msg, interface)
setMember (msg, name)
getMember (msg)
hasMember (msg, member)
setErrorName (msg, name)
getErrorName (msg)
setDestination (msg, name)
getDestination (msg)
hasDestination (msg, destination)
setSender (msg, name)
getSender (msg)
hasSender (msg, sender)
getSignature (msg)
hasSignature (msg, signature)
containsUnixFds (msg)
setSerial (msg, serialNum)
getSerial (msg)
addArgs (msg, ...)
addArgsBySignature (msg, signature, ...)
getArgs (msg)
getArgsAsArray (msg)
marshallToArray (msg)
dispose (msg)


Functions

new (msgType)

Creates a new D-Bus Message of the specified type.

Constructs one of the following types of new D-Bus messages:

The constructed message is initially empty (e.g. there are no arguments or parameters assigned to it).

Parameters:

Returns:

    userdata Message userdata object
newMethodCall (destination, path, interface, member)

Creates a new D-Bus method call Message.

Constructs a D-Bus method call message either using an initialization table or a parameter list. The destination may be nil in which no destination is set which is appropriate when using D-Bus in a peer-to-peer context (e.g. no message bus). The interface may be nil which means it remains undefined which object receives the message if more than one interface defines the same member name.

Parameters:

  • destination string or table The bus name that the message should be sent to or a MethodCallInitializer table containing all the method call parameters. If a table is specified then the parameters following the table are ignored. The destination is a optional parameter and may be set to nil.
  • path string The D-Bus object path the message should be sent to. Ignored if the first parameter is a table.
  • interface string or nil The interface to invoke the method on. Ignored if the first parameter is a table. The interface is optional and may be set to nil.
  • member string The member name to call.

Returns:

    userdata Message userdata object for a message call.
newMethodReturn (callMsg)

Creates a new D-Bus method return Message.

Constructs a D-Bus method return message based on a method call message.

Parameters:

  • callMsg userdata The D-Bus call message on which to form the D-Bus return message.

Returns:

    userdata Message userdata object for a return message.
newSignal (path, interface, name)

Creates a new D-Bus signal message.

Constructs a D-Bus signal message either using an initializer table or parameter list.

Parameters:

  • path string The path to the object emitting the signalor a SignalInitializer table containing all the signal parameters. If a table is specified then the parameters following the table are ignored.
  • interface string or nil The interface the signal is emitted from. Ignored if the first parameter is a table.
  • name string or nil The signal name. Ignored if the first parameter is a table.

Returns:

    userdata Message userdata object for a signal.
newError (callMsg, errName, errMsg)

Creates a new D-Bus error message based on a request message.

Parameters:

  • callMsg userdata The D-Bus call message on which to base the D-Bus error message.
  • errName string The error name for the message. It must be a valid name according to the syntax given in the D-Bus specification.
  • errMsg string or nil The error message or nil if there is not one.

Returns:

    userdata Message userdata object for a error message.
copy (origMsg)

Creates a new D-Bus message based on an existing instance.

Creates a new message that is an exact replica of the message specified except that its serial number is reset to 0 and if the original message was "locked" (in the outgoing message queue and thus not modifiable) the new message will be unlocked.

Parameters:

  • origMsg userdata The original D-Bus message to copy.

Returns:

    userdata Message userdata object for the new copy.
msgTypeToString (msgType)

Converts the D-Bus message type into a machine-readable string.

Parameters:

  • msgType number The D-Bus message type.

Returns:

    string The machine-readable message type string.
unmarshallToMessage (msgBuf)

Unmarshalls a binary array into a D-Bus message.

This method takes an array of numbers representing the binary representation of a D-Bus message and turns it into a new message. This is the opposite operation performed by marshallToArray.

Parameters:

  • msgBuf array Array of numbers containing the binary representation of the message.

Returns:

    userdata A D-Bus message created from the binary representation.
validateSignature (signature)

Check a type signature for validity.

This function checks the validity of the type signature against the D-Bus specification.

Parameters:

  • signature string The signature to validate.

Returns:

  1. bool Returns true if the signature is valid, false otherwise.
  2. string or nil An error message if there signature is invalid, nil otherwise.

Tables

MethodCallInitializer
A D-Bus method call message "initializer" table.

This table can be used in lieu of a parameter list to initialize a new D-Bus method call message.

Fields:

  • method (string) [Req] The method name to call.
  • interface (string) [Opt] The interface to invoke the method on.
  • path (string) [Req] The D-Bus object path the message should be sent to.
  • destination (string) [Opt] The bus name that the message should be sent to.

see also:

SignalInitializer
A D-Bus signal message "initializer" table.

This table can be used in lieu of a parameter list to initialize a new D-Bus signal message.

Fields:

  • name (string) [Req] The name of the signal.
  • interface (string) [Req] The interface the signal is emitted from.
  • path (string) [Req] The path to the object emitting the signal.

see also:

Message Types

INVALID
This value is never a valid message type. Equivalent to l2dbus.Dbus.MESSAGE_TYPE_INVALID.
METHOD_CALL
Message type of a method call. Equivalent to l2dbus.Dbus.MESSAGE_TYPE_METHOD_CALL.
METHOD_RETURN
Message type of a method return. Equivalent to l2dbus.Dbus.MESSAGE_TYPE_METHOD_RETURN.
ERROR
Message type of an error. Equivalent to l2dbus.Dbus.MESSAGE_TYPE_ERROR.
SIGNAL
Message type of a signal. Equivalent to l2dbus.Dbus.MESSAGE_TYPE_SIGNAL.

l2dbus.Message

getType (msg)

Gets the type of the message.

The valid types include MESSAGE_TYPE_METHOD_CALL, MESSAGE_TYPE_METHOD_RETURN, MESSAGE_TYPE_SIGNAL, and MESSAGE_TYPE_ERROR. Other types are allowed and all code must silently ignore messages of unknown type. The MESSAGE_TYPE_INVALID type will never be returned.

Parameters:

  • msg userdata The D-Bus message to get the type.

Returns:

    number The D-Bus message type constant.
setNoReply (msg, flag)

Sets flag indicating the message does not want a reply.

This method sets a flag in the message that indicates that it does not want a reply. If this flag is set the other end of the connection may (e.g. is not required to) optimize by not sending method return or error replies.

If this flag is set then there is no way to know if the message successfully arrived at the remote end. The reply message is used to indicate a message has been received. By default a new message has this flag set to false so the far-end is required to reply.

Parameters:

  • msg userdata The D-Bus message to set the flag.
  • flag bool Set to true to indicate not reply is necessary. Set to false to indicate a reply is needed.
getNoReply (msg)

Determines if a reply message is needed.

Returns true if the message does not expect a reply.

Parameters:

  • msg userdata The D-Bus message to get the flag status.

Returns:

    bool Returns true if the message does not expect a reply or false if a reply is expected.
setAutoStart (msg, flag)

Sets flag indicating that the owner for the destination name will be automatically started before the message is delivered.

When this flag is set the message is held until a name owner finishes starting up or fails. If it fails then the reply will be an error message. By default new messages have this set to true so that auto-starting is the default.

Parameters:

  • msg userdata The D-Bus message on which the flag will be set.
  • flag bool Set to true to indicate auto-start is enabled or false otherwise.
getAutoStart (msg)

Returns true if the provided message will cause the recipient of the message (e.g. the destination name) to be auto-started. Otherwise false is returned and the destination is not auto-started.

Parameters:

  • msg userdata The D-Bus message on which to retrieve the flag.

Returns:

    bool Returns true to indicate auto-start is enabled or false otherwise.
setObjectPath (msg, path)

Sets the object path the message is being sent to (for a MESSAGE_TYPE_METHOD_CALL) or the one the signal is being emitted from (for MESSAGE_TYPE_SIGNAL)

The path must be a valid D-Bus object path.

Parameters:

  • msg userdata The D-Bus message to set the path.
  • path string or nil The path to set. Can be nil to unset the path.
getObjectPath (msg)

Gets the object path this message is being sent to (for a MESSAGE_TYPE_METHOD_CALL) or the path the signal is being emitted from (for MESSAGE_TYPE_SIGNAL)

The path must be a valid D-Bus object path.

Parameters:

  • msg userdata The D-Bus message to get the path.

Returns:

    string or nil The path or nil if it's not set.
hasObjectPath (msg, path)

Checks to see if the message has the specified object path.

The provided path must be a valid D-Bus object path.

Parameters:

  • msg userdata The D-Bus message to check the object path.
  • path string The object path to compare.

Returns:

    bool Returns true if the paths match, false otherwise.
getDecomposedObjectPath (msg)

Gets the decomposed object path this message is being sent to (for a MESSAGE_TYPE_METHOD_CALL) or the decomposed path the signal is being emitted from (for MESSAGE_TYPE_SIGNAL).

The decomposed form is defined as one array element per path component. An empty but non-NULL path means the "/" path. So the path "/foo/bar" becomes {"foo", "bar"} and the path "/" becomes an empty table {}.

Parameters:

  • msg userdata The D-Bus message to get the path.

Returns:

    table A Lua table/array containing the decomposed path as elements of the array.
setInterface (msg, interface)

Sets the interface this message is being sent to (for a MESSAGE_TYPE_METHOD_CALL) or the interface the signal is being emitted from (for MESSAGE_TYPE_SIGNAL).

The interface name must contain only valid characters from the D-Bus specification.

Parameters:

  • msg userdata The D-Bus message to set the interface.
  • interface string or nil The D-Bus interface name or nil if the interface is to be unset.
getInterface (msg)

Gets the interface this message is being sent to (for a MESSAGE_TYPE_METHOD_CALL) or the interface the signal is being emitted from (for MESSAGE_TYPE_SIGNAL).

Parameters:

  • msg userdata The D-Bus message to get the interface.

Returns:

    string or nil The D-Bus interface name or nil if unset.
hasInterface (msg, interface)

Checks to see if the message has a matching interface.

Parameters:

  • msg userdata The D-Bus message to compare with the interface.
  • interface string The interface name.

Returns:

    bool Returns true if the interface field in the message header matches, false otherwise.
setMember (msg, name)

Sets the interface member this being invoked (for a MESSAGE_TYPE_METHOD_CALL) or the member name for the signal being emitted (for MESSAGE_TYPE_SIGNAL).

The member name must contain only valid characters from the D-Bus specification.

Parameters:

  • msg userdata The D-Bus message to set the member name.
  • name string or nil The D-Bus member name or nil if the name is to be unset.
getMember (msg)

Gets the interface member being invoked (for a MESSAGE_TYPE_METHOD_CALL) or emitted (for MESSAGE_TYPE_SIGNAL).

Parameters:

  • msg userdata The D-Bus message to get the member name.

Returns:

    string or nil The D-Bus member name or nil if unset.
hasMember (msg, member)

Checks to see if the message has a matching interface member.

Parameters:

  • msg userdata The D-Bus message to compare with the interface member.
  • member string The member name to compare.

Returns:

    bool Returns true if the member field in the message header matches, false otherwise.
setErrorName (msg, name)

Sets the name of the error message.

The error name must be fully qualified according the the D-Bus specification.

Parameters:

  • msg userdata The D-Bus error message to set the name.
  • name string or nil The error name or nil to unset this field.
getErrorName (msg)

Gets the error name for messages of type MESSAGE_TYPE_ERROR).

Parameters:

  • msg userdata The D-Bus error message to get the error name.

Returns:

    string or nil The D-Bus error name or nil if unset.
setDestination (msg, name)

Sets the message's destination.

The destination is the name of another connection on the bus and may specify either the well-known name or the unique name assigned by the bus. The destination name must be fully qualified according the the D-Bus specification.

Parameters:

  • msg userdata The D-Bus message to set the destination.
  • name string or nil The destination or nil to unset this field.
getDestination (msg)

Gets the destination of a message.

Parameters:

  • msg userdata The D-Bus message to get the destination.

Returns:

    string or nil The D-Bus destination or nil if unset.
hasDestination (msg, destination)

Checks to see if the message has a matching destination.

If the message has no destination specified or has a different destination then false is returned, otherwise true.

Parameters:

  • msg userdata The D-Bus message to compare with the destination.
  • destination string The destination to compare.

Returns:

    bool Returns true if the destination in the message header matches, false otherwise.
setSender (msg, name)

Sets the message sender.

The sender name must be fully qualified according the the D-Bus specification.

Note: You usually don't want to call this method unless you're implementing a message bus daemon since that is typically one function of the daemon.

Parameters:

  • msg userdata The D-Bus message to set sender.
  • name string or nil The sender or nil to unset this field.
getSender (msg)

Gets the unique name of the connection which originated this message or nil if unknown or inapplicable.

The sender is typically filled in by the message bus. The sender will always be the unique bus name and not one of the (potentially multiple) well-known names a connection may own.

Parameters:

  • msg userdata The D-Bus message to get the sender.

Returns:

    string or nil The unique D-Bus sender or nil if unset.
hasSender (msg, sender)

Checks to see if the message has the given unique name as its sender.

If the message has no sender specified or has a different sender then false is returned. Messages from the message bus itself will have SERVICE_DBUS as the sender.

Note: A peer application will always have the unique name of the connection as the sender and not the a sender's well-known name.

Parameters:

  • msg userdata The D-Bus message to compare with the sender name.
  • sender string The sender name to compare.

Returns:

    bool Returns true if the sender in the message header matches, false otherwise.
getSignature (msg)

Gets the type signature of the message.

The type signature are the arguments in the message payload. The payload only includes the in arguments for MESSAGE_TYPE_METHOD_CALL messages and only out arguments for MESSAGE_TYPE_METHOD_RETURN messages. Therefore the result is not the complete signature of the entire C++ style method.

Parameters:

  • msg userdata The D-Bus message to get the signature.

Returns:

    string or nil The D-Bus signature in terms of type codes or nil if unset.
hasSignature (msg, signature)

Checks to see if the message has the given signature.

Parameters:

  • msg userdata The D-Bus message to compare with the signature.
  • signature string The signature to compare.

Returns:

    bool Returns true if the signature matches, false otherwise.
containsUnixFds (msg)

Checks to see if the message contains Unix file descriptors (fds).

Parameters:

  • msg userdata The D-Bus message to check for Unix file descriptors.

Returns:

    bool Returns true if the message contains Unix file descriptors, false otherwise.
setSerial (msg, serialNum)

Sets the message serial number.

The serial number can only be done once for a message.

Note: The underlying Connection will automatically set the serial to an appropriate value when it is enqueued to be sent. This function typically only needs to be used in situations where the message is being encapsulated in another protocol or it's being sent via a mechanism outside of the standard Connection methods.

Parameters:

  • msg userdata The D-Bus message to set the serial number.
  • serialNum number The integral serial number to set.
getSerial (msg)

Returns the serial number of the message or zero (0) if none has been set.

The message's serial number is provided by the application sending the message and is used to identify replies to the message. All messages received on a connection will have a serial provided by the remote application.

Parameters:

  • msg userdata The D-Bus message to get the serial number.

Returns:

    number The serial number of the message.
addArgs (msg, ...)

Append Lua arguments to a D-Bus message.

The Lua arguments are converted to their equivalent D-Bus types before encoding them into the message using a set of heuristics. A Lua error is generated if any errors are detected during the encoding process.

Parameters:

  • msg userdata D-Bus message to append arguments to.
  • ... args Lua arguments to append to the message.
addArgsBySignature (msg, signature, ...)

Append Lua arguments to a D-Bus message using signature.

The Lua arguments are converted to their equivalent D-Bus types using the provide D-Bus signature. The signature is used as guide so that the conversions are explicit. If an error is encountered in the conversion process a Lua error is thrown. The provided signature must be a valid message signature.

Parameters:

  • msg userdata D-Bus message to append arguments to.
  • signature string The valid D-Bus signature for the arguments.
  • ... args Lua arguments to append to the message.
getArgs (msg)

Retrieve the arguments from the D-Bus message.

This method unmarshalls the arguments from the D-Bus message converting them to equivalent Lua types. The arguments are passed back as multiple return values. If there is an error then a Lua error is thrown.

Parameters:

  • msg userdata D-Bus message to extract arguments.

Returns:

    ... Lua arguments passed out as multiple return values.
getArgsAsArray (msg)

Retrieve the arguments from the D-Bus message and return as an array.

This method unmarshalls the arguments from the D-Bus message converting them to equivalent Lua types. The arguments are returned in a Lua table treated as an array. The arguments are ordered arg[1..N] in the array. If there is an error then a Lua error is thrown.

Parameters:

  • msg userdata D-Bus message to extract arguments.

Returns:

    array Lua arguments returned in an array.
marshallToArray (msg)

Marshall the D-Bus message data to a byte array.

This method marshalls the contents of the D-Bus message into a Lua array of numbers (bytes). The array represents a binary representation of the D-Bus message.

Parameters:

  • msg userdata D-Bus message to extract binary data.

Returns:

    array Array of numbers containing the binary representation of the message.
dispose (msg)

Unreferences the underlying (wrapped) D-Bus message.

This function unreferences the D-Bus message that is wrapped by the Lua userdata object. Unreferencing the message likely means that at the D-Bus level the message is destroyed. The advantage of explicitly unreferencing a message is that it deterministically destroys the underlying D-Bus message rather than waiting for the Lua garbage collector to destroy it. Since the Lua garbage collector may run infrequently there is always the chance that numerous unreferenced Lua D-Bus messages may exist and consume valuable system resources. This call can free the D-Bus message resource at the expense that the (likely smaller) Lua D-Bus message userdata remains unclaimed until the Lua garbage collector runs and unreferences the message userdata.

Note: Once the dispose method is called on the Lua D-Bus message then attempts to call additional methods will fail and generate a Lua error to indicate the underlying D-Bus message no longer is referenced. In other words, do not do this unless you want an error. Once a message is disposed then the only safe action is for the Lua garbage collector to reclaim it. This can be accelerated by not holding any strong references to the Lua D-Bus message in question.

Parameters:

  • msg userdata The Lua D-Bus message to dispose.
generated by LDoc 1.3