Class DBusMessage

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gio.DBusMessage
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class DBusMessage extends GObject
A type for representing D-Bus messages that can be sent or received on a DBusConnection.
Since:
2.26

  • Constructor Details

    • DBusMessage

      public DBusMessage(MemorySegment address)
      Create a DBusMessage instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • DBusMessage

      public DBusMessage()
      Create a new DBusMessage.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the DBusMessage class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected DBusMessage asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GObject
      Returns:
      the instance as if it were its parent type

    • fromBlob

      public static DBusMessage fromBlob(@Nullable byte @Nullable [] blob, Set<DBusCapabilityFlags> capabilities) throws GErrorException

      Creates a new GDBusMessage from the data stored at blob. The byte order that the message was in can be retrieved using g_dbus_message_get_byte_order().

      If the blob cannot be parsed, contains invalid fields, or contains invalid headers, IOErrorEnum.INVALID_ARGUMENT will be returned.

      Parameters:
      blob - A blob representing a binary D-Bus message.
      capabilities - A GDBusCapabilityFlags describing what protocol features are supported.
      Returns:
      A new GDBusMessage or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • fromBlob

      public static DBusMessage fromBlob(@Nullable byte @Nullable [] blob, DBusCapabilityFlags... capabilities) throws GErrorException

      Creates a new GDBusMessage from the data stored at blob. The byte order that the message was in can be retrieved using g_dbus_message_get_byte_order().

      If the blob cannot be parsed, contains invalid fields, or contains invalid headers, IOErrorEnum.INVALID_ARGUMENT will be returned.

      Parameters:
      blob - A blob representing a binary D-Bus message.
      capabilities - A GDBusCapabilityFlags describing what protocol features are supported.
      Returns:
      A new GDBusMessage or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • methodCall

      public static DBusMessage methodCall(@Nullable String name, String path, @Nullable String interface_, String method)
      Creates a new GDBusMessage for a method call.
      Parameters:
      name - A valid D-Bus name or null.
      path - A valid object path.
      interface_ - A valid D-Bus interface name or null.
      method - A valid method name.
      Returns:
      A GDBusMessage. Free with g_object_unref().
      Since:
      2.26

    • signal

      public static DBusMessage signal(String path, String interface_, String signal)
      Creates a new GDBusMessage for a signal emission.
      Parameters:
      path - A valid object path.
      interface_ - A valid D-Bus interface name.
      signal - A valid signal name.
      Returns:
      A GDBusMessage. Free with g_object_unref().
      Since:
      2.26

    • bytesNeeded

      public static long bytesNeeded(@Nullable byte @Nullable [] blob) throws GErrorException
      Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at blob.
      Parameters:
      blob - A blob representing a binary D-Bus message.
      Returns:
      Number of bytes needed or -1 if error is set (e.g. if blob contains invalid data or not enough data is available to determine the size).
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • copy

      public DBusMessage copy() throws GErrorException

      Copies message. The copy is a deep copy and the returned GDBusMessage is completely identical except that it is guaranteed to not be locked.

      This operation can fail if e.g. this DBusMessage contains file descriptors and the per-process or system-wide open files limit is reached.

      Returns:
      A new GDBusMessage or null if error is set. Free with g_object_unref().
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • getArg0

      public @Nullable String getArg0()

      Convenience to get the first item in the body of message.

      See getArg0Path() for returning object-path-typed arg0 values.

      Returns:
      The string item or null if the first item in the body of this DBusMessage is not a string.
      Since:
      2.26

    • getArg0Path

      public @Nullable String getArg0Path()

      Convenience to get the first item in the body of message.

      See getArg0() for returning string-typed arg0 values.

      Returns:
      The object path item or NULL if the first item in the body of this DBusMessage is not an object path.
      Since:
      2.80

    • getBody

      public @Nullable Variant getBody()
      Gets the body of a message.
      Returns:
      A GVariant or null if the body is empty. Do not free, it is owned by message.
      Since:
      2.26

    • getByteOrder

      public DBusMessageByteOrder getByteOrder()
      Gets the byte order of message.
      Returns:
      The byte order.

    • getDestination

      public @Nullable String getDestination()
      Convenience getter for the DBusMessageHeaderField.DESTINATION header field.
      Returns:
      The value.
      Since:
      2.26

    • getErrorName

      public @Nullable String getErrorName()
      Convenience getter for the DBusMessageHeaderField.ERROR_NAME header field.
      Returns:
      The value.
      Since:
      2.26

    • getFlags

      public Set<DBusMessageFlags> getFlags()
      Gets the flags for message.
      Returns:
      Flags that are set (typically values from the GDBusMessageFlags enumeration bitwise ORed together).
      Since:
      2.26

    • getHeader

      public @Nullable Variant getHeader(DBusMessageHeaderField headerField)

      Gets a header field on message.

      The caller is responsible for checking the type of the returned GVariant matches what is expected.

      Parameters:
      headerField - A 8-bit unsigned integer (typically a value from the GDBusMessageHeaderField enumeration)
      Returns:
      A GVariant with the value if the header was found, null otherwise. Do not free, it is owned by message.
      Since:
      2.26

    • getHeaderFields

      public byte[] getHeaderFields()
      Gets an array of all header fields on this DBusMessage that are set.
      Returns:
      An array of header fields terminated by DBusMessageHeaderField.INVALID. Each element is a guchar. Free with g_free().
      Since:
      2.26

    • getInterface

      public @Nullable String getInterface()
      Convenience getter for the DBusMessageHeaderField.INTERFACE header field.
      Returns:
      The value.
      Since:
      2.26

    • getLocked

      public boolean getLocked()
      Checks whether this DBusMessage is locked. To monitor changes to this value, connect to the GObject::notify signal to listen for changes on the GDBusMessage:locked property.
      Returns:
      true if this DBusMessage is locked, false otherwise.
      Since:
      2.26

    • getMember

      public @Nullable String getMember()
      Convenience getter for the DBusMessageHeaderField.MEMBER header field.
      Returns:
      The value.
      Since:
      2.26

    • getMessageType

      public DBusMessageType getMessageType()
      Gets the type of message.
      Returns:
      A 8-bit unsigned integer (typically a value from the GDBusMessageType enumeration).
      Since:
      2.26

    • getNumUnixFds

      public int getNumUnixFds()
      Convenience getter for the DBusMessageHeaderField.NUM_UNIX_FDS header field.
      Returns:
      The value.
      Since:
      2.26

    • getPath

      public @Nullable String getPath()
      Convenience getter for the DBusMessageHeaderField.PATH header field.
      Returns:
      The value.
      Since:
      2.26

    • getReplySerial

      public int getReplySerial()
      Convenience getter for the DBusMessageHeaderField.REPLY_SERIAL header field.
      Returns:
      The value.
      Since:
      2.26

    • getSender

      public @Nullable String getSender()
      Convenience getter for the DBusMessageHeaderField.SENDER header field.
      Returns:
      The value.
      Since:
      2.26

    • getSerial

      public int getSerial()
      Gets the serial for message.
      Returns:
      A guint32.
      Since:
      2.26

    • getSignature

      public String getSignature()

      Convenience getter for the DBusMessageHeaderField.SIGNATURE header field.

      This will always be non-null, but may be an empty string.

      Returns:
      The value.
      Since:
      2.26

    • getUnixFdList

      public @Nullable UnixFDList getUnixFdList()

      Gets the UNIX file descriptors associated with message, if any.

      This method is only available on UNIX.

      The file descriptors normally correspond to G_VARIANT_TYPE_HANDLE values in the body of the message. For example, if g_variant_get_handle() returns 5, that is intended to be a reference to the file descriptor that can be accessed by g_unix_fd_list_get (list, 5, ...).

      Returns:
      A GUnixFDList or null if no file descriptors are associated. Do not free, this object is owned by message.
      Since:
      2.26

    • lock

      public void lock()
      If this DBusMessage is locked, does nothing. Otherwise locks the message.
      Since:
      2.26

    • newMethodError

      public DBusMessage newMethodError(String errorName, String errorMessageFormat, Object... varargs)
      Creates a new GDBusMessage that is an error reply to methodCallMessage.
      Parameters:
      errorName - A valid D-Bus error name.
      errorMessageFormat - The D-Bus error message in a printf() format.
      varargs - Arguments for errorMessageFormat.
      Returns:
      A GDBusMessage. Free with g_object_unref().
      Since:
      2.26

    • newMethodErrorLiteral

      public DBusMessage newMethodErrorLiteral(String errorName, String errorMessage)
      Creates a new GDBusMessage that is an error reply to methodCallMessage.
      Parameters:
      errorName - A valid D-Bus error name.
      errorMessage - The D-Bus error message.
      Returns:
      A GDBusMessage. Free with g_object_unref().
      Since:
      2.26

    • newMethodReply

      public DBusMessage newMethodReply()
      Creates a new GDBusMessage that is a reply to methodCallMessage.
      Returns:
      GDBusMessage. Free with g_object_unref().
      Since:
      2.26

    • print

      public String print(int indent)

      Produces a human-readable multi-line description of message.

      The contents of the description has no ABI guarantees, the contents and formatting is subject to change at any time. Typical output looks something like this:

      Flags:   none
