Package ch.bailu.gtk.gio

Class Socket

java.lang.Object

ch.bailu.gtk.type.Type

ch.bailu.gtk.type.Pointer

ch.bailu.gtk.gobject.Object

ch.bailu.gtk.gio.Socket

All Implemented Interfaces:

PointerInterface

public class Socket
extends Object

A #GSocket is a low-level networking primitive. It is a more or less
direct mapping of the BSD socket API in a portable GObject based API.
It supports both the UNIX socket implementations and winsock2 on Windows.

#GSocket is the platform independent base upon which the higher level
network primitives are based. Applications are not typically meant to
use it directly, but rather through classes like #GSocketClient,
#GSocketService and #GSocketConnection. However there may be cases where
direct use of #GSocket is useful.

#GSocket implements the #GInitable interface, so if it is manually constructed
by e.g. g_object_new() you must call g_initable_init() and check the
results before using the object. This is done automatically in
g_socket_new() and g_socket_new_from_fd(), so these functions can return
%NULL.

Sockets operate in two general modes, blocking or non-blocking. When
in blocking mode all operations (which don’t take an explicit blocking
parameter) block until the requested operation
is finished or there is an error. In non-blocking mode all calls that
would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
To know when a call would successfully run you can call g_socket_condition_check(),
or g_socket_condition_wait(). You can also use g_socket_create_source() and
attach it to a #GMainContext to get callbacks when I/O is possible.
Note that all sockets are always set to non blocking mode in the system, and
blocking mode is emulated in GSocket.

When working in non-blocking mode applications should always be able to
handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
function said that I/O was possible. This can easily happen in case
of a race condition in the application, but it can also happen for other
reasons. For instance, on Windows a socket is always seen as writable
until a write returns %G_IO_ERROR_WOULD_BLOCK.

#GSockets can be either connection oriented or datagram based.
For connection oriented types you must first establish a connection by
either connecting to an address or accepting a connection from another
address. For connectionless socket types the target/source address is
specified or received in each I/O operation.

All socket file descriptors are set to be close-on-exec.

Note that creating a #GSocket causes the signal %SIGPIPE to be
ignored for the remainder of the program. If you are writing a
command-line utility that uses #GSocket, you may need to take into
account the fact that your program will not automatically be killed
if it tries to write to %stdout after it has been closed.

Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
a #GSocket concurrently from multiple threads, you must implement your own
locking.

https://docs.gtk.org/gio/class.Socket.html

Nested Class Summary

Nested classes/interfaces inherited from class ch.bailu.gtk.gobject.Object

Object.OnBindingTransformFunc, Object.OnDestroyNotify, Object.OnDuplicateFunc, Object.OnNotify, Object.OnToggleNotify, Object.OnWeakNotify

Field Summary

Fields inherited from class ch.bailu.gtk.gobject.Object

SIGNAL_ON_NOTIFY

Fields inherited from class ch.bailu.gtk.type.Pointer

NULL

Constructor Summary

Constructors

Constructor	Description
Socket(int family, int type, int protocol)	Creates a new #GSocket with the defined family, type and protocol.
Socket(PointerContainer pointer)

Method Summary

