mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-25 15:06:14 +01:00
docs: Move the GSocket SECTION
Move it to the struct docs. Signed-off-by: Philip Withnall <philip@tecnocode.co.uk> Helps: #3037
This commit is contained in:
parent
0b0179678a
commit
bd753fb87c
@ -83,46 +83,44 @@
|
||||
#endif
|
||||
|
||||
/**
|
||||
* SECTION:gsocket
|
||||
* @short_description: Low-level socket object
|
||||
* @include: gio/gio.h
|
||||
* @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
|
||||
* GSocket:
|
||||
*
|
||||
* A #GSocket is a low-level networking primitive. It is a more or less
|
||||
* 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
|
||||
* `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.
|
||||
* use it directly, but rather through classes like [class@Gio.SocketClient],
|
||||
* [class@Gio.SocketService] and [class@Gio.SocketConnection]. 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.
|
||||
* `GSocket` implements the [iface@Gio.Initable] interface, so if it is manually
|
||||
* constructed by e.g. [ctor@GObject.Object.new] you must call
|
||||
* [method@Gio.Initable.init] and check the results before using the object.
|
||||
* This is done automatically in [ctor@Gio.Socket.new] and
|
||||
* [ctor@Gio.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.
|
||||
* would block return immediately with a `G_IO_ERROR_WOULD_BLOCK` error.
|
||||
* To know when a call would successfully run you can call
|
||||
* [method@Gio.Socket.condition_check], or [method@Gio.Socket.condition_wait].
|
||||
* You can also use [method@Gio.Socket.create_source] and attach it to a
|
||||
* [type@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 GSocket.
|
||||
* 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
|
||||
* 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.
|
||||
* until a write returns `G_IO_ERROR_WOULD_BLOCK`.
|
||||
*
|
||||
* #GSockets can be either connection oriented or datagram based.
|
||||
* `GSocket`s 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
|
||||
@ -130,14 +128,14 @@
|
||||
*
|
||||
* All socket file descriptors are set to be close-on-exec.
|
||||
*
|
||||
* Note that creating a #GSocket causes the signal %SIGPIPE to be
|
||||
* 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
|
||||
* 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.
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* Since: 2.22
|
||||
|
Loading…
Reference in New Issue
Block a user