Version: 0
Serial:  4
Headers:
  path -> objectpath '/org/gtk/GDBus/TestObject'
  interface -> 'org.gtk.GDBus.TestInterface'
  member -> 'GimmeStdout'
  destination -> ':1.146'
Body: ()
UNIX File Descriptors:
  (none)

      or

      Flags:   no-reply-expected
Version: 0
Serial:  477
Headers:
  reply-serial -> uint32 4
  destination -> ':1.159'
  sender -> ':1.146'
  num-unix-fds -> uint32 1
Body: ()
UNIX File Descriptors:
  fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
      Parameters:
      indent - Indentation level.
      Returns:
      A string that should be freed with GLib#free.
      Since:
      2.26

    • setBody

      public void setBody(Variant body)

      Sets the body message. As a side-effect the DBusMessageHeaderField.SIGNATURE header field is set to the type string of body (or cleared if body is null).

      If body is floating, this DBusMessage assumes ownership of body.

      Parameters:
      body - Either null or a GVariant that is a tuple.
      Since:
      2.26

    • setByteOrder

      public void setByteOrder(DBusMessageByteOrder byteOrder)
      Sets the byte order of message.
      Parameters:
      byteOrder - The byte order.

    • setDestination

      public void setDestination(@Nullable String value)
      Convenience setter for the DBusMessageHeaderField.DESTINATION header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setErrorName

      public void setErrorName(String value)
      Convenience setter for the DBusMessageHeaderField.ERROR_NAME header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setFlags

      public void setFlags(Set<DBusMessageFlags> flags)
      Sets the flags to set on message.
      Parameters:
      flags - Flags for this DBusMessage that are set (typically values from the GDBusMessageFlags enumeration bitwise ORed together).
      Since:
      2.26

    • setFlags

      public void setFlags(DBusMessageFlags... flags)
      Sets the flags to set on message.
      Parameters:
      flags - Flags for this DBusMessage that are set (typically values from the GDBusMessageFlags enumeration bitwise ORed together).
      Since:
      2.26

    • setHeader

      public void setHeader(DBusMessageHeaderField headerField, @Nullable Variant value)

      Sets a header field on message.

      If value is floating, this DBusMessage assumes ownership of value.

      Parameters:
      headerField - A 8-bit unsigned integer (typically a value from the GDBusMessageHeaderField enumeration)
      value - A GVariant to set the header field or null to clear the header field.
      Since:
      2.26

    • setInterface

      public void setInterface(@Nullable String value)
      Convenience setter for the DBusMessageHeaderField.INTERFACE header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setMember

      public void setMember(@Nullable String value)
      Convenience setter for the DBusMessageHeaderField.MEMBER header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setMessageType

      public void setMessageType(DBusMessageType type)
      Sets this DBusMessage to be of type.
      Parameters:
      type - A 8-bit unsigned integer (typically a value from the GDBusMessageType enumeration).
      Since:
      2.26

    • setNumUnixFds

      public void setNumUnixFds(int value)
      Convenience setter for the DBusMessageHeaderField.NUM_UNIX_FDS header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setPath

      public void setPath(@Nullable String value)
      Convenience setter for the DBusMessageHeaderField.PATH header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setReplySerial

      public void setReplySerial(int value)
      Convenience setter for the DBusMessageHeaderField.REPLY_SERIAL header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setSender

      public void setSender(@Nullable String value)
      Convenience setter for the DBusMessageHeaderField.SENDER header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setSerial

      public void setSerial(int serial)

      Sets the serial for message.

      The D-Bus specification does not allow the serial to be zero.

      Parameters:
      serial - A guint32, which must not be zero.
      Since:
      2.26

    • setSignature

      public void setSignature(@Nullable String value)
      Convenience setter for the DBusMessageHeaderField.SIGNATURE header field.
      Parameters:
      value - The value to set.
      Since:
      2.26

    • setUnixFdList

      public void setUnixFdList(@Nullable UnixFDList fdList)

      Sets the UNIX file descriptors associated with message. As a side-effect the DBusMessageHeaderField.NUM_UNIX_FDS header field is set to the number of fds in fdList (or cleared if fdList is null).

      This method is only available on UNIX.

      When designing D-Bus APIs that are intended to be interoperable, please note that non-GDBus implementations of D-Bus can usually only access file descriptors if they are referenced by a value of type G_VARIANT_TYPE_HANDLE in the body of the message.

      Parameters:
      fdList - A GUnixFDList or null.
      Since:
      2.26

    • toBlob

      public byte[] toBlob(Set<DBusCapabilityFlags> capabilities) throws GErrorException
      Serializes this DBusMessage to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used.
      Parameters:
      capabilities - A GDBusCapabilityFlags describing what protocol features are supported.
      Returns:
      A pointer to a valid binary D-Bus message of outSize bytes generated by this DBusMessage or null if error is set. Free with g_free().
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • toBlob

      public byte[] toBlob(DBusCapabilityFlags... capabilities) throws GErrorException
      Serializes this DBusMessage to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used.
      Parameters:
      capabilities - A GDBusCapabilityFlags describing what protocol features are supported.
      Returns:
      A pointer to a valid binary D-Bus message of outSize bytes generated by this DBusMessage or null if error is set. Free with g_free().
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • toGerror

      public boolean toGerror() throws GErrorException

      If this DBusMessage is not of type DBusMessageType.ERROR does nothing and returns false.

      Otherwise this method encodes the error in this DBusMessage as a GError using g_dbus_error_set_dbus_error() using the information in the DBusMessageHeaderField.ERROR_NAME header field of this DBusMessage as well as the first string item in message's body.

      Returns:
      true if error was set, false otherwise.
      Throws:
      GErrorException - see GError
      Since:
      2.26

    • builder

      public static DBusMessage.Builder<? extends DBusMessage.Builder> builder()
      A DBusMessage.Builder object constructs a DBusMessage with the specified properties. Use the various set...() methods to set properties, and finish construction with DBusMessage.Builder.build().
      Returns:
      the builder object