Modifier and Type	Method	Description
Socket	accept(Cancellable cancellable)	Accept incoming connections on a connection-based socket.
DatagramBased	asDatagramBased()	Implements interface DatagramBased.
Initable	asInitable()	Implements interface Initable.
boolean	bind(SocketAddress address, boolean allow_reuse)	When a socket is created it is attached to an address family, but it doesn't have an address in this family. g_socket_bind() assigns the address (sometimes called name) of the socket.
boolean	checkConnectResult()	Checks and resets the pending connect error for the socket.
boolean	close()	Closes the socket, shutting down any active connection.
int	conditionCheck(int condition)	Checks on the readiness of @socket to perform operations.
boolean	conditionTimedWait(int condition, long timeout_us, Cancellable cancellable)	Waits for up to @timeout_us microseconds for @condition to become true on @socket.
boolean	conditionWait(int condition, Cancellable cancellable)	Waits for @condition to become true on @socket.
boolean	connect(SocketAddress address, Cancellable cancellable)	Connect the socket to the specified remote address.
SocketConnection	connectionFactoryCreateConnection()	Creates a #GSocketConnection subclass of the right type for @socket.
Source	createSource(int condition, Cancellable cancellable)	Creates a #GSource that can be attached to a %GMainContext to monitor for the availability of the specified @condition on the socket.
long	getAvailableBytes()	Get the amount of data pending in the OS input buffer, without blocking.
boolean	getBlocking()	Gets the blocking mode of the socket.
boolean	getBroadcast()	Gets the broadcast setting on @socket; if %TRUE, it is possible to send packets to broadcast addresses.
static ClassHandler	getClassHandler()
Credentials	getCredentials()	Returns the credentials of the foreign process connected to this socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX sockets).
int	getFamily()	Gets the socket family of the socket.
int	getFd()	Returns the underlying OS socket object.
static int	getInstanceSize()
boolean	getKeepalive()	Gets the keepalive mode of the socket.
int	getListenBacklog()	Gets the listen backlog setting of the socket.
SocketAddress	getLocalAddress()	Try to get the local address of a bound socket.
boolean	getMulticastLoopback()	Gets the multicast loopback setting on @socket; if %TRUE (the default), outgoing multicast packets will be looped back to multicast listeners on the same host.
int	getMulticastTtl()	Gets the multicast time-to-live setting on @socket; see g_socket_set_multicast_ttl() for more details.
boolean	getOption(int level, int optname, Int value)	Gets the value of an integer-valued option on @socket, as with getsockopt().
static long	getParentTypeID()
static TypeSystem.TypeSize	getParentTypeSize()
int	getProtocol()	Gets the socket protocol id the socket was created with.
SocketAddress	getRemoteAddress()	Try to get the remote address of a connected socket.
int	getSocketType()	Gets the socket type of the socket.
int	getTimeout()	Gets the timeout setting of the socket.
int	getTtl()	Gets the unicast time-to-live setting on @socket; see g_socket_set_ttl() for more details.
static long	getTypeID()
static TypeSystem.TypeSize	getTypeSize()
boolean	isClosed()	Checks whether a socket is closed.
boolean	isConnected()	Check whether the socket is connected.
boolean	joinMulticastGroup(InetAddress group, boolean source_specific, Str iface)	Registers @socket to receive multicast messages sent to @group.
boolean	joinMulticastGroup(InetAddress group, boolean source_specific, String iface)	Registers @socket to receive multicast messages sent to @group.
boolean	joinMulticastGroupSsm(InetAddress group, InetAddress source_specific, Str iface)	Registers @socket to receive multicast messages sent to @group.
boolean	joinMulticastGroupSsm(InetAddress group, InetAddress source_specific, String iface)	Registers @socket to receive multicast messages sent to @group.
boolean	leaveMulticastGroup(InetAddress group, boolean source_specific, Str iface)	Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group).
boolean	leaveMulticastGroup(InetAddress group, boolean source_specific, String iface)	Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group).
boolean	leaveMulticastGroupSsm(InetAddress group, InetAddress source_specific, Str iface)	Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group).
boolean	leaveMulticastGroupSsm(InetAddress group, InetAddress source_specific, String iface)	Removes @socket from the multicast group defined by @group, @iface, and @source_specific (which must all have the same values they had when you joined the group).
boolean	listen()	Marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using g_socket_accept().
static Socket	newFromFdSocket(int fd)	Creates a new #GSocket from a native file descriptor or winsock SOCKET handle.
long	receive(Str buffer, long size, Cancellable cancellable)	Receive data (up to @size bytes) from a socket.
long	receiveWithBlocking(Str buffer, long size, boolean blocking, Cancellable cancellable)	This behaves exactly the same as g_socket_receive(), except that the choice of blocking or non-blocking behavior is determined by the @blocking argument rather than by @socket's properties.
long	send(Str buffer, long size, Cancellable cancellable)	Tries to send @size bytes from @buffer on the socket.
long	send(String buffer, long size, Cancellable cancellable)	Tries to send @size bytes from @buffer on the socket.
long	sendTo(SocketAddress address, Str buffer, long size, Cancellable cancellable)	Tries to send @size bytes from @buffer to @address.
long	sendTo(SocketAddress address, String buffer, long size, Cancellable cancellable)	Tries to send @size bytes from @buffer to @address.
long	sendWithBlocking(Str buffer, long size, boolean blocking, Cancellable cancellable)	This behaves exactly the same as g_socket_send(), except that the choice of blocking or non-blocking behavior is determined by the @blocking argument rather than by @socket's properties.
long	sendWithBlocking(String buffer, long size, boolean blocking, Cancellable cancellable)	This behaves exactly the same as g_socket_send(), except that the choice of blocking or non-blocking behavior is determined by the @blocking argument rather than by @socket's properties.
void	setBlocking(boolean blocking)	Sets the blocking mode of the socket.
void	setBroadcast(boolean broadcast)	Sets whether @socket should allow sending to broadcast addresses.
void	setKeepalive(boolean keepalive)	Sets or unsets the %SO_KEEPALIVE flag on the underlying socket.
void	setListenBacklog(int backlog)	Sets the maximum number of outstanding connections allowed when listening on this socket.
void	setMulticastLoopback(boolean loopback)	Sets whether outgoing multicast packets will be received by sockets listening on that multicast address on the same host.
void	setMulticastTtl(int ttl)	Sets the time-to-live for outgoing multicast datagrams on @socket.
boolean	setOption(int level, int optname, int value)	Sets the value of an integer-valued option on @socket, as with setsockopt().
void	setTimeout(int timeout)	Sets the time in seconds after which I/O operations on @socket will time out if they have not yet completed.
void	setTtl(int ttl)	Sets the time-to-live for outgoing unicast packets on @socket.
boolean	shutdown(boolean shutdown_read, boolean shutdown_write)	Shut down part or all of a full-duplex connection.
boolean	speaksIpv4()	Checks if a socket is capable of speaking IPv4.

Methods inherited from class ch.bailu.gtk.gobject.Object

addToggleRef, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, disconnect, disconnect, dupData, dupData, dupQdata, forceFloating, freezeNotify, get, get, getData, getData, getProperty, getProperty, getQdata, interfaceFindProperty, interfaceInstallProperty, isFloating, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, replaceData, replaceData, replaceQdata, runDispose, set, set, setData, setData, setDataFull, setDataFull, setProperty, setProperty, setQdata, setQdataFull, stealData, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref

Methods inherited from class ch.bailu.gtk.type.Pointer

asCPointer, cast, connectSignal, disconnectSignals, disconnectSignals, equals, hashCode, throwIfNull, throwNullPointerException, toString, unregisterCallbacks, unregisterCallbacks

Methods inherited from class ch.bailu.gtk.type.Type

asCPointer, asCPointer, asCPointerNotNull, asJnaPointer, asJnaPointer, asPointer, asPointer, cast, cast, throwIfNull

