class: SocketClientMeta

[760:14] static extends: object

Generated metadata helpers for SocketClient class surfaces.

Methods

• properties ()

  Returns property metadata for SocketClient.

  • @r A list.

• signals ()

  Returns signal metadata for SocketClient.

  • @r A list.

class: SocketClient

[21:7] extends: object

GSocketClient is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type. You create a GSocketClient object, set any options you want, and then call a sync or async connect operation, which returns a [class@Gio.SocketConnection] subclass on success. The type of the [class@Gio.SocketConnection] object returned depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection]. As GSocketClient is a lightweight object, you don't need to cache it. You can just create a new one any time you need one.

Members

• handleObj
• lib
• retainedCallbacks
• signalHandlerNames
• signalSetterHandlers

Methods

• SocketClient ()

  Creates a new #GSocketClient with the default options.

• toNativeHandle (Source)

  Normalizes a constructor argument into a raw pointer carrier. Accepts a raw NativeHandle, a raw NativeBuffer returned from fn.call(...), another generated wrapper exposing handle(), or null. Returns null when the argument carries no pointer.

  • @p Source is the raw handle, raw buffer, wrapper, or null.
  • @r A raw pointer carrier or null when no pointer is present.

• getLib ()

  Returns the opened native library for this generated wrapper.

  • @r The opened native library.

• handle ()

  Returns the wrapped NativeHandle.

  • @r The wrapped NativeHandle.

• isNull ()

  Returns true when the wrapped handle is null.

  • @r A bool.

• describe ()

  Returns a small string for debugging generated wrappers.

  • @r A string.

• asObject ()

  Wraps this handle as Object.

  • @r A Object object.

• connectSignal (string Name, CallbackObj)

  Connects one generated callback wrapper to a named signal.

  • @p Name is the signal name.
  • @p CallbackObj is the generated callback wrapper to connect.
  • @r The connected handler id.

• disconnectSignalHandler (int HandlerId)

  Disconnects one retained signal handler id.

  • @p HandlerId is the signal handler id to disconnect.
  • @r None.

