Module org.freedesktop.dbus
Package org.freedesktop.dbus.messages

Class Message

java.lang.Object
org.freedesktop.dbus.messages.Message
Direct Known Subclasses:
DBusSignal, Error, MethodBase
public class Message extends Object
Superclass of all messages which are sent over the Bus.
This class deals with all the marshalling to/from the wire format.

  • Field Details

    • MAXIMUM_ARRAY_LENGTH

      public static final int MAXIMUM_ARRAY_LENGTH
      See Also:

    • MAXIMUM_MESSAGE_LENGTH

      public static final int MAXIMUM_MESSAGE_LENGTH
      See Also:

    • MAXIMUM_NUM_UNIX_FDS

      public static final int MAXIMUM_NUM_UNIX_FDS
      See Also:

    • PROTOCOL

      public static final byte PROTOCOL
      The current protocol major version.
      See Also:

    • DEFAULT_OPTIONS

      private static final Message.ExtractOptions DEFAULT_OPTIONS
      Default extraction options.

    • OFFSET_DATA

      private static final int OFFSET_DATA
      Position of data offset in int array.
      See Also:

    • OFFSET_SIG

      private static final int OFFSET_SIG
      Position of signature offset in int array.
      See Also:

    • padding

      private static byte[][] padding
      Keep a static reference to each size of padding array to prevent allocation.

    • BUFFERINCREMENT

      private static final int BUFFERINCREMENT
      Steps to increment the buffer array.
      See Also:

    • GLOBAL_SERIAL

      private static final AtomicLong GLOBAL_SERIAL

    • logger

      protected final org.slf4j.Logger logger

    • filedescriptors

      private final List<FileDescriptor> filedescriptors

    • headers

      private final Object[] headers

    • wiredata

      private byte[][] wiredata

    • bytecounter

      private long bytecounter

    • serial

      private long serial

    • type

      private byte type

    • flags

      private byte flags

    • protover

      private byte protover

    • big

      private boolean big

    • args

      private Object[] args

    • body

      private byte[] body

    • bodylen

      private long bodylen

    • preallocated

      private int preallocated

    • paofs

      private int paofs

    • pabuf

      private byte[] pabuf

    • bufferuse

      private int bufferuse

    • endianWasSet

      private boolean endianWasSet

  • Constructor Details

    • Message

      protected Message(byte _endian, byte _type, byte _flags) throws DBusException
      Create a message; only to be called by sub-classes.
      Parameters:
      _endian - The endianness to create the message.
      _type - The message type.
      _flags - Any message flags.
      Throws:
      DBusException - on error

    • Message

      protected Message()
      Create a blank message. Only to be used when calling populate.

  • Method Details

    • updateEndianess

      public void updateEndianess(byte _endianess)

    • populate

      void populate(byte[] _msg, byte[] _headers, byte[] _body, List<FileDescriptor> _descriptors) throws DBusException
      Create a message from wire-format data.
      Parameters:
      _msg - D-Bus serialized data of type yyyuu
      _headers - D-Bus serialized data of type a(yv)
      _body - D-Bus serialized data of the signature defined in headers.
      Throws:
      DBusException

    • getHeader

      protected Object[] getHeader()

    • setHeader

      protected void setHeader(Object[] _header)
      Set header content. null value is ignored.
      Parameters:
      _header - header to set

    • getByteCounter

      protected long getByteCounter()

    • setByteCounter

      protected void setByteCounter(long _bytecounter)

    • setSerial

      protected void setSerial(long _serial)

    • setWireData

      protected void setWireData(byte[][] _wiredata)

    • getProtover

      byte getProtover()

    • getBodylen

      long getBodylen()

    • preallocate

      private void preallocate(int _num)
      Create a buffer of num bytes. Data is copied to this rather than added to the buffer list.

    • ensureBuffers

      private void ensureBuffers(int _num)
      Ensures there are enough free buffers.
      Parameters:
      _num - number of free buffers to create.

    • appendBytes

      protected void appendBytes(byte[] _buf)
      Appends a buffer to the buffer list.
      Parameters:
      _buf - buffer byte array

    • appendByte

      protected void appendByte(byte _b)
      Appends a byte to the buffer list.
      Parameters:
      _b - byte

    • demarshallint

      protected long demarshallint(byte[] _buf, int _ofs, int _width)
      Demarshalls an integer of a given width from a buffer. Endianness is determined from the format of the message.
      Parameters:
      _buf - The buffer to demarshall from.
      _ofs - The offset to demarshall from.
      _width - The byte-width of the int.
      Returns:
      long

    • appendint

      protected void appendint(long _l, int _width)
      Marshalls an integer of a given width and appends it to the message. Endianness is determined from the message.
      Parameters:
      _l - The integer to marshall.
      _width - The byte-width of the int.

    • marshallint

      protected void marshallint(long _l, byte[] _buf, int _ofs, int _width)
      Marshalls an integer of a given width into a buffer. Endianness is determined from the message.
      Parameters:
      _l - The integer to marshall.
      _buf - The buffer to marshall to.
      _ofs - The offset to marshall to.
      _width - The byte-width of the int.

    • getWireData

      public byte[][] getWireData()

    • getFiledescriptors

      public List<FileDescriptor> getFiledescriptors()

    • toString

      public String toString()
      Formats the message in a human-readable format.
      Overrides:
      toString in class Object

    • getHeader

      protected Object getHeader(byte _type)
      Returns the value of the header field of a given field.
      Parameters:
      _type - The field to return.
      Returns:
      The value of the field or null if unset.

    • pad

      protected void pad(byte _type)
      Pad the message to the proper alignment for the given type.
      Parameters:
      _type - type

    • append

      protected void append(String _sig, Object... _data) throws DBusException
      Append a series of values to the message.
      Parameters:
      _sig - The signature(s) of the value(s).
      _data - The value(s).
      Throws:
      DBusException - on error

    • appendOne

      private int appendOne(byte[] _sigb, int _sigofs, Object _data) throws DBusException
      Appends a value to the message. The type of the value is read from a D-Bus signature and used to marshall the value.
      Parameters:
      _sigb - A buffer of the D-Bus signature.
      _sigofs - The offset into the signature corresponding to this value.
      _data - The value to marshall.
      Returns:
      The offset into the signature of the end of this value's type.
      Throws:
      DBusException

    • align

      protected int align(int _current, byte _type)
      Align a counter to the given type.
      Parameters:
      _current - The current counter.
      _type - The type to align to.
      Returns:
      The new, aligned, counter.

    • extractHeader

      Object[] extractHeader(byte[] _headers) throws DBusException
      Extracts the header information from the given byte array.
      Parameters:
      _headers - D-Bus serialized data of type a(yv)
      Returns:
      Object array containing header data
      Throws:
      DBusException - when parsing fails

    • readHeaderVariants

      private Object readHeaderVariants(byte[] _signatureBuf, byte[] _dataBuf, int[] _offsets, Message.ExtractOptions _options) throws DBusException
      Special lightweight version to read the variant objects in DBus message header. This method will not create Variant objects it directly extracts the Variant data content.
      Parameters:
      _signatureBuf - DBus signature string as byte array
      _dataBuf - buffer with header data
      _offsets - current offsets
      _options - additional options
      Returns:
      Object
      Throws:
      DBusException - when parsing fails

    • extractOne

      private Object extractOne(byte[] _signatureBuf, byte[] _dataBuf, int[] _offsets, Message.ExtractOptions _options) throws DBusException
      Demarshall one value from a buffer.
      Parameters:
      _signatureBuf - A buffer of the D-Bus signature.
      _dataBuf - The buffer to demarshall from.
      _offsets - An array of two ints, which holds the position of the current signature offset and the current offset of the data buffer.
      _options - extract options
      Returns:
      The demarshalled value.
      Throws:
      DBusException

    • extractByte

      private Object extractByte(byte[] _dataBuf, int[] _offsets)
      Extracts a byte from the data received on bus.
      Parameters:
      _dataBuf - buffer holding the byte
      _offsets - offset position in buffer (will be updated)
      Returns:
      Object

    • extractStruct

      private Object extractStruct(byte[] _signatureBuf, byte[] _dataBuf, int[] _offsets, Message.ExtractOptions _options, Message.ExtractMethod _extractMethod) throws DBusException
      Extracts a struct from the data received on bus.
      Parameters:
      _signatureBuf - signature (as byte array) defining the struct content
      _dataBuf - buffer containing the struct
      _offsets - offset position in buffer (will be updated)
      _options - extract options
      _extractMethod - method to be called for every entry contained of the struct
      Returns:
      Object
      Throws:
      DBusException - when parsing fails

    • extractArray

      private Object extractArray(byte[] _signatureBuf, byte[] _dataBuf, int[] _offsets, Message.ExtractOptions _options, Message.ExtractMethod _extractMethod) throws MarshallingException, DBusException
      Extracts an array from the data received on bus.
      Parameters:
      _signatureBuf - signature string (as byte array) of the content of the array
      _dataBuf - buffer containing the array to read
      _offsets - current offsets in the buffer (will be updated)
      _options - additional options
      _extractMethod - method to be called for every entry contained in the array
      Returns:
      Object
      Throws:
      MarshallingException - when Array is too large
      DBusException - when parsing fails

    • extractVariant

      private Object extractVariant(byte[] _dataBuf, int[] _offsets, Message.ExtractOptions _options, BiFunction<String,Object,Object> _variantFactory) throws DBusException
      Extracts a Variant from the data received on bus.
      Parameters:
      _dataBuf - buffer containing the variant
      _offsets - current offsets in the buffer (will be updated)
      _options - extract options
      _variantFactory - method to create new Variant objects (or other object types)
      Returns:
      Object / Variant
      Throws:
      DBusException - when parsing fails

    • optimizePrimitives

      private Object optimizePrimitives(byte[] _signatureBuf, byte[] _dataBuf, int[] _offsets, long _size, byte _algn, int _length, Message.ExtractOptions _options, Message.ExtractMethod _extractMethod) throws DBusException
      Will create primitive arrays when an array is read.
      In case the array is not compatible with primitives (e.g. object types are used or array contains Struct/Maps etc) an array of the appropriate type will be created.
      Parameters:
      _signatureBuf - signature string (as byte array) containing the type of array
      _dataBuf - buffer containing the array
      _offsets - current offset in buffer (will be updated)
      _size - size of a byte
      _algn - data offset padding width when reading primitives (except byte)
      _length - length of the array
      _options - extract options
      _extractMethod - method to be called for every entry contained in the array if not primitive array
      Returns:
      Object array
      Throws:
      DBusException - when parsing fails

    • prepareCollection

      private int prepareCollection(byte[] _signatureBuf, int[] _offsets, long _size) throws DBusException
      Throws:
      DBusException

    • extract

      protected Object[] extract(String _signature, byte[] _dataBuf, int _offsets, Message.ExtractOptions _options) throws DBusException
      Demarshall values from a buffer.
      Parameters:
      _signature - The D-Bus signature(s) of the value(s).
      _dataBuf - The buffer to demarshall from.
      _offsets - The offset into the data buffer to start.
      _options - additional options
      Returns:
      The demarshalled value(s).
      Throws:
      DBusException - on error

    • extract

      protected Object[] extract(String _signature, byte[] _dataBuf, int[] _offsets, Message.ExtractOptions _options) throws DBusException
      Demarshall values from a buffer.
      Parameters:
      _signature - The D-Bus signature(s) of the value(s).
      _dataBuf - The buffer to demarshall from.
      _offsets - An array of two ints, which holds the position of the current signature offset and the current offset of the data buffer. These values will be updated to the start of the next value after demarshalling.
      _options - additional options
      Returns:
      The demarshalled value(s).
      Throws:
      DBusException - on error

    • extract

      Object[] extract(String _signature, byte[] _dataBuf, int[] _offsets, Message.ExtractOptions _options, Message.ExtractMethod _method) throws DBusException
      Throws:
      DBusException

    • getSource

      public String getSource()
      Returns the Bus ID that sent the message.
      Returns:
      string

    • getDestination

      public String getDestination()
      Returns the destination of the message.
      Returns:
      string

    • getInterface

      public String getInterface()
      Returns the interface of the message.
      Returns:
      string

    • getPath

      public String getPath()
      Returns the object path of the message.
      Returns:
      string

    • getName

      public String getName()
      Returns the member name or error name this message represents.
      Returns:
      string

    • getSig

      public String getSig()
      Returns the dbus signature of the parameters.
      Returns:
      string

    • getFlags

      public int getFlags()
      Returns the message flags.
      Returns:
      int

    • getSerial

      public long getSerial()
      Returns the message serial ID (unique for this connection)
      Returns:
      the message serial.

    • getReplySerial

      public long getReplySerial()
      If this is a reply to a message, this returns its serial.
      Returns:
      The reply serial, or 0 if it is not a reply.

    • getParameters

      public Object[] getParameters() throws DBusException
      Parses and returns the parameters to this message as an Object array.
      Returns:
      object array
      Throws:
      DBusException - on failure

    • getParameters

      public Object[] getParameters(List<Type[]> _constructorArgs) throws DBusException
      Parses and returns the parameters to this message as an Object array. This method takes a list of Type[] where each entry of the list represents a constructor call. The constructor arguments are used to determine if a collection of array of primitive type should be used when calling the constructor.
      Parameters:
      _constructorArgs - list of desired constructor arguments
      Returns:
      object array
      Throws:
      DBusException - on failure

    • extractArgs

      private Object[] extractArgs(List<Type[]> _constructorArgs) throws DBusException
      Creates a object array containing all objects which should be used to call a constructor.
      Parameters:
      _constructorArgs - list of desired constructor arguments
      Returns:
      object array
      Throws:
      DBusException - on failure

    • usesPrimitives

      static List<Message.ConstructorArgType> usesPrimitives(List<Type[]> _constructorArgs, List<Type> _dataType)
      Compares a list of Type[] with a list of desired types. This is used to decide if an array of primitive types, an array of object types or a Collection/List of a object type is used in the constructor.
      Parameters:
      _constructorArgs - list of constructor types to check
      _dataType - list of desired types
      Returns:
      List of ConstructorArgType

    • setArgs

      public void setArgs(Object[] _args)

    • setSource

      public void setSource(String _source) throws DBusException
      Warning, do not use this method unless you really know what you are doing.
      Parameters:
      _source - string
      Throws:
      DBusException - on error

    • dumpWireData

      String dumpWireData()
      Dumps the current content of wiredata to String.
      Returns:
      String, maybe empty
      Since:
      v4.2.2 - 2023-01-20

    • getType

      public byte getType()
      Type of this message.
      Returns:
      byte

    • getEndianess

      public byte getEndianess()

    • createHeaderArgs

      protected Object[] createHeaderArgs(byte _header, String _argType, Object _value)
      Creates a message header. Will automatically add the values to the current instances header map.
      Parameters:
      _header - header type (one of HeaderField)
      _argType - argument type (one of ArgumentType)
      _value - value
      Returns:
      Object array

    • padAndMarshall

      protected void padAndMarshall(List<Object> _hargs, long _serial, String _sig, Object... _args) throws DBusException
      Adds message padding and marshalling.
      Parameters:
      _hargs -
      _serial -
      _sig -
      _args -
      Throws:
      DBusException

    • demarshallint

      public static long demarshallint(byte[] _buf, int _ofs, byte _endian, int _width)
      Demarshalls an integer of a given width from a buffer.
      Parameters:
      _buf - The buffer to demarshall from.
      _ofs - The offset to demarshall from.
      _endian - The endianness to use in demarshalling.
      _width - The byte-width of the int.
      Returns:
      long

    • demarshallintBig

      public static long demarshallintBig(byte[] _buf, int _ofs, int _width)
      Demarshalls an integer of a given width from a buffer using big-endian format.
      Parameters:
      _buf - The buffer to demarshall from.
      _ofs - The offset to demarshall from.
      _width - The byte-width of the int.
      Returns:
      long

    • demarshallintLittle

      public static long demarshallintLittle(byte[] _buf, int _ofs, int _width)
      Demarshalls an integer of a given width from a buffer using little-endian format.
      Parameters:
      _buf - The buffer to demarshall from.
      _ofs - The offset to demarshall from.
      _width - The byte-width of the int.
      Returns:
      long

    • marshallintBig

      public static void marshallintBig(long _l, byte[] _buf, int _ofs, int _width)
      Marshalls an integer of a given width into a buffer using big-endian format.
      Parameters:
      _l - The integer to marshall.
      _buf - The buffer to marshall to.
      _ofs - The offset to marshall to.
      _width - The byte-width of the int.

    • marshallintLittle

      public static void marshallintLittle(long _l, byte[] _buf, int _ofs, int _width)
      Marshalls an integer of a given width into a buffer using little-endian format.
      Parameters:
      _l - The integer to marshall.
      _buf - The buffer to demarshall to.
      _ofs - The offset to demarshall to.
      _width - The byte-width of the int.

    • getAlignment

      public static int getAlignment(byte _type)
      Return the alignment for a given type.
      Parameters:
      _type - type
      Returns:
      int

    • getHeaderFieldName

      public static String getHeaderFieldName(byte _field)
      Returns the name of the given header field.
      Parameters:
      _field - field
      Returns:
      string

    • cloneWithNewSerial

      Message cloneWithNewSerial()
      Creates a clone of this message and setting serial to next available.
      Returns:
      Message