Methods inherited from class java.lang.Object

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

Methods inherited from interface ch.bailu.gtk.type.PointerInterface

asCPointerNotNull, asJnaPointer, asPointer, isNotNull, isNull

Constructor Details

Socket

public Socket(PointerContainer pointer)

Socket

public Socket(int family,
 int type,
 int protocol)

Creates a new #GSocket with the defined family, type and protocol.
If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
for the family and type is used.

The @protocol is a family and type specific int that specifies what
kind of protocol to use. #GSocketProtocol lists several common ones.
Many families only support one protocol, and use 0 for this, others
support several and using 0 means to use the default protocol for
the family and type.

The protocol id is passed directly to the operating
system, so you can use protocols not listed in #GSocketProtocol if you
know the protocol number used for it.

Parameters:

family - the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.

type - the socket type to use.

protocol - the id of the protocol to use, or 0 for default.

Method Details

getClassHandler

public static ClassHandler getClassHandler()

newFromFdSocket

public static Socket newFromFdSocket(int fd)
                              throws AllocationError

Creates a new #GSocket from a native file descriptor
or winsock SOCKET handle.

This reads all the settings from the file descriptor so that
all properties should work. Note that the file descriptor
will be set to non-blocking mode, independent on the blocking
mode of the #GSocket.

On success, the returned #GSocket takes ownership of @fd. On failure, the
caller must close @fd themselves.

Since GLib 2.46, it is no longer a fatal error to call this on a non-socket
descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED

Parameters:

fd - a native socket file descriptor.

Returns:

a #GSocket or %NULL on error. Free the returned object with g_object_unref().

Throws:

AllocationError

accept

public Socket accept(@Nullable
 Cancellable cancellable)
              throws AllocationError

Accept incoming connections on a connection-based socket. This removes
the first outstanding connection request from the listening socket and
creates a #GSocket object for it.

The @socket must be bound to a local address with g_socket_bind() and
must be listening for incoming connections (g_socket_listen()).

If there are no outstanding connections then the operation will block
or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
To be notified of an incoming connection, wait for the %G_IO_IN condition.

Parameters:

cancellable - a %GCancellable or %NULL

Returns:

a new #GSocket, or %NULL on error. Free the returned object with g_object_unref().

Throws:

AllocationError

bind

public boolean bind(@Nonnull
 SocketAddress address,
 boolean allow_reuse)
             throws AllocationError

When a socket is created it is attached to an address family, but it
doesn't have an address in this family. g_socket_bind() assigns the
address (sometimes called name) of the socket.

It is generally required to bind to a local address before you can
receive connections. (See g_socket_listen() and g_socket_accept() ).
In certain situations, you may also want to bind a socket that will be
used to initiate connections, though this is not normally required.

If @socket is a TCP socket, then @allow_reuse controls the setting
of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
server sockets (sockets that you will eventually call
g_socket_accept() on), and %FALSE for client sockets. (Failing to
set this flag on a server socket may cause g_socket_bind() to return
%G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
immediately restarted.)

If @socket is a UDP socket, then @allow_reuse determines whether or
not other UDP sockets can be bound to the same address at the same
time. In particular, you can have several UDP sockets bound to the
same address, and they will all receive all of the multicast and
broadcast packets sent to that address. (The behavior of unicast
UDP packets to an address with multiple listeners is not defined.)

Parameters:

address - a #GSocketAddress specifying the local address.

allow_reuse - whether to allow reusing this address

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

checkConnectResult

public boolean checkConnectResult()
                           throws AllocationError

Checks and resets the pending connect error for the socket.
This is used to check for errors when g_socket_connect() is
used in non-blocking mode.

Returns:

%TRUE if no error, %FALSE otherwise, setting @error to the error

Throws:

AllocationError

close

public boolean close()
              throws AllocationError

Closes the socket, shutting down any active connection.

Closing a socket does not wait for all outstanding I/O operations
to finish, so the caller should not rely on them to be guaranteed
to complete even if the close returns with no error.

Once the socket is closed, all other operations will return
%G_IO_ERROR_CLOSED. Closing a socket multiple times will not
return an error.

Sockets will be automatically closed when the last reference
is dropped, but you might want to call this function to make sure
resources are released as early as possible.

Beware that due to the way that TCP works, it is possible for
recently-sent data to be lost if either you close a socket while the
%G_IO_IN condition is set, or else if the remote connection tries to
send something to you after you close the socket but before it has
finished reading all of the data you sent. There is no easy generic
way to avoid this problem; the easiest fix is to design the network
protocol such that the client will never send data "out of turn".
Another solution is for the server to half-close the connection by
calling g_socket_shutdown() with only the @shutdown_write flag set,
and then wait for the client to notice this and close its side of the
connection, after which the server can safely call g_socket_close().
(This is what #GTcpConnection does if you call
g_tcp_connection_set_graceful_disconnect(). But of course, this
only works if the client will close its connection after the server
does.)

Returns:

%TRUE on success, %FALSE on error

Throws:

AllocationError

conditionCheck

public int conditionCheck(int condition)

Checks on the readiness of @socket to perform operations.
The operations specified in @condition are checked for and masked
against the currently-satisfied conditions on @socket. The result
is returned.

Note that on Windows, it is possible for an operation to return
%G_IO_ERROR_WOULD_BLOCK even immediately after
g_socket_condition_check() has claimed that the socket is ready for
writing. Rather than calling g_socket_condition_check() and then
writing to the socket if it succeeds, it is generally better to
simply try writing to the socket right away, and try again later if
the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.