• setOnEvent (callback Fn, UserData = null)

  Emitted when @client's activity on @connectable changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different @event values are as follows: - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up

  • @connectable in DNS. @connection will be %NULL. - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved @connectable in DNS. @connection will be %NULL. - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection to a remote host; either a proxy server or the destination server itself. @connection is the #GSocketConnection, which is not yet connected. Since GLib 2.40, you can access the remote address via g_socket_connection_get_remote_address(). - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected to a remote host. @connection is the connected #GSocketConnection. - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate with a proxy to get it to connect to @connectable. @connection is the #GSocketConnection to the proxy server. - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a connection to
  • @connectable through a proxy server. @connection is the stream returned from g_proxy_connect(), which may or may not be a #GSocketConnection. - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS handshake. @connection is a #GTlsClientConnection. - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed the TLS handshake. @connection is a #GTlsClientConnection. - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected to
  • @connectable (in which case @connection is the #GSocketConnection that it will be returning to the caller) or has failed (in which case @connection is %NULL and the client is about to return an error). Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted multiple times (or not at all) for a given connectable (in particular, if @client ends up attempting to connect to more than one address). However, if @client emits the #GSocketClient::event signal at all for a given connectable, then it will always emit it with %G_SOCKET_CLIENT_COMPLETE when it is done. Note that there may be additional #GSocketClientEvent values in the future; unrecognized @event values should be ignored.
  • @p Fn is the Aussom callback.
  • @p Fn is called with (SocketClient Self, string Event, SocketConnectable Connectable, IOStream Connection).
  • @p UserData is retained and passed through to the generated callback wrapper when provided.
  • @r The connected handler id.

• getProperty (string Name)

  Reads one generated property by name.

• setProperty (string Name, Value)

  Writes one generated property by name.

• setEnableproxy (bool Value)

  Enable proxy support.

  • @p Value is the new property value.
  • @r None.

• setFamily (string Value)

  The address family to use for socket construction.

  • @p Value is the new property value.
  • @r None.

• setLocaladdress (object Value)

  The local address constructed sockets will be bound to.

  • @p Value is the new property value.
  • @r None.

• setProtocol (string Value)

  The protocol to use for socket construction, or 0 for default.

  • @p Value is the new property value.
  • @r None.

• setProxyresolver (object Value)

  The proxy resolver to use

  • @p Value is the new property value.
  • @r None.

• setTimeout (int Value)

  The I/O timeout for sockets, in seconds, or 0 for none.

  • @p Value is the new property value.
  • @r None.

• setTls (bool Value)

  Whether to create TLS connections.

  • @p Value is the new property value.
  • @r None.

• setTlsvalidationflags (string Value)

  The TLS validation flags used when creating TLS connections. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Therefore, there is no safe way to use this property. This is not a horrible problem, though, because you should not be attempting to ignore validation errors anyway. If you really must ignore TLS certificate errors, connect to the #GSocketClient::event signal, wait for it to be emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, and use that to connect to #GTlsConnection::accept-certificate.

  • @p Value is the new property value.
  • @r None.

• setType (string Value)

  The type to use for socket construction.

  • @p Value is the new property value.
  • @r None.

• add_application_proxy (string protocol)

  Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the #GProxyResolver, #GSocketClient will consider this protocol as supported but will not try to find a #GProxy instance to handle handshaking. The application must check for this case by calling g_socket_connection_get_remote_address() on the returned #GSocketConnection, and seeing if it's a #GProxyAddress of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself. This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method. When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake.

  • @p protocol is The proxy protocol.
  • @r None.

• connect (object connectable, object cancellable)

  Tries to resolve the @connectable and make a network connection to it. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. The type of the #GSocketConnection object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a #GTcpConnection. The socket created will be the same family as the address that the

  • @connectable resolves to, unless family is set with g_socket_client_set_family() or indirectly via g_socket_client_set_local_address(). The socket type defaults to %G_SOCKET_TYPE_STREAM but can be set with g_socket_client_set_socket_type(). If a local address is specified with g_socket_client_set_local_address() the socket will be bound to this address before connecting.
  • @p connectable is a #GSocketConnectable specifying the remote address..
  • @p cancellable is optional #GCancellable object, %NULL to ignore..

• connect_finish (object result)

  Finishes an async connect operation. See g_socket_client_connect_async()

  • @p result is a #GAsyncResult..

• connect_to_host_finish (object result)

  Finishes an async connect operation. See g_socket_client_connect_to_host_async()

  • @p result is a #GAsyncResult..

• connect_to_service (string domain, string service, object cancellable)

  Attempts to create a TCP connection to a service. This call looks up the SRV record for @service at @domain for the "tcp" protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining. Upon a successful connection, a new #GSocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it. In the event of any failure (DNS error, service not found, no hosts connectable) %NULL is returned and @error (if non-%NULL) is set accordingly.

  • @p domain is a domain name.
  • @p service is the name of the service to connect to.
  • @p cancellable is a #GCancellable, or %NULL.

• connect_to_service_finish (object result)

  Finishes an async connect operation. See g_socket_client_connect_to_service_async()

  • @p result is a #GAsyncResult..

• connect_to_uri_finish (object result)

  Finishes an async connect operation. See g_socket_client_connect_to_uri_async()

  • @p result is a #GAsyncResult..

• get_enable_proxy ()

  Gets the proxy enable state; see g_socket_client_set_enable_proxy()

• get_family ()

  Gets the socket family of the socket client. See g_socket_client_set_family() for details.

• get_local_address ()

  Gets the local address of the socket client. See g_socket_client_set_local_address() for details.

• get_protocol ()

  Gets the protocol name type of the socket client. See g_socket_client_set_protocol() for details.

• get_proxy_resolver ()

  Gets the #GProxyResolver being used by @client. Normally, this will be the resolver returned by g_proxy_resolver_get_default(), but you can override it with g_socket_client_set_proxy_resolver().

• get_socket_type ()

  Gets the socket type of the socket client. See g_socket_client_set_socket_type() for details.

• get_timeout ()

  Gets the I/O timeout time for sockets created by @client. See g_socket_client_set_timeout() for details.

• get_tls ()

  Gets whether @client creates TLS connections. See g_socket_client_set_tls() for details.

• get_tls_validation_flags ()

  Gets the TLS validation flags used creating TLS connections via @client. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information.

• set_enable_proxy (bool enable)

  Sets whether or not @client attempts to make connections via a proxy server. When enabled (the default), #GSocketClient will use a #GProxyResolver to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation. See also g_socket_client_set_proxy_resolver().

  • @p enable is whether to enable proxies.
  • @r None.

• set_family (string family)

  Sets the socket family of the socket client. If this is set to something other than %G_SOCKET_FAMILY_INVALID then the sockets created by this object will be of the specified family. This might be useful for instance if you want to force the local connection to be an ipv4 socket, even though the address might be an ipv6 mapped to ipv4 address.

  • @p family is a #GSocketFamily.
  • @r None.

• set_local_address (object address)

  Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not %NULL) before connecting. This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface.

  • @p address is a #GSocketAddress, or %NULL.
  • @r None.

