Package org.gnome.gio

Class DBusMethodInvocation

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.DBusMethodInvocation

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class DBusMethodInvocation
extends GObject

Instances of the GDBusMethodInvocation class are used when handling D-Bus method calls. It provides a way to asynchronously return results and errors.

The normal way to obtain a GDBusMethodInvocation object is to receive it as an argument to the handle_method_call() function in a Gio.DBusInterfaceVTable that was passed to DBusConnection.registerObject(java.lang.String, org.gnome.gio.DBusInterfaceInfo, org.gnome.gio.DBusInterfaceVTable, java.lang.foreign.MemorySegment).

Since:

2.26

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DBusMethodInvocation.Builder<B extends DBusMethodInvocation.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
DBusMethodInvocation()	Creates a new DBusMethodInvocation.
DBusMethodInvocation(MemorySegment address)	Create a DBusMethodInvocation proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected DBusMethodInvocation	asParent()	Returns this instance as if it were its parent type.
static DBusMethodInvocation.Builder<? extends DBusMethodInvocation.Builder>	builder()	A DBusMethodInvocation.Builder object constructs a DBusMethodInvocation with the specified properties.
DBusConnection	getConnection()	Gets the GDBusConnection the method was invoked on.
@Nullable String	getInterfaceName()	Gets the name of the D-Bus interface the method was invoked on.
DBusMessage	getMessage()	Gets the GDBusMessage for the method invocation.
@Nullable DBusMethodInfo	getMethodInfo()	Gets information about the method call, if any.
String	getMethodName()	Gets the name of the method that was invoked.
String	getObjectPath()	Gets the object path the method was invoked on.
Variant	getParameters()	Gets the parameters of the method invocation.
@Nullable DBusPropertyInfo	getPropertyInfo()	Gets information about the property that this method call is for, if any.
@Nullable String	getSender()	Gets the bus name that invoked the method.
static @Nullable Type	getType()	Get the GType of the DBusMethodInvocation class
@Nullable MemorySegment	getUserData()	Gets the userData gpointer passed to g_dbus_connection_register_object().
void	returnDbusError(String errorName, String errorMessage)	Finishes handling a D-Bus method call by returning an error.
void	returnError(Quark domain, int code, String format, Object... varargs)	Finishes handling a D-Bus method call by returning an error.
void	returnErrorLiteral(Quark domain, int code, String message)	Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
void	returnGerror(GError error)	Like g_dbus_method_invocation_return_error() but takes a GError instead of the error domain, error code and message.
void	returnValue(@Nullable Variant parameters)	Finishes handling a D-Bus method call by returning parameters. If the parameters GVariant is floating, it is consumed.
void	returnValueWithUnixFdList(@Nullable Variant parameters, @Nullable UnixFDList fdList)	Like g_dbus_method_invocation_return_value() but also takes a GUnixFDList.
void	takeError(GError error)	Like g_dbus_method_invocation_return_gerror() but takes ownership of error so the caller does not need to free it.

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

DBusMethodInvocation

public DBusMethodInvocation(MemorySegment address)

Create a DBusMethodInvocation proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

DBusMethodInvocation

public DBusMethodInvocation()

Creates a new DBusMethodInvocation.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the DBusMethodInvocation class

Returns:

the GType

asParent

protected DBusMethodInvocation 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

getConnection

public DBusConnection getConnection()

Gets the GDBusConnection the method was invoked on.

Returns:

A GDBusConnection. Do not free, it is owned by invocation.

Since:

2.26

getInterfaceName

public @Nullable String getInterfaceName()

Gets the name of the D-Bus interface the method was invoked on.

This can be NULL if it was not specified by the sender. See Gio.DBusInterfaceMethodCallFunc or the D-Bus Specification for details on when this can happen and how it should be handled.

If this method call is a property Get, Set or GetAll call that has been redirected to the method call handler then "org.freedesktop.DBus.Properties" will be returned. See GDBusInterfaceVTable for more information.

Returns:

A string. Do not free, it is owned by invocation.

Since:

2.26

getMessage

public DBusMessage getMessage()

Gets the GDBusMessage for the method invocation. This is useful if you need to use low-level protocol features, such as UNIX file descriptor passing, that cannot be properly expressed in the GVariant API.

See this Gio.DBusConnection#an-example-d-bus-server and Gio.DBusConnection#an-example-for-file-descriptor-passing for an example of how to use this low-level API to send and receive UNIX file descriptors.

Returns:

GDBusMessage. Do not free, it is owned by invocation.

Since:

2.26

getMethodInfo

public @Nullable DBusMethodInfo getMethodInfo()

Gets information about the method call, if any.

If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then null will be returned. See g_dbus_method_invocation_get_property_info() and GDBusInterfaceVTable for more information.

Returns:

A GDBusMethodInfo or null. Do not free, it is owned by invocation.

Since:

2.26

getMethodName

public String getMethodName()

Gets the name of the method that was invoked.

Returns:

A string. Do not free, it is owned by invocation.

Since:

2.26

getObjectPath

public String getObjectPath()

Gets the object path the method was invoked on.

Returns:

A string. Do not free, it is owned by invocation.

Since:

2.26

getParameters