It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
these conditions will always be set in the output if they are true.

This call never blocks.

Parameters:

condition - a #GIOCondition mask to check

Returns:

the @GIOCondition mask of the current state

conditionTimedWait

public boolean conditionTimedWait(int condition,
 long timeout_us,
 @Nullable
 Cancellable cancellable)
                           throws AllocationError

Waits for up to @timeout_us microseconds for @condition to become true
on @socket. If the condition is met, %TRUE is returned.

If @cancellable is cancelled before the condition is met, or if
@timeout_us (or the socket's #GSocket:timeout) is reached before the
condition is met, then %FALSE is returned and @error, if non-%NULL,
is set to the appropriate value (%G_IO_ERROR_CANCELLED or
%G_IO_ERROR_TIMED_OUT).

If you don't want a timeout, use g_socket_condition_wait().
(Alternatively, you can pass -1 for @timeout_us.)

Note that although @timeout_us is in microseconds for consistency with
other GLib APIs, this function actually only has millisecond
resolution, and the behavior is undefined if @timeout_us is not an
exact number of milliseconds.

Parameters:

condition - a #GIOCondition mask to wait for

timeout_us - the maximum time (in microseconds) to wait, or -1

cancellable - a #GCancellable, or %NULL

Returns:

%TRUE if the condition was met, %FALSE otherwise

Throws:

AllocationError

conditionWait

public boolean conditionWait(int condition,
 @Nullable
 Cancellable cancellable)
                      throws AllocationError

Waits for @condition to become true on @socket. When the condition
is met, %TRUE is returned.

If @cancellable is cancelled before the condition is met, or if the
socket has a timeout set and it is reached before the condition is
met, then %FALSE is returned and @error, if non-%NULL, is set to
the appropriate value (%G_IO_ERROR_CANCELLED or
%G_IO_ERROR_TIMED_OUT).

See also g_socket_condition_timed_wait().

Parameters:

condition - a #GIOCondition mask to wait for

cancellable - a #GCancellable, or %NULL

Returns:

%TRUE if the condition was met, %FALSE otherwise

Throws:

AllocationError

connect

public boolean connect(@Nonnull
 SocketAddress address,
 @Nullable
 Cancellable cancellable)
                throws AllocationError

Connect the socket to the specified remote address.

For connection oriented socket this generally means we attempt to make
a connection to the @address. For a connection-less socket it sets
the default address for g_socket_send() and discards all incoming datagrams
from other sources.

Generally connection oriented sockets can only connect once, but
connection-less sockets can connect multiple times to change the
default address.

If the connect call needs to do network I/O it will block, unless
non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
and the user can be notified of the connection finishing by waiting
for the G_IO_OUT condition. The result of the connection must then be
checked with g_socket_check_connect_result().

Parameters:

address - a #GSocketAddress specifying the remote address.

cancellable - a %GCancellable or %NULL

Returns:

%TRUE if connected, %FALSE on error.

Throws:

AllocationError

connectionFactoryCreateConnection

public SocketConnection connectionFactoryCreateConnection()

Creates a #GSocketConnection subclass of the right type for
@socket.

Returns:

a #GSocketConnection

createSource

public Source createSource(int condition,
 @Nullable
 Cancellable cancellable)

Creates a #GSource that can be attached to a %GMainContext to monitor
for the availability of the specified @condition on the socket. The #GSource
keeps a reference to the @socket.

The callback on the source is of the #GSocketSourceFunc type.

It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
these conditions will always be reported output if they are true.

@cancellable if not %NULL can be used to cancel the source, which will
cause the source to trigger, reporting the current condition (which
is likely 0 unless cancellation happened at the same time as a
condition change). You can check for this in the callback using
g_cancellable_is_cancelled().

If @socket has a timeout set, and it is reached before @condition
occurs, the source will then trigger anyway, reporting %G_IO_IN or
%G_IO_OUT depending on @condition. However, @socket will have been
marked as having had a timeout, and so the next #GSocket I/O method
you call will then fail with a %G_IO_ERROR_TIMED_OUT.

Parameters:

condition - a #GIOCondition mask to monitor

cancellable - a %GCancellable or %NULL

Returns:

a newly allocated %GSource, free with g_source_unref().

getAvailableBytes

public long getAvailableBytes()

Get the amount of data pending in the OS input buffer, without blocking.

If @socket is a UDP or SCTP socket, this will return the size of
just the next packet, even if additional packets are buffered after
that one.

Note that on Windows, this function is rather inefficient in the
UDP case, and so if you know any plausible upper bound on the size
of the incoming packet, it is better to just do a
g_socket_receive() with a buffer of that size, rather than calling
g_socket_get_available_bytes() first and then doing a receive of
exactly the right size.

Returns:

the number of bytes that can be read from the socket without blocking or truncating, or -1 on error.

getBlocking

public boolean getBlocking()

Gets the blocking mode of the socket. For details on blocking I/O,
see g_socket_set_blocking().

Returns:

%TRUE if blocking I/O is used, %FALSE otherwise.

getBroadcast

public boolean getBroadcast()

Gets the broadcast setting on @socket; if %TRUE,
it is possible to send packets to broadcast
addresses.

Returns:

the broadcast setting on @socket

getCredentials

public Credentials getCredentials()
                           throws AllocationError

Returns the credentials of the foreign process connected to this
socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
sockets).

If this operation isn't supported on the OS, the method fails with
the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
by reading the %SO_PEERCRED option on the underlying socket.