• set_protocol (string protocol)

  Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol. If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default protocol for the socket family and type.

  • @p protocol is a #GSocketProtocol.
  • @r None.

• set_proxy_resolver (object proxy_resolver)

  Overrides the #GProxyResolver used by @client. You can call this if you want to use specific proxies, rather than using the system default proxy settings. Note that whether or not the proxy resolver is actually used depends on the setting of #GSocketClient:enable-proxy, which is not changed by this function (but which is %TRUE by default)

  • @p proxy_resolver is a #GProxyResolver, or %NULL for the default..
  • @r None.

• set_socket_type (string type)

  Sets the socket type of the socket client. The sockets created by this object will be of the specified type. It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, as GSocketClient is used for connection oriented services.

  • @p type is a #GSocketType.
  • @r None.

• set_timeout (int timeout)

  Sets the I/O timeout for sockets created by @client. @timeout is a time in seconds, or 0 for no timeout (the default). The timeout value affects the initial connection attempt as well, so setting this may cause calls to g_socket_client_connect(), etc, to fail with %G_IO_ERROR_TIMED_OUT.

  • @p timeout is the timeout.
  • @r None.

• set_tls (bool tls)

  Sets whether @client creates TLS (aka SSL) connections. If @tls is %TRUE,

  • @client will wrap its connections in a #GTlsClientConnection and perform a TLS handshake when connecting. Note that since #GSocketClient must return a #GSocketConnection, but #GTlsClientConnection is not a #GSocketConnection, this actually wraps the resulting #GTlsClientConnection in a #GTcpWrapperConnection when returning it. You can use g_tcp_wrapper_connection_get_base_io_stream() on the return value to extract the #GTlsClientConnection. If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the #GTlsConnection::accept-certificate signal), you can connect to @client's #GSocketClient::event signal and wait for it to be emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you a chance to see the #GTlsClientConnection before the handshake starts.
  • @p tls is whether to use TLS.
  • @r None.

• set_tls_validation_flags (string flags)

  Sets the TLS validation flags used when creating TLS connections via

  • @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. This function does not work as originally designed and is impossible to use correctly. See #GSocketClient:tls-validation-flags for more information.
  • @p flags is the validation flags.
  • @r None.

class: SocketClientEventCallback

[687:7] extends: object

Generated low-level callback wrapper for GIR callback event.

Members

• callbackObj
• userFn
• userData
• hasUserData

Methods

• SocketClientEventCallback (callback Fn, UserData = null)

  Creates one native callback wrapper. The wrapper owns a trampoline that converts native pointers into generated wrapper objects before invoking Fn.

  • @p Fn is the Aussom callback implementation.
  • @p UserData is retained and passed through to Fn on each invocation when provided.

• trampoline (nativeSelf, event, connectable, connection, nativeUserData)

  Internal trampoline. Converts native pointer arguments into generated wrapper instances, then invokes the user's callback.

• callback ()

  Returns the wrapped NativeCallback.

• handle ()

  Returns the callback as a NativeHandle.

• close ()

  Closes the underlying NativeCallback.

• isClosed ()

  Returns true when the callback has been closed.