Package org.gnome.gio

Class SocketListener

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.SocketListener

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

SocketService

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

A GSocketListener is an object that keeps track of a set of server sockets and helps you accept sockets from any of the socket, either sync or async.

Add addresses and ports to listen on using addAddress(org.gnome.gio.SocketAddress, org.gnome.gio.SocketType, org.gnome.gio.SocketProtocol, org.gnome.gobject.GObject, org.javagi.base.Out<org.gnome.gio.SocketAddress>) and addInetPort(short, org.gnome.gobject.GObject). These will be listened on until close() is called. Dropping your final reference to the GSocketListener will not cause close() to be called implicitly, as some references to the GSocketListener may be held internally.

If you want to implement a network server, also look at SocketService and ThreadedSocketService which are subclasses of GSocketListener that make this even easier.

Since:

2.22

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SocketListener.Builder<B extends SocketListener.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	SocketListener.EventCallback	Functional interface declaration of the EventCallback callback.
static class	SocketListener.SocketListenerClass	Class structure for GSocketListener.

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

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
SocketConnection	accept(@Nullable Out<GObject> sourceObject, @Nullable Cancellable cancellable)	Blocks waiting for a client to connect to any of the sockets added to the listener.
void	acceptAsync(@Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	This is the asynchronous version of g_socket_listener_accept().
SocketConnection	acceptFinish(AsyncResult result, @Nullable Out<GObject> sourceObject)	Finishes an async accept operation.
Socket	acceptSocket(@Nullable Out<GObject> sourceObject, @Nullable Cancellable cancellable)	Blocks waiting for a client to connect to any of the sockets added to the listener.
void	acceptSocketAsync(@Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	This is the asynchronous version of g_socket_listener_accept_socket().
Socket	acceptSocketFinish(AsyncResult result, @Nullable Out<GObject> sourceObject)	Finishes an async accept operation.
boolean	addAddress(SocketAddress address, SocketType type, SocketProtocol protocol, @Nullable GObject sourceObject, @Nullable Out<SocketAddress> effectiveAddress)	Creates a socket of type type and protocol protocol, binds it to address and adds it to the set of sockets we're accepting sockets from.
short	addAnyInetPort(@Nullable GObject sourceObject)	Listens for TCP connections on any available port number for both IPv6 and IPv4 (if each is available).
boolean	addInetPort(short port, @Nullable GObject sourceObject)	Helper function for g_socket_listener_add_address() that creates a TCP/IP socket listening on IPv4 and IPv6 (if supported) on the specified port on all interfaces.
boolean	addSocket(Socket socket, @Nullable GObject sourceObject)	Adds socket to the set of sockets that we try to accept new clients from.
protected SocketListener	asParent()	Returns this instance as if it were its parent type.
static SocketListener.Builder<? extends SocketListener.Builder>	builder()	A SocketListener.Builder object constructs a SocketListener with the specified properties.
protected void	changed()	virtual method called when the set of socket listened to changes
void	close()	Closes all the sockets in the listener.
void	emitEvent(SocketListenerEvent event, @Nullable Socket socket)	Emits the "event" signal.
protected void	event(SocketListenerEvent event, Socket socket)
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static @Nullable Type	getType()	Get the GType of the SocketListener class
SignalConnection<SocketListener.EventCallback>	onEvent(SocketListener.EventCallback handler)	Emitted when listener's activity on socket changes state.
void	setBacklog(int listenBacklog)	Sets the listen backlog on the sockets in the listener.

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, 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

SocketListener

public SocketListener(MemorySegment address)

Create a SocketListener proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

SocketListener

public SocketListener()

Creates a new SocketListener.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the SocketListener class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

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

accept

public SocketConnection accept(@Nullable Out<GObject> sourceObject,
 @Nullable Cancellable cancellable)
                        throws GErrorException

Blocks waiting for a client to connect to any of the sockets added to the listener. Returns a GSocketConnection for the socket that was accepted.

If sourceObject is not null it will be filled out with the source object specified when the corresponding socket or address was added to the listener.

If cancellable is not null, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnum.CANCELLED will be returned.

Parameters:

sourceObject - location where GObject pointer will be stored, or null

cancellable - optional GCancellable object, null to ignore.

Returns:

a GSocketConnection on success, null on error.

Throws:

GErrorException - see GError

Since:

2.22

acceptAsync

public void acceptAsync(@Nullable Cancellable cancellable,
 @Nullable AsyncReadyCallback callback)

This is the asynchronous version of g_socket_listener_accept().

When the operation is finished callback will be called. You can then call g_socket_listener_accept_finish() to get the result of the operation.

Parameters:

cancellable - a GCancellable, or null

callback - a GAsyncReadyCallback

Since:

2.22

acceptFinish

public SocketConnection acceptFinish(AsyncResult result,
 @Nullable Out<GObject> sourceObject)
                              throws GErrorException

Finishes an async accept operation. See g_socket_listener_accept_async()

Parameters:

result - a GAsyncResult.

sourceObject - Optional GObject identifying this source

Returns:

a GSocketConnection on success, null on error.

Throws:

GErrorException - see GError

Since:

2.22

acceptSocket

public Socket acceptSocket(@Nullable Out<GObject> sourceObject,
 @Nullable Cancellable cancellable)
                    throws GErrorException

Blocks waiting for a client to connect to any of the sockets added to the listener. Returns the GSocket that was accepted.

If you want to accept the high-level GSocketConnection, not a GSocket, which is often the case, then you should use g_socket_listener_accept() instead.

If sourceObject is not null it will be filled out with the source object specified when the corresponding socket or address was added to the listener.

If cancellable is not null, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnum.CANCELLED will be returned.

Parameters:

sourceObject - location where GObject pointer will be stored, or null.

cancellable - optional GCancellable object, null to ignore.

Returns:

a GSocket on success, null on error.

Throws:

GErrorException - see GError

Since:

2.22

acceptSocketAsync

public void acceptSocketAsync(@Nullable Cancellable cancellable,
 @Nullable AsyncReadyCallback callback)

This is the asynchronous version of g_socket_listener_accept_socket().

When the operation is finished callback will be called. You can then call g_socket_listener_accept_socket_finish() to get the result of the operation.

Parameters:

cancellable - a GCancellable, or null

callback - a GAsyncReadyCallback

Since:

2.22

acceptSocketFinish

public Socket acceptSocketFinish(AsyncResult result,
 @Nullable Out<GObject> sourceObject)
                          throws GErrorException

Finishes an async accept operation. See g_socket_listener_accept_socket_async()

Parameters:

result - a GAsyncResult.

sourceObject - Optional GObject identifying this source

Returns:

a GSocket on success, null on error.

Throws:

GErrorException - see GError

Since:

2.22

addAddress

public boolean addAddress(SocketAddress address,
 SocketType type,
 SocketProtocol protocol,
 @Nullable GObject sourceObject,
 @Nullable Out<SocketAddress> effectiveAddress)
                   throws GErrorException

Creates a socket of type type and protocol protocol, binds it to address and adds it to the set of sockets we're accepting sockets from.

Note that adding an IPv6 address, depending on the platform, may or may not result in a listener that also accepts IPv4 connections. For more deterministic behavior, see g_socket_listener_add_inet_port().

sourceObject will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

If successful and effectiveAddress is non-null then it will be set to the address that the binding actually occurred at. This is helpful for determining the port number that was used for when requesting a binding to port 0 (ie: "any port"). This address, if requested, belongs to the caller and must be freed.

Call g_socket_listener_close() to stop listening on address; this will not be done automatically when you drop your final reference to listener, as references may be held internally.

Parameters:

address - a GSocketAddress

type - a GSocketType

protocol - a GSocketProtocol

sourceObject - Optional GObject identifying this source

effectiveAddress - location to store the address that was bound to, or null.

Returns:

true on success, false on error.

Throws:

GErrorException - see GError

Since:

2.22

addAnyInetPort

public short addAnyInetPort(@Nullable GObject sourceObject)
                     throws GErrorException

Listens for TCP connections on any available port number for both IPv6 and IPv4 (if each is available).

This is useful if you need to have a socket for incoming connections but don't care about the specific port number.

If possible, the SocketListener will listen on both IPv4 and IPv6 (listening on the same port on both). If listening on one of the socket families fails, the SocketListener will only listen on the other. If listening on both fails, an error will be returned.

If you need to distinguish whether listening on IPv4 or IPv6 or both was successful, connect to Gio.SocketListener::event.

sourceObject will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

Parameters:

sourceObject - Optional GObject identifying this source

Returns:

the port number, or 0 in case of failure.

Throws:

GErrorException - see GError

Since:

2.24

addInetPort

public boolean addInetPort(short port,
 @Nullable GObject sourceObject)
                    throws GErrorException

Helper function for g_socket_listener_add_address() that creates a TCP/IP socket listening on IPv4 and IPv6 (if supported) on the specified port on all interfaces.

If possible, the SocketListener will listen on both IPv4 and IPv6 (listening on the same port on both). If listening on one of the socket families fails, the SocketListener will only listen on the other. If listening on both fails, an error will be returned.

If you need to distinguish whether listening on IPv4 or IPv6 or both was successful, connect to Gio.SocketListener::event.

sourceObject will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

Call g_socket_listener_close() to stop listening on port; this will not be done automatically when you drop your final reference to listener, as references may be held internally.

Parameters:

port - an IP port number (non-zero)

sourceObject - Optional GObject identifying this source

Returns:

true on success, false on error.

Throws:

GErrorException - see GError

Since:

2.22

addSocket

public boolean addSocket(Socket socket,
 @Nullable GObject sourceObject)
                  throws GErrorException

Adds socket to the set of sockets that we try to accept new clients from. The socket must be bound to a local address and listened to.

For parallel calls to SocketListener methods to work, the socket must be in non-blocking mode. (See Gio.Socket:blocking.)

sourceObject will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

The socket will not be automatically closed when the this SocketListener is finalized unless the listener held the final reference to the socket. Before GLib 2.42, the socket was automatically closed on finalization of the listener, even if references to it were held elsewhere.

Parameters:

socket - a listening GSocket

sourceObject - Optional GObject identifying this source

Returns:

true on success, false on error.

Throws:

GErrorException - see GError

Since:

2.22

close

public void close()

Closes all the sockets in the listener.

Since:

2.22

setBacklog

public void setBacklog(int listenBacklog)

Sets the listen backlog on the sockets in the listener. This must be called before adding any sockets, addresses or ports to the GSocketListener (for example, by calling g_socket_listener_add_inet_port()) to be effective.

See g_socket_set_listen_backlog() for details

Parameters:

listenBacklog - an integer

Since:

2.22

changed

protected void changed()

virtual method called when the set of socket listened to changes

event

protected void event(SocketListenerEvent event,
 Socket socket)

onEvent

public SignalConnection<SocketListener.EventCallback> onEvent(SocketListener.EventCallback handler)

Emitted when listener's activity on socket changes state. Note that when listener is used to listen on both IPv4 and IPv6, a separate set of signals will be emitted for each, and the order they happen in is undefined.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

Since:

2.46

See Also:

• SocketListener.EventCallback.run(org.gnome.gio.SocketListenerEvent, org.gnome.gio.Socket)

emitEvent

public void emitEvent(SocketListenerEvent event,
 @Nullable Socket socket)

Emits the "event" signal. See onEvent(org.gnome.gio.SocketListener.EventCallback).

builder

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

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

Returns:

the builder object