This method can be expected to be available on the following platforms:

- Linux since GLib 2.26
- OpenBSD since GLib 2.30
- Solaris, Illumos and OpenSolaris since GLib 2.40
- NetBSD since GLib 2.42
- macOS, tvOS, iOS since GLib 2.66

Other ways to obtain credentials from a foreign peer includes the
#GUnixCredentialsMessage type and
g_unix_connection_send_credentials() /
g_unix_connection_receive_credentials() functions.

Returns:

%NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref().

Throws:

AllocationError

getFamily

public int getFamily()

Gets the socket family of the socket.

Returns:

a #GSocketFamily

getFd

public int getFd()

Returns the underlying OS socket object. On unix this
is a socket file descriptor, and on Windows this is
a Winsock2 SOCKET handle. This may be useful for
doing platform specific or otherwise unusual operations
on the socket.

Returns:

the file descriptor of the socket.

getKeepalive

public boolean getKeepalive()

Gets the keepalive mode of the socket. For details on this,
see g_socket_set_keepalive().

Returns:

%TRUE if keepalive is active, %FALSE otherwise.

getListenBacklog

public int getListenBacklog()

Gets the listen backlog setting of the socket. For details on this,
see g_socket_set_listen_backlog().

Returns:

the maximum number of pending connections.

getLocalAddress

public SocketAddress getLocalAddress()
                              throws AllocationError

Try to get the local address of a bound socket. This is only
useful if the socket has been bound to a local address,
either explicitly or implicitly when connecting.

Returns:

a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().

Throws:

AllocationError

getMulticastLoopback

public boolean getMulticastLoopback()

Gets the multicast loopback setting on @socket; if %TRUE (the
default), outgoing multicast packets will be looped back to
multicast listeners on the same host.

Returns:

the multicast loopback setting on @socket

getMulticastTtl

public int getMulticastTtl()

Gets the multicast time-to-live setting on @socket; see
g_socket_set_multicast_ttl() for more details.

Returns:

the multicast time-to-live setting on @socket

getOption

public boolean getOption(int level,
 int optname,
 @Nonnull
 Int value)
                  throws AllocationError

Gets the value of an integer-valued option on @socket, as with
getsockopt(). (If you need to fetch a non-integer-valued option,
you will need to call getsockopt() directly.)

The [<gio/gnetworking.h>][gio-gnetworking.h]
header pulls in system headers that will define most of the
standard/portable socket options. For unusual socket protocols or
platform-dependent options, you may need to include additional
headers.

Note that even for socket options that are a single byte in size,
@value is still a pointer to a #gint variable, not a #guchar;
g_socket_get_option() will handle the conversion internally.

Parameters:

level - the "API level" of the option (eg, `SOL_SOCKET`)

optname - the "name" of the option (eg, `SO_BROADCAST`)

value - return location for the option value

Returns:

success or failure. On failure, @error will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the getsockopt() call.

Throws:

AllocationError

getProtocol

public int getProtocol()

Gets the socket protocol id the socket was created with.
In case the protocol is unknown, -1 is returned.

Returns:

a protocol id, or -1 if unknown

getRemoteAddress

public SocketAddress getRemoteAddress()
                               throws AllocationError

Try to get the remote address of a connected socket. This is only
useful for connection oriented sockets that have been connected.

Returns:

a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().

Throws:

AllocationError

getSocketType

public int getSocketType()

Gets the socket type of the socket.

Returns:

a #GSocketType

getTimeout

public int getTimeout()

Gets the timeout setting of the socket. For details on this, see
g_socket_set_timeout().

Returns:

the timeout in seconds

getTtl

public int getTtl()

Gets the unicast time-to-live setting on @socket; see
g_socket_set_ttl() for more details.

Returns:

the time-to-live setting on @socket

isClosed

public boolean isClosed()

Checks whether a socket is closed.

Returns:

%TRUE if socket is closed, %FALSE otherwise

isConnected

public boolean isConnected()

Check whether the socket is connected. This is only useful for
connection-oriented sockets.

If using g_socket_shutdown(), this function will return %TRUE until the
socket has been shut down for reading and writing. If you do a non-blocking
connect, this function will not return %TRUE until after you call
g_socket_check_connect_result().

Returns:

%TRUE if socket is connected, %FALSE otherwise.

joinMulticastGroup

public boolean joinMulticastGroup(@Nonnull
 InetAddress group,
 boolean source_specific,
 @Nullable
 Str iface)
                           throws AllocationError

Registers @socket to receive multicast messages sent to @group.
@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
been bound to an appropriate interface and port with
g_socket_bind().

If @iface is %NULL, the system will automatically pick an interface
to bind to based on @group.

If @source_specific is %TRUE, source-specific multicast as defined
in RFC 4604 is used. Note that on older platforms this may fail
with a %G_IO_ERROR_NOT_SUPPORTED error.

To bind to a given source-specific multicast address, use
g_socket_join_multicast_group_ssm() instead.

Parameters:

group - a #GInetAddress specifying the group address to join.

source_specific - %TRUE if source-specific multicast should be used

iface - Name of the interface to use, or %NULL

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

joinMulticastGroup

public boolean joinMulticastGroup(@Nonnull
 InetAddress group,
 boolean source_specific,
 String iface)
                           throws AllocationError

Registers @socket to receive multicast messages sent to @group.
@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
been bound to an appropriate interface and port with
g_socket_bind().

If @iface is %NULL, the system will automatically pick an interface
to bind to based on @group.

