Description

Low-level socket object

Methods and Functions

gSocketNew(family, type, protocol, .errwarn = TRUE)
gSocketNewFromFd(fd, .errwarn = TRUE)
gSocketBind(object, address, allow.reuse, .errwarn = TRUE)
gSocketListen(object, .errwarn = TRUE)
gSocketAccept(object, cancellable = NULL, .errwarn = TRUE)
gSocketConnect(object, address, cancellable = NULL, .errwarn = TRUE)
gSocketCheckConnectResult(object, .errwarn = TRUE)
gSocketReceive(object, size, cancellable = NULL, .errwarn = TRUE)
gSocketReceiveFrom(object, size, cancellable = NULL, .errwarn = TRUE)
gSocketReceiveMessage(object, flags = 0, cancellable = NULL, .errwarn = TRUE)
gSocketSend(object, buffer, size, cancellable = NULL, .errwarn = TRUE)
gSocketSendTo(object, address, buffer, size, cancellable = NULL, .errwarn = TRUE)
gSocketSendMessage(object, address, vectors, messages = NULL, flags = 0, cancellable = NULL, .errwarn = TRUE)
gSocketClose(object, .errwarn = TRUE)
gSocketIsClosed(object)
gSocketShutdown(object, shutdown.read, shutdown.write, .errwarn = TRUE)
gSocketIsConnected(object)
gSocketCreateSource(object, condition, cancellable = NULL)
gSocketConditionCheck(object, condition)
gSocketConditionWait(object, condition, cancellable = NULL, .errwarn = TRUE)
gSocketSetListenBacklog(object, backlog)
gSocketGetListenBacklog(object)
gSocketGetBlocking(object)
gSocketSetBlocking(object, blocking)
gSocketGetKeepalive(object)
gSocketSetKeepalive(object, keepalive)
gSocketGetFamily(object)
gSocketGetFd(object)
gSocketGetLocalAddress(object, .errwarn = TRUE)
gSocketGetProtocol(object)
gSocketGetRemoteAddress(object, .errwarn = TRUE)
gSocketGetSocketType(object)
gSocketSpeaksIpv4(object)
gSocket(family, type, protocol, .errwarn = TRUE)

Hierarchy

Interfaces

GSocket implements GInitable.

Detailed Description

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. gObjectNew you must call gInitableInit and check the results before using the object. This is done automatically in gSocketNew and gSocketNewFromFd, so these functions can return NULL.

Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations 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 gSocketConditionCheck, or gSocketConditionWait. You can also use gSocketCreateSource 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.

Structures

GSocket

A lowlevel network socket object. Since 2.22

Convenient Construction

gSocket is the equivalent of gSocketNew.

Enums and Flags

GSocketType

Flags used when creating a GSocket. Some protocols may not implement all the socket types. Since 2.22

invalid

Type unknown or wrong

stream

Reliable connection-based byte streams (e.g. TCP).

datagram

Connectionless, unreliable datagram passing. (e.g. UDP)

seqpacket

Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP).

GSocketProtocol

A protocol identifier is specified when creating a GSocket, which is a family/type specific identifier, where 0 means the default protocol for the particular family/type.

This enum contains a set of commonly available and used protocols. You can also pass any other identifiers handled by the platform in order to use protocols not listed here. Since 2.22

unknown

The protocol type is unknown

default

The default protocol for the family/type

tcp

TCP over IP

udp

UDP over IP

sctp

SCTP over IP

User Functions

GSocketSourceFunc(socket, condition, user.data)

This is the function type of the callback used for the GSource returned by gSocketCreateSource. Since 2.22

socket

the GSocket

condition

the current condition at the source fired.

user.data

data passed in by the user.

Returns: [logical] it should return FALSE if the source should be removed.

Properties

blocking [logical : Read / Write]

Whether or not I/O on this socket is blocking. Default value: TRUE

family [GSocketFamily : Read / Write / Construct Only]

The sockets address family. Default value: G_SOCKET_FAMILY_INVALID

fd [integer : Read / Write / Construct Only]

The sockets file descriptor. Default value: -1

keepalive [logical : Read / Write]

Keep connection alive by sending periodic pings. Default value: FALSE

listen-backlog [integer : Read / Write]

Outstanding connections in the listen queue. Allowed values: [0,128] Default value: 10

local-address [GSocketAddress : * : Read]

The local address the socket is bound to.

protocol [GSocketProtocol : Read / Write / Construct Only]

The id of the protocol to use, or -1 for unknown. Default value: G_SOCKET_PROTOCOL_UNKNOWN

remote-address [GSocketAddress : * : Read]

The remote address the socket is connected to.

type [GSocketType : Read / Write / Construct Only]

The sockets type. Default value: G_SOCKET_TYPE_STREAM

Author(s)

Derived by RGtkGen from GTK+ documentation

References

https://developer.gnome.org/gio/stable/GSocket.html