Package org.gnome.gio

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("io.github.jwharm.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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DBusMessage.Builder<B extends DBusMessage.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
DBusMessage()	Creates a new DBusMessage.
DBusMessage(MemorySegment address)	Create a DBusMessage proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected DBusMessage	asParent()	Returns this instance as if it were its parent type.
static DBusMessage.Builder<? extends DBusMessage.Builder>	builder()	A DBusMessage.Builder object constructs a DBusMessage with the specified properties.
static long	bytesNeeded(@org.jspecify.annotations.Nullable byte @Nullable [] blob)	Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at blob.
DBusMessage	copy()	Copies message. The copy is a deep copy and the returned GDBusMessage is completely identical except that it is guaranteed to not be locked.
static DBusMessage	fromBlob(@org.jspecify.annotations.Nullable byte @Nullable [] blob, Set<DBusCapabilityFlags> capabilities)	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().
static DBusMessage	fromBlob(@org.jspecify.annotations.Nullable byte @Nullable [] blob, DBusCapabilityFlags... capabilities)	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().
@Nullable String	getArg0()	Convenience to get the first item in the body of message.
@Nullable String	getArg0Path()	Convenience to get the first item in the body of message.
@Nullable Variant	getBody()	Gets the body of a message.
DBusMessageByteOrder	getByteOrder()	Gets the byte order of message.
@Nullable String	getDestination()	Convenience getter for the DBusMessageHeaderField.DESTINATION header field.
@Nullable String	getErrorName()	Convenience getter for the DBusMessageHeaderField.ERROR_NAME header field.
Set<DBusMessageFlags>	getFlags()	Gets the flags for message.
@Nullable Variant	getHeader(DBusMessageHeaderField headerField)	Gets a header field on message.
byte[]	getHeaderFields()	Gets an array of all header fields on this DBusMessage that are set.
@Nullable String	getInterface()	Convenience getter for the DBusMessageHeaderField.INTERFACE header field.
boolean	getLocked()	Checks whether this DBusMessage is locked.
@Nullable String	getMember()	Convenience getter for the DBusMessageHeaderField.MEMBER header field.
DBusMessageType	getMessageType()	Gets the type of message.
int	getNumUnixFds()	Convenience getter for the DBusMessageHeaderField.NUM_UNIX_FDS header field.
@Nullable String	getPath()	Convenience getter for the DBusMessageHeaderField.PATH header field.
int	getReplySerial()	Convenience getter for the DBusMessageHeaderField.REPLY_SERIAL header field.
@Nullable String	getSender()	Convenience getter for the DBusMessageHeaderField.SENDER header field.
int	getSerial()	Gets the serial for message.
String	getSignature()	Convenience getter for the DBusMessageHeaderField.SIGNATURE header field.
static @Nullable Type	getType()	Get the GType of the DBusMessage class
@Nullable UnixFDList	getUnixFdList()	Gets the UNIX file descriptors associated with message, if any.
void	lock()	If this DBusMessage is locked, does nothing.
static DBusMessage	methodCall(@Nullable String name, String path, @Nullable String interface_, String method)	Creates a new GDBusMessage for a method call.
DBusMessage	newMethodError(String errorName, String errorMessageFormat, Object... varargs)	Creates a new GDBusMessage that is an error reply to methodCallMessage.
DBusMessage	newMethodErrorLiteral(String errorName, String errorMessage)	Creates a new GDBusMessage that is an error reply to methodCallMessage.
DBusMessage	newMethodReply()	Creates a new GDBusMessage that is a reply to methodCallMessage.
String	print(int indent)	Produces a human-readable multi-line description of message.
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).
void	setByteOrder(DBusMessageByteOrder byteOrder)	Sets the byte order of message.
void	setDestination(@Nullable String value)	Convenience setter for the DBusMessageHeaderField.DESTINATION header field.
void	setErrorName(String value)	Convenience setter for the DBusMessageHeaderField.ERROR_NAME header field.
void	setFlags(Set<DBusMessageFlags> flags)	Sets the flags to set on message.
void	setFlags(DBusMessageFlags... flags)	Sets the flags to set on message.
void	setHeader(DBusMessageHeaderField headerField, @Nullable Variant value)	Sets a header field on message.
void	setInterface(@Nullable String value)	Convenience setter for the DBusMessageHeaderField.INTERFACE header field.
void	setMember(@Nullable String value)	Convenience setter for the DBusMessageHeaderField.MEMBER header field.
void	setMessageType(DBusMessageType type)	Sets this DBusMessage to be of type.
void	setNumUnixFds(int value)	Convenience setter for the DBusMessageHeaderField.NUM_UNIX_FDS header field.
void	setPath(@Nullable String value)	Convenience setter for the DBusMessageHeaderField.PATH header field.
void	setReplySerial(int value)	Convenience setter for the DBusMessageHeaderField.REPLY_SERIAL header field.
void	setSender(@Nullable String value)	Convenience setter for the DBusMessageHeaderField.SENDER header field.
void	setSerial(int serial)	Sets the serial for message.
void	setSignature(@Nullable String value)	Convenience setter for the DBusMessageHeaderField.SIGNATURE header field.
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).
static DBusMessage	signal(String path, String interface_, String signal)	Creates a new GDBusMessage for a signal emission.
byte[]	toBlob(Set<DBusCapabilityFlags> capabilities)	Serializes this DBusMessage to a blob.
byte[]	toBlob(DBusCapabilityFlags... capabilities)	Serializes this DBusMessage to a blob.
boolean	toGerror()	If this DBusMessage is not of type DBusMessageType.ERROR does nothing and returns false.

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getMemoryLayout, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DBusMessage

public DBusMessage(MemorySegment address)

Create a DBusMessage proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

DBusMessage

public DBusMessage()

Creates a new DBusMessage.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the DBusMessage class

Returns:

the GType

asParent

protected DBusMessage asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

fromBlob

public static DBusMessage fromBlob(@org.jspecify.annotations.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(@org.jspecify.annotations.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(@org.jspecify.annotations.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(java.lang.foreign.MemorySegment).

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