If @source_specific is %TRUE, source-specific multicast as defined
in RFC 4604 is used. Note that on older platforms this may fail
with a %G_IO_ERROR_NOT_SUPPORTED error.

To bind to a given source-specific multicast address, use
g_socket_join_multicast_group_ssm() instead.

Parameters:

group - a #GInetAddress specifying the group address to join.

source_specific - %TRUE if source-specific multicast should be used

iface - Name of the interface to use, or %NULL

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

joinMulticastGroupSsm

public boolean joinMulticastGroupSsm(@Nonnull
 InetAddress group,
 @Nullable
 InetAddress source_specific,
 @Nullable
 Str iface)
                              throws AllocationError

Registers @socket to receive multicast messages sent to @group.
@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
been bound to an appropriate interface and port with
g_socket_bind().

If @iface is %NULL, the system will automatically pick an interface
to bind to based on @group.

If @source_specific is not %NULL, use source-specific multicast as
defined in RFC 4604. Note that on older platforms this may fail
with a %G_IO_ERROR_NOT_SUPPORTED error.

Note that this function can be called multiple times for the same
@group with different @source_specific in order to receive multicast
packets from more than one source.

Parameters:

group - a #GInetAddress specifying the group address to join.

source_specific - a #GInetAddress specifying the source-specific multicast address or %NULL to ignore.

iface - Name of the interface to use, or %NULL

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

joinMulticastGroupSsm

public boolean joinMulticastGroupSsm(@Nonnull
 InetAddress group,
 @Nullable
 InetAddress source_specific,
 String iface)
                              throws AllocationError

Registers @socket to receive multicast messages sent to @group.
@socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
been bound to an appropriate interface and port with
g_socket_bind().

If @iface is %NULL, the system will automatically pick an interface
to bind to based on @group.

If @source_specific is not %NULL, use source-specific multicast as
defined in RFC 4604. Note that on older platforms this may fail
with a %G_IO_ERROR_NOT_SUPPORTED error.

Note that this function can be called multiple times for the same
@group with different @source_specific in order to receive multicast
packets from more than one source.

Parameters:

group - a #GInetAddress specifying the group address to join.

source_specific - a #GInetAddress specifying the source-specific multicast address or %NULL to ignore.

iface - Name of the interface to use, or %NULL

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

leaveMulticastGroup

public boolean leaveMulticastGroup(@Nonnull
 InetAddress group,
 boolean source_specific,
 @Nullable
 Str iface)
                            throws AllocationError

Removes @socket from the multicast group defined by @group, @iface,
and @source_specific (which must all have the same values they had
when you joined the group).

@socket remains bound to its address and port, and can still receive
unicast messages after calling this.

To unbind to a given source-specific multicast address, use
g_socket_leave_multicast_group_ssm() instead.

Parameters:

group - a #GInetAddress specifying the group address to leave.

source_specific - %TRUE if source-specific multicast was used

iface - Interface used

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

leaveMulticastGroup

public boolean leaveMulticastGroup(@Nonnull
 InetAddress group,
 boolean source_specific,
 String iface)
                            throws AllocationError

Removes @socket from the multicast group defined by @group, @iface,
and @source_specific (which must all have the same values they had
when you joined the group).

@socket remains bound to its address and port, and can still receive
unicast messages after calling this.

To unbind to a given source-specific multicast address, use
g_socket_leave_multicast_group_ssm() instead.

Parameters:

group - a #GInetAddress specifying the group address to leave.

source_specific - %TRUE if source-specific multicast was used

iface - Interface used

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

leaveMulticastGroupSsm

public boolean leaveMulticastGroupSsm(@Nonnull
 InetAddress group,
 @Nullable
 InetAddress source_specific,
 @Nullable
 Str iface)
                               throws AllocationError

Removes @socket from the multicast group defined by @group, @iface,
and @source_specific (which must all have the same values they had
when you joined the group).

@socket remains bound to its address and port, and can still receive
unicast messages after calling this.

Parameters:

group - a #GInetAddress specifying the group address to leave.

source_specific - a #GInetAddress specifying the source-specific multicast address or %NULL to ignore.

iface - Name of the interface to use, or %NULL

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

leaveMulticastGroupSsm

public boolean leaveMulticastGroupSsm(@Nonnull
 InetAddress group,
 @Nullable
 InetAddress source_specific,
 String iface)
                               throws AllocationError

Removes @socket from the multicast group defined by @group, @iface,
and @source_specific (which must all have the same values they had
when you joined the group).

@socket remains bound to its address and port, and can still receive
unicast messages after calling this.

Parameters:

group - a #GInetAddress specifying the group address to leave.

source_specific - a #GInetAddress specifying the source-specific multicast address or %NULL to ignore.

iface - Name of the interface to use, or %NULL

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

listen

public boolean listen()
               throws AllocationError

Marks the socket as a server socket, i.e. a socket that is used
to accept incoming requests using g_socket_accept().

Before calling this the socket must be bound to a local address using
g_socket_bind().

To set the maximum amount of outstanding clients, use
g_socket_set_listen_backlog().

Returns:

%TRUE on success, %FALSE on error.

Throws:

AllocationError

receive

public long receive(@Nonnull
 Str buffer,
 long size,
 @Nullable
 Cancellable cancellable)
             throws AllocationError

Receive data (up to @size bytes) from a socket. This is mainly used by
connection-oriented sockets; it is identical to g_socket_receive_from()
with @address set to %NULL.

For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
g_socket_receive() will always read either 0 or 1 complete messages from
the socket. If the received message is too large to fit in @buffer, then
the data beyond @size bytes will be discarded, without any explicit
indication that this has occurred.