public Variant getParameters()

Gets the parameters of the method invocation. If there are no input parameters then this will return a GVariant with 0 children rather than NULL.

Returns:

A GVariant tuple. Do not unref this because it is owned by invocation.

Since:

2.26

getPropertyInfo

public @Nullable DBusPropertyInfo getPropertyInfo()

Gets information about the property that this method call is for, if any.

This will only be set in the case of an invocation in response to a property Get or Set call that has been directed to the method call handler for an object on account of its property_get() or property_set() vtable pointers being unset.

See GDBusInterfaceVTable for more information.

If the call was GetAll, null will be returned.

Returns:

a GDBusPropertyInfo or null

Since:

2.38

getSender

public @Nullable String getSender()

Gets the bus name that invoked the method.

This can return null if not specified by the caller, e.g. on peer-to-peer connections.

Returns:

A string. Do not free, it is owned by invocation.

Since:

2.26

getUserData

public @Nullable MemorySegment getUserData()

Gets the userData gpointer passed to g_dbus_connection_register_object().

Returns:

A gpointer.

Since:

2.26

returnDbusError

public void returnDbusError(String errorName,
 String errorMessage)

Finishes handling a D-Bus method call by returning an error.

This method will take ownership of invocation. See GDBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

errorName - A valid D-Bus error name.

errorMessage - A valid D-Bus error message.

Since:

2.26

returnError

public void returnError(Quark domain,
 int code,
 String format,
 Object... varargs)

Finishes handling a D-Bus method call by returning an error.

See g_dbus_error_encode_gerror() for details about what error name will be returned on the wire. In a nutshell, if the given error is registered using g_dbus_error_register_error() the name given during registration is used. Otherwise, a name of the form org.gtk.GDBus.UnmappedGError.Quark... is used. This provides transparent mapping of GError between applications using GDBus.

If you are writing an application intended to be portable, always register errors with g_dbus_error_register_error() or use g_dbus_method_invocation_return_dbus_error().

This method will take ownership of invocation. See GDBusInterfaceVTable for more information about the ownership of invocation.

Since 2.48, if the method call requested for a reply not to be sent then this call will free this DBusMethodInvocation but otherwise do nothing (as per the recommendations of the D-Bus specification).

Parameters:

domain - A GQuark for the GError error domain.

code - The error code.

format - printf()-style format.

varargs - Parameters for format.

Since:

2.26

returnErrorLiteral

public void returnErrorLiteral(Quark domain,
 int code,
 String message)

Like g_dbus_method_invocation_return_error() but without printf()-style formatting.

This method will take ownership of invocation. See GDBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

domain - A GQuark for the GError error domain.

code - The error code.

message - The error message.

Since:

2.26

returnGerror

public void returnGerror(GError error)

Like g_dbus_method_invocation_return_error() but takes a GError instead of the error domain, error code and message.

This method will take ownership of invocation. See GDBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

error - A GError.

Since:

2.26

returnValue

public void returnValue(@Nullable Variant parameters)

Finishes handling a D-Bus method call by returning parameters. If the parameters GVariant is floating, it is consumed.

It is an error if parameters is not of the right format: it must be a tuple containing the out-parameters of the D-Bus method. Even if the method has a single out-parameter, it must be contained in a tuple. If the method has no out-parameters, parameters may be null or an empty tuple.

GDBusMethodInvocation *invocation = some_invocation;
 g_autofree gchar *result_string = NULL;
 g_autoptr (GError) error = NULL;

 result_string = calculate_result (&error);

 if (error != NULL)
   g_dbus_method_invocation_return_gerror (invocation, error);
 else
   g_dbus_method_invocation_return_value (invocation,
                                          g_variant_new ("(s)", result_string));

 // Do not free @invocation here; returning a value does that
 

This method will take ownership of invocation. See GDBusInterfaceVTable for more information about the ownership of invocation.

Since 2.48, if the method call requested for a reply not to be sent then this call will sink parameters and free invocation, but otherwise do nothing (as per the recommendations of the D-Bus specification).

Parameters:

parameters - A GVariant tuple with out parameters for the method or null if not passing any parameters.

Since:

2.26

returnValueWithUnixFdList

public void returnValueWithUnixFdList(@Nullable Variant parameters,
 @Nullable UnixFDList fdList)

Like g_dbus_method_invocation_return_value() but also takes a GUnixFDList.

This method is only available on UNIX.

This method will take ownership of invocation. See GDBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

parameters - A GVariant tuple with out parameters for the method or null if not passing any parameters.

fdList - A GUnixFDList or null.

Since:

2.30

takeError

public void takeError(GError error)

Like g_dbus_method_invocation_return_gerror() but takes ownership of error so the caller does not need to free it.

This method will take ownership of invocation. See GDBusInterfaceVTable for more information about the ownership of invocation.

Parameters:

error - A GError.

Since:

2.30

builder

public static DBusMethodInvocation.Builder<? extends DBusMethodInvocation.Builder> builder()

A DBusMethodInvocation.Builder object constructs a DBusMethodInvocation with the specified properties. Use the various set...() methods to set properties, and finish construction with DBusMethodInvocation.Builder.build().

Returns:

the builder object