# Gio::Socket Class Reference

Low-level socket object. More...

Inherits Glib::Object, and Gio::Initable.

Collaboration diagram for Gio::Socket:
[legend]

List of all members.

## Public Member Functions

virtual | ~Socket ()
GSocket* | gobj ()
| Provides access to the underlying C GObject.
const GSocket* | gobj () const
| Provides access to the underlying C GObject.
GSocket* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void | bind (const Glib::RefPtr< SocketAddress >& address, bool allow_reuse)
| When a socket is created it is attached to an address family, but it doesn't have an address in this family.
void | listen ()
| Marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using g_socket_accept().
Glib::RefPtr< Socket > | accept (const Glib::RefPtr< Cancellable >& cancellable)
| Accept incoming connections on a connection-based socket.
Glib::RefPtr< Socket > | accept ()
void | connect (const Glib::RefPtr< SocketAddress >& address, const Glib::RefPtr< Cancellable >& cancellable)
| Connect the socket to the specified remote address.
void | connect (const Glib::RefPtr< SocketAddress >& address)
void | check_connect_result ()
gssize | receive (char* buffer, gsize size, const Glib::RefPtr< Cancellable >& cancellable)
| Receive data (up to size bytes) from a socket.
gssize | receive (char* buffer, gsize size)
gssize | send (const gchar* buffer, gsize size, const Glib::RefPtr< Cancellable >& cancellable)
| Tries to send size bytes from buffer on the socket.
gssize | send (const gchar* buffer, gsize size)
gssize | send_to (const Glib::RefPtr< SocketAddress >& address, const char* buffer, gsize size, const Glib::RefPtr< Cancellable >& cancellable)
| Send data to address on socket.
gssize | send_to (const Glib::RefPtr< SocketAddress >& address, const char* buffer, gsize size)
void | close ()
| Closes the socket, shutting down any active connection.
bool | is_closed ()
| Checks whether a socket is closed.
void | shutdown (bool shutdown_read, bool shutdown_write)
bool | is_connected ()
| Check whether the socket is connected.
Glib::IOCondition | condition_check (Glib::IOCondition condition)
| Checks on the readiness of socket to perform operations.
void | condition_wait (Glib::IOCondition condition, const Glib::RefPtr< Cancellable >& cancellable)
| Waits for condition to become true on socket.
void | condition_wait (Glib::IOCondition condition)
void | set_listen_backlog (int backlog)
| Sets the maximum number of outstanding connections allowed when listening on this socket.
int | get_listen_backlog () const
| Gets the listen backlog setting of the socket.
void | set_blocking (bool blocking)
| Sets the blocking mode of the socket.
bool | get_blocking () const
| Gets the blocking mode of the socket.
void | set_keepalive (bool keepalive)
| Setting keepalive to `true` enables the sending of periodic ping requests on idle connections in order to keep the connection alive.
bool | get_keepalive () const
| Gets the keepalive mode of the socket.
SocketFamily | get_family () const
| Gets the socket family of the socket.
int | get_fd () const
| Returns: the file descriptor of the socket.
Glib::RefPtr< SocketAddress > | get_local_address () const
| Try to get the local address of a bound socket.
Glib::RefPtr< SocketAddress > | get_remote_address () const
| Try to get the remove address of a connected socket.
SocketProtocol | get_protocol () const
SocketType | get_socket_type () const
| Gets the socket type of the socket.
bool | speaks_ipv4 () const
Glib::PropertyProxy< bool > | property_blocking ()
| Whether or not I/O on this socket is blocking.
Glib::PropertyProxy_ReadOnly < bool > | property_blocking () const
| Whether or not I/O on this socket is blocking.
Glib::PropertyProxy_ReadOnly < SocketFamily > | property_family () const
| The sockets address family.
Glib::PropertyProxy_ReadOnly< int > | property_fd () const
| The sockets file descriptor.
Glib::PropertyProxy< bool > | property_keepalive ()
| Keep connection alive by sending periodic pings.
Glib::PropertyProxy_ReadOnly < bool > | property_keepalive () const
| Keep connection alive by sending periodic pings.
Glib::PropertyProxy< int > | property_listen_backlog ()
| Outstanding connections in the listen queue.
Glib::PropertyProxy_ReadOnly< int > | property_listen_backlog () const
| Outstanding connections in the listen queue.
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< SocketAddress > > | property_local_address () const
| The local address the socket is bound to.
Glib::PropertyProxy_ReadOnly < Glib::RefPtr< SocketAddress > > | property_remote_address () const
| The remote address the socket is connected to.
Glib::PropertyProxy_ReadOnly < SocketProtocol > | property_protocol () const
| The id of the protocol to use.
Glib::PropertyProxy_ReadOnly < SocketType > | property_type () const
| The sockets type.

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr< Gio::Socket > | wrap (GSocket* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

Low-level socket object.

A Socket 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.

Socket 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 SocketClient, SocketService and SocketConnection. However there may be cases where direct use of Socket is useful.

(FIXME: update this doc for giomm) Socket implements the Initable 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 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 condition_check(), or condition_wait(). You can also use create_source() and attach it to a Glib::MainContext 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 Socket.

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.

Sockets 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 Socket causes the signal SIGPIPE to be ignored for the remainder of the program. If you are writing a command-line utility that uses Socket, 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.

Since glibmm 2.22:

## Constructor & Destructor Documentation

virtual Gio::Socket::~Socket | ( |  | ) | `[virtual]`

## Member Function Documentation

Glib::RefPtr<Socket> Gio::Socket::accept | ( |  | ) |

Glib::RefPtr<Socket> Gio::Socket::accept | ( | const Glib::RefPtr< Cancellable >& | cancellable | ) |

Accept incoming connections on a connection-based socket.

This removes the first outstanding connection request from the listening socket and creates a Socket 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 IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. To be notified of an incoming connection, wait for the IO_IN condition.

Returns:
  A new Socket, or `0` on error. Free the returned object with Glib::object_unref().

Since glibmm 2.22:

void Gio::Socket::bind | ( | const Glib::RefPtr< SocketAddress >& | address,
|  | bool | 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.

It is generally required to bind to a local address before you can receive connections. (See g_socket_listen() and g_socket_accept() ).

If allow_reuse is `true` this allows the bind call to succeed in some situation where it would otherwise return a IO_ERROR_ADDRESS_IN_USE error. The main example is for a TCP server socket where there are outstanding connections in the WAIT state, which are generally safe to ignore. However, setting it to `true` doesn't mean the call will succeed if there is a socket actively bound to the address.

In general, pass `true` if the socket will be used to accept connections, otherwise pass `false`.

Parameters:

  | address | A SocketAddress specifying the local address.
  | allow_reuse | Whether to allow reusing this address.

Returns:
  `true` on success, `false` on error.

Since glibmm 2.22:

void Gio::Socket::check_connect_result | ( |  | ) |

void Gio::Socket::close | ( |  | ) |

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 IO_ERROR_CLOSED. Closing a stream 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.

Returns:
  `true` on success, `false` on error

Since glibmm 2.22:

Glib::IOCondition Gio::Socket::condition_check | ( | Glib::IOCondition | 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.

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

This call never blocks.

Parameters:

  | condition | A IOCondition mask to check.

Returns:
  The GIOCondition mask of the current state

Since glibmm 2.22:

void Gio::Socket::condition_wait | ( | Glib::IOCondition | condition | ) |

void Gio::Socket::condition_wait | ( | Glib::IOCondition | condition,
|  | const Glib::RefPtr< Cancellable >& | cancellable |
| ) |  |  |

Waits for condition to become true on socket.

When the condition becomes true, `true` is returned.

If cancellable is cancelled before the condition becomes true then `false` is returned and error, if non-`0`, is set to IO_ERROR_CANCELLED.

Parameters:

  | condition | A IOCondition mask to wait for.
  | cancellable | A Cancellable, or `0`.

Returns:
  `true` if the condition was met, `false` otherwise

Since glibmm 2.22:

void Gio::Socket::connect | ( | const Glib::RefPtr< SocketAddress >& | address | ) |

void Gio::Socket::connect | ( | const Glib::RefPtr< SocketAddress >& | address,
|  | const Glib::RefPtr< Cancellable >& | cancellable |
| ) |  |  |

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 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 can then be checked with Glib::socket_check_pending_error().

Parameters:

  | address | A SocketAddress specifying the remote address.

Returns:
  `true` if connected, `false` on error.

Since glibmm 2.22:

bool Gio::Socket::get_blocking | ( |  | ) | const

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.

Since glibmm 2.22:

SocketFamily Gio::Socket::get_family | ( |  | ) | const

Gets the socket family of the socket.

Returns:
  A SocketFamily

Since glibmm 2.22:

int Gio::Socket::get_fd | ( |  | ) | const

Returns: the file descriptor of the socket.

Returns:
  The file descriptor of the socket.

Since glibmm 2.22:

bool Gio::Socket::get_keepalive | ( |  | ) | const

Gets the keepalive mode of the socket.

For details on this, see g_socket_set_keepalive().

Returns:
  `true` if keepalive is active, `false` otherwise.

Since glibmm 2.22:

int Gio::Socket::get_listen_backlog | ( |  | ) | const

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.

Since glibmm 2.22:

Glib::RefPtr<SocketAddress> Gio::Socket::get_local_address | ( |  | ) | const

Try to get the local address of a bound socket.

This is only useful if the socket has been bound to a local address.

Returns:
  A SocketAddress or `0` on error.

Since glibmm 2.22:

SocketProtocol Gio::Socket::get_protocol | ( |  | ) | const

Glib::RefPtr<SocketAddress> Gio::Socket::get_remote_address | ( |  | ) | const

Try to get the remove address of a connected socket.

This is only useful for connection oriented sockets that have been connected.

Returns:
  A SocketAddress or `0` on error.

Since glibmm 2.22:

SocketType Gio::Socket::get_socket_type | ( |  | ) | const

Gets the socket type of the socket.

Returns:
  A SocketType

Since glibmm 2.22:

const GSocket* Gio::Socket::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GObject.

Reimplemented from Gio::Initable.

GSocket* Gio::Socket::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GObject.

Reimplemented from Gio::Initable.

GSocket* Gio::Socket::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

bool Gio::Socket::is_closed | ( |  | ) |

Checks whether a socket is closed.

Returns:
  `true` if socket is closed, `false` otherwise

Since glibmm 2.22:

bool Gio::Socket::is_connected | ( |  | ) |

Check whether the socket is connected.

This is only useful for connection-oriented sockets.

Returns:
  `true` if socket is connected, `false` otherwise.

Since glibmm 2.22:

void Gio::Socket::listen | ( |  | ) |

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().

Returns:
  `true` on success, `false` on error.

Since glibmm 2.22:

Glib::PropertyProxy_ReadOnly<bool> Gio::Socket::property_blocking | ( |  | ) | const

Whether or not I/O on this socket is blocking.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Gio::Socket::property_blocking | ( |  | ) |

Whether or not I/O on this socket is blocking.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<SocketFamily> Gio::Socket::property_family | ( |  | ) | const

The sockets address family.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<int> Gio::Socket::property_fd | ( |  | ) | const

The sockets file descriptor.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Gio::Socket::property_keepalive | ( |  | ) | const

Keep connection alive by sending periodic pings.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Gio::Socket::property_keepalive | ( |  | ) |

Keep connection alive by sending periodic pings.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<int> Gio::Socket::property_listen_backlog | ( |  | ) | const

Outstanding connections in the listen queue.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<int> Gio::Socket::property_listen_backlog | ( |  | ) |

Outstanding connections in the listen queue.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<SocketAddress> > Gio::Socket::property_local_address | ( |  | ) | const

The local address the socket is bound to.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<SocketProtocol> Gio::Socket::property_protocol | ( |  | ) | const

The id of the protocol to use.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly< Glib::RefPtr<SocketAddress> > Gio::Socket::property_remote_address | ( |  | ) | const

The remote address the socket is connected to.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<SocketType> Gio::Socket::property_type | ( |  | ) | const

The sockets type.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

gssize Gio::Socket::receive | ( | char * | buffer,
|  | gsize | size |
| ) |  |  |

gssize Gio::Socket::receive | ( | char * | buffer,
|  | gsize | size,
|  | const Glib::RefPtr< Cancellable >& | cancellable |
| ) |  |  |

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 `0`.

If a message is too long to fit in buffer, excess bytes may be discarded depending on the type of socket the message is received from.

If the socket is in blocking mode the call will block until there is some data to receive or there is an error. If there is no data available and the socket is in non-blocking mode a IO_ERROR_WOULD_BLOCK error will be returned. To be notified of available data, wait for the 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 count bytes long).
  | size | The number of bytes that will be read from the stream.

Returns:
  Number of bytes read, or -1 on error

Since glibmm 2.22:

gssize Gio::Socket::send | ( | const gchar * | buffer,
|  | gsize | size |
| ) |  |  |

gssize Gio::Socket::send | ( | const gchar * | buffer,
|  | gsize | size,
|  | const Glib::RefPtr< Cancellable >& | cancellable |
| ) |  |  |

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 `0`.

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 IO_ERROR_WOULD_BLOCK error will be returned. To be notified of available space, wait for the IO_OUT condition.

Note that on Windows you can't rely on a IO_OUT condition not producing a IO_ERROR_WOULD_BLOCK error, as this is how Winsock write notification works. However, robust apps should always be able to handle this since it can easily appear in other cases too.

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.

Returns:
  Number of bytes read, or -1 on error

Since glibmm 2.22:

gssize Gio::Socket::send_to | ( | const Glib::RefPtr< SocketAddress >& | address,
|  | const char * | buffer,
|  | gsize | size |
| ) |  |  |

gssize Gio::Socket::send_to | ( | const Glib::RefPtr< SocketAddress >& | address,
|  | const char * | buffer,
|  | gsize | size,
|  | const Glib::RefPtr< Cancellable >& | cancellable |
| ) |  |  |

Send data to address on socket.

This is the most complicated and fully-featured version of this call. For easier use, see g_socket_send() and g_socket_send_to().

If address is `0` then the message is sent to the default receiver (set by g_socket_connect()).

vector must point to an array of OutputVector structs and num_vectors must be the length of this array. These structs describe the buffers that the sent data will be gathered from. If num_vector is -1, then vector is assumed to be terminated by a OutputVector with a `0` buffer pointer.

messages, if non-`0`, is taken to point to an array of num_messages SocketControlMessage instances. These correspond to the control messages to be sent on the socket. If num_messages is -1 then messages is treated as a `0`-terminated array.

flags modify how the message sent. The commonly available arguments for this is available in the SocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system specific flags too.

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 IO_ERROR_WOULD_BLOCK error will be returned. To be notified of available space, wait for the IO_OUT condition.

Note that on Windows you can't rely on a IO_OUT condition not producing a IO_ERROR_WOULD_BLOCK error, as this is how Winsock write notification works. However, robust apps should always be able to handle this since it can easily appear in other cases too.

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

Parameters:

  | address | A SocketAddress, or `0`.
  | vectors | An array of OutputVector structs.
  | num_vectors | The number of elements in vectors, or -1.
  | messages | A pointer to an array of SocketControlMessages, or `0`.
  | num_messages | Number of elements in messages, or -1.
  | flags | An int containing SocketMsgFlags flags.

Returns:
  Number of bytes read, or -1 on error

Since glibmm 2.22:

void Gio::Socket::set_blocking | ( | bool | blocking | ) |

Sets the blocking mode of the socket.

In blocking mode all operations block until they succeed or there is an error. In non-blocking mode all functions return results immediately or with a 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.

Since glibmm 2.22:

Parameters:

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

void Gio::Socket::set_keepalive | ( | bool | keepalive | ) |

Setting keepalive to `true` enables the sending of periodic ping requests on idle connections in order to keep the connection alive.

This is only useful for connection oriented sockets. The exact period used between each ping is system and protocol dependent.

Sending keepalive requests like this has a few disadvantages. For instance, it uses more network bandwidth, and it makes your application more sensitive to temporary outages in the network (i.e. if a cable is pulled your otherwise idle connection could be terminated, whereas otherwise it would survive unless actually used before the cable was reinserted). However, it is sometimes useful to ensure that connections are eventually terminated if e.g. the remote side is disconnected, so as to avoid leaking resources forever.

Since glibmm 2.22:

Parameters:

  | keepalive | Whether to use try to keep the connection alive or not.

void Gio::Socket::set_listen_backlog | ( | 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.

Since glibmm 2.22:

Parameters:

  | backlog | The maximum number of pending connections.

void Gio::Socket::shutdown | ( | bool | shutdown_read,
|  | bool | shutdown_write |
| ) |  |  |

bool Gio::Socket::speaks_ipv4 | ( |  | ) | const

## Friends And Related Function Documentation

Glib::RefPtr< Gio::Socket > wrap | ( | GSocket * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- giomm/socket.h