For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
number of bytes, up to @size. If more than @size bytes have been
received, the additional data will be returned in future calls to
g_socket_receive().

If the socket is in blocking mode the call will block until there
is some data to receive, the connection is closed, or there is an
error. If there is no data available and the socket is in
non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
returned. To be notified when data is available, wait for the
%G_IO_IN condition.

On error -1 is returned and @error is set accordingly.

Parameters:

buffer - a buffer to read data into (which should be at least @size bytes long).

size - the number of bytes you want to read from the socket

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error

Throws:

AllocationError

receiveWithBlocking

public long receiveWithBlocking(@Nonnull
 Str buffer,
 long size,
 boolean blocking,
 @Nullable
 Cancellable cancellable)
                         throws AllocationError

This behaves exactly the same as g_socket_receive(), except that
the choice of blocking or non-blocking behavior is determined by
the @blocking argument rather than by @socket's properties.

Parameters:

buffer - a buffer to read data into (which should be at least @size bytes long).

size - the number of bytes you want to read from the socket

blocking - whether to do blocking or non-blocking I/O

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error

Throws:

AllocationError

send

public long send(@Nonnull
 Str buffer,
 long size,
 @Nullable
 Cancellable cancellable)
          throws AllocationError

Tries to send @size bytes from @buffer on the socket. This is
mainly used by connection-oriented sockets; it is identical to
g_socket_send_to() with @address set to %NULL.

If the socket is in blocking mode the call will block until there is
space for the data in the socket queue. If there is no space available
and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
will be returned. To be notified when space is available, wait for the
%G_IO_OUT condition. Note though that you may still receive
%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
notified of a %G_IO_OUT condition. (On Windows in particular, this is
very common due to the way the underlying APIs work.)

On error -1 is returned and @error is set accordingly.

Parameters:

buffer - the buffer containing the data to send.

size - the number of bytes to send

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes written (which may be less than @size), or -1 on error

Throws:

AllocationError

send

public long send(String buffer,
 long size,
 @Nullable
 Cancellable cancellable)
          throws AllocationError

Tries to send @size bytes from @buffer on the socket. This is
mainly used by connection-oriented sockets; it is identical to
g_socket_send_to() with @address set to %NULL.

If the socket is in blocking mode the call will block until there is
space for the data in the socket queue. If there is no space available
and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
will be returned. To be notified when space is available, wait for the
%G_IO_OUT condition. Note though that you may still receive
%G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
notified of a %G_IO_OUT condition. (On Windows in particular, this is
very common due to the way the underlying APIs work.)

On error -1 is returned and @error is set accordingly.

Parameters:

buffer - the buffer containing the data to send.

size - the number of bytes to send

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes written (which may be less than @size), or -1 on error

Throws:

AllocationError

sendTo

public long sendTo(@Nullable
 SocketAddress address,
 @Nonnull
 Str buffer,
 long size,
 @Nullable
 Cancellable cancellable)
            throws AllocationError

Tries to send @size bytes from @buffer to @address. If @address is
%NULL then the message is sent to the default receiver (set by
g_socket_connect()).

See g_socket_send() for additional information.

Parameters:

address - a #GSocketAddress, or %NULL

buffer - the buffer containing the data to send.

size - the number of bytes to send

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes written (which may be less than @size), or -1 on error

Throws:

AllocationError

sendTo

public long sendTo(@Nullable
 SocketAddress address,
 String buffer,
 long size,
 @Nullable
 Cancellable cancellable)
            throws AllocationError

Tries to send @size bytes from @buffer to @address. If @address is
%NULL then the message is sent to the default receiver (set by
g_socket_connect()).

See g_socket_send() for additional information.

Parameters:

address - a #GSocketAddress, or %NULL

buffer - the buffer containing the data to send.

size - the number of bytes to send

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes written (which may be less than @size), or -1 on error

Throws:

AllocationError

sendWithBlocking

public long sendWithBlocking(@Nonnull
 Str buffer,
 long size,
 boolean blocking,
 @Nullable
 Cancellable cancellable)
                      throws AllocationError

This behaves exactly the same as g_socket_send(), except that
the choice of blocking or non-blocking behavior is determined by
the @blocking argument rather than by @socket's properties.

Parameters:

buffer - the buffer containing the data to send.

size - the number of bytes to send

blocking - whether to do blocking or non-blocking I/O

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes written (which may be less than @size), or -1 on error

Throws:

AllocationError

sendWithBlocking

public long sendWithBlocking(String buffer,
 long size,
 boolean blocking,
 @Nullable
 Cancellable cancellable)
                      throws AllocationError

This behaves exactly the same as g_socket_send(), except that
the choice of blocking or non-blocking behavior is determined by
the @blocking argument rather than by @socket's properties.

Parameters:

buffer - the buffer containing the data to send.

size - the number of bytes to send

blocking - whether to do blocking or non-blocking I/O

cancellable - a %GCancellable or %NULL

Returns:

Number of bytes written (which may be less than @size), or -1 on error

Throws:

AllocationError

setBlocking

public void setBlocking(boolean blocking)

Sets the blocking mode of the socket. In blocking mode
all operations (which don’t take an explicit blocking parameter) block until
they succeed or there is an error. In
non-blocking mode all functions return results immediately or
with a %G_IO_ERROR_WOULD_BLOCK error.

All sockets are created in blocking mode. However, note that the
platform level socket is always non-blocking, and blocking mode
is a GSocket level feature.

