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("org.javagi.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(SocketAddress, SocketType, SocketProtocol, GObject, Out) and addInetPort(short, 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

  • Constructor Details

    • SocketListener

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

    • SocketListener

      public SocketListener()
      Create 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()
      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

    • 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:

    • emitEvent

      public void emitEvent(SocketListenerEvent event, @Nullable Socket socket)
      Emits the "event" signal. See onEvent(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