Parameters:

blocking - Whether to use blocking I/O or not.

setBroadcast

public void setBroadcast(boolean broadcast)

Sets whether @socket should allow sending to broadcast addresses.
This is %FALSE by default.

Parameters:

broadcast - whether @socket should allow sending to broadcast addresses

setKeepalive

public void setKeepalive(boolean keepalive)

Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
this flag is set on a socket, the system will attempt to verify that the
remote socket endpoint is still present if a sufficiently long period of
time passes with no data being exchanged. If the system is unable to
verify the presence of the remote endpoint, it will automatically close
the connection.

This option is only functional on certain kinds of sockets. (Notably,
%G_SOCKET_PROTOCOL_TCP sockets.)

The exact time between pings is system- and protocol-dependent, but will
normally be at least two hours. Most commonly, you would set this flag
on a server socket if you want to allow clients to remain idle for long
periods of time, but also want to ensure that connections are eventually
garbage-collected if clients crash or become unreachable.

Parameters:

keepalive - Value for the keepalive flag

setListenBacklog

public void setListenBacklog(int backlog)

Sets the maximum number of outstanding connections allowed
when listening on this socket. If more clients than this are
connecting to the socket and the application is not handling them
on time then the new connections will be refused.

Note that this must be called before g_socket_listen() and has no
effect if called after that.

Parameters:

backlog - the maximum number of pending connections.

setMulticastLoopback

public void setMulticastLoopback(boolean loopback)

Sets whether outgoing multicast packets will be received by sockets
listening on that multicast address on the same host. This is %TRUE
by default.

Parameters:

loopback - whether @socket should receive messages sent to its multicast groups from the local host

setMulticastTtl

public void setMulticastTtl(int ttl)

Sets the time-to-live for outgoing multicast datagrams on @socket.
By default, this is 1, meaning that multicast packets will not leave
the local network.

Parameters:

ttl - the time-to-live value for all multicast datagrams on @socket

setOption

public boolean setOption(int level,
 int optname,
 int value)
                  throws AllocationError

Sets the value of an integer-valued option on @socket, as with
setsockopt(). (If you need to set a non-integer-valued option,
you will need to call setsockopt() directly.)

The [<gio/gnetworking.h>][gio-gnetworking.h]
header pulls in system headers that will define most of the
standard/portable socket options. For unusual socket protocols or
platform-dependent options, you may need to include additional
headers.

Parameters:

level - the "API level" of the option (eg, `SOL_SOCKET`)

optname - the "name" of the option (eg, `SO_BROADCAST`)

value - the value to set the option to

Returns:

success or failure. On failure, @error will be set, and the system error value (`errno` or WSAGetLastError()) will still be set to the result of the setsockopt() call.

Throws:

AllocationError

setTimeout

public void setTimeout(int timeout)

Sets the time in seconds after which I/O operations on @socket will
time out if they have not yet completed.

On a blocking socket, this means that any blocking #GSocket
operation will time out after @timeout seconds of inactivity,
returning %G_IO_ERROR_TIMED_OUT.

On a non-blocking socket, calls to g_socket_condition_wait() will
also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
created with g_socket_create_source() will trigger after
@timeout seconds of inactivity, with the requested condition
set, at which point calling g_socket_receive(), g_socket_send(),
g_socket_check_connect_result(), etc, will fail with
%G_IO_ERROR_TIMED_OUT.

If @timeout is 0 (the default), operations will never time out
on their own.

Note that if an I/O operation is interrupted by a signal, this may
cause the timeout to be reset.

Parameters:

timeout - the timeout for @socket, in seconds, or 0 for none

setTtl

public void setTtl(int ttl)

Sets the time-to-live for outgoing unicast packets on @socket.
By default the platform-specific default value is used.

Parameters:

ttl - the time-to-live value for all unicast packets on @socket

shutdown

public boolean shutdown(boolean shutdown_read,
 boolean shutdown_write)
                 throws AllocationError

Shut down part or all of a full-duplex connection.

If @shutdown_read is %TRUE then the receiving side of the connection
is shut down, and further reading is disallowed.

If @shutdown_write is %TRUE then the sending side of the connection
is shut down, and further writing is disallowed.

It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.

One example where it is useful to shut down only one side of a connection is
graceful disconnect for TCP connections where you close the sending side,
then wait for the other side to close the connection, thus ensuring that the
other side saw all sent data.

Parameters:

shutdown_read - whether to shut down the read side

shutdown_write - whether to shut down the write side

Returns:

%TRUE on success, %FALSE on error

Throws:

AllocationError

speaksIpv4

public boolean speaksIpv4()

Checks if a socket is capable of speaking IPv4.

IPv4 sockets are capable of speaking IPv4. On some operating systems
and under some combinations of circumstances IPv6 sockets are also
capable of speaking IPv4. See RFC 3493 section 3.7 for more
information.

No other types of sockets are currently considered as being capable
of speaking IPv4.

Returns:

%TRUE if this socket can be used with IPv4.

asDatagramBased

public DatagramBased asDatagramBased()

Implements interface DatagramBased. Call this to get access to interface functions.

Returns:

DatagramBased

asInitable

public Initable asInitable()

Implements interface Initable. Call this to get access to interface functions.

Returns:

Initable

getTypeID

public static long getTypeID()

getParentTypeID

public static long getParentTypeID()

getTypeSize

public static TypeSystem.TypeSize getTypeSize()

getParentTypeSize

public static TypeSystem.TypeSize getParentTypeSize()

getInstanceSize

public static int getInstanceSize()