SoupSocket

SoupSocket — A network socket

Synopsis




struct              SoupSocket;
SoupSocket*         soup_socket_new                     (const char *optname1,
                                                         ...);

void                (*SoupSocketCallback)               (SoupSocket *sock,
                                                         guint status,
                                                         gpointer user_data);
void                soup_socket_connect_async           (SoupSocket *sock,
                                                         GCancellable *cancellable,
                                                         SoupSocketCallback callback,
                                                         gpointer user_data);
guint               soup_socket_connect_sync            (SoupSocket *sock,
                                                         GCancellable *cancellable);

gboolean            soup_socket_listen                  (SoupSocket *sock);

gboolean            soup_socket_start_ssl               (SoupSocket *sock,
                                                         GCancellable *cancellable);
gboolean            soup_socket_start_proxy_ssl         (SoupSocket *sock,
                                                         const char *ssl_host,
                                                         GCancellable *cancellable);
gboolean            soup_socket_is_ssl                  (SoupSocket *sock);

void                soup_socket_disconnect              (SoupSocket *sock);
gboolean            soup_socket_is_connected            (SoupSocket *sock);

SoupAddress*        soup_socket_get_local_address       (SoupSocket *sock);
SoupAddress*        soup_socket_get_remote_address      (SoupSocket *sock);

enum                SoupSocketIOStatus;
SoupSocketIOStatus  soup_socket_read                    (SoupSocket *sock,
                                                         gpointer buffer,
                                                         gsize len,
                                                         gsize *nread,
                                                         GCancellable *cancellable,
                                                         GError **error);
SoupSocketIOStatus  soup_socket_read_until              (SoupSocket *sock,
                                                         gpointer buffer,
                                                         gsize len,
                                                         gconstpointer boundary,
                                                         gsize boundary_len,
                                                         gsize *nread,
                                                         gboolean *got_boundary,
                                                         GCancellable *cancellable,
                                                         GError **error);
SoupSocketIOStatus  soup_socket_write                   (SoupSocket *sock,
                                                         gconstpointer buffer,
                                                         gsize len,
                                                         gsize *nwrote,
                                                         GCancellable *cancellable,
                                                         GError **error);

#define             SOUP_SSL_ERROR
enum                SoupSSLError;

#define             SOUP_SOCKET_LOCAL_ADDRESS
#define             SOUP_SOCKET_REMOTE_ADDRESS
#define             SOUP_SOCKET_FLAG_NONBLOCKING
#define             SOUP_SOCKET_IS_SERVER
#define             SOUP_SOCKET_SSL_CREDENTIALS
#define             SOUP_SOCKET_ASYNC_CONTEXT
#define             SOUP_SOCKET_TIMEOUT


Object Hierarchy


  GObject
   +----SoupSocket

Properties


  "async-context"            gpointer              : Read / Write / Construct Only
  "is-server"                gboolean              : Read
  "local-address"            SoupAddress           : Read / Write / Construct Only
  "non-blocking"             gboolean              : Read / Write
  "remote-address"           SoupAddress           : Read / Write / Construct Only
  "ssl-creds"                gpointer              : Read / Write
  "timeout"                  guint                 : Read / Write

Signals


  "disconnected"                                   : Run Last
  "new-connection"                                 : Run First
  "readable"                                       : Run Last
  "writable"                                       : Run Last

Description

Details

struct SoupSocket

struct SoupSocket;


soup_socket_new ()

SoupSocket*         soup_socket_new                     (const char *optname1,
                                                         ...);

Creates a new (disconnected) socket

optname1 :

name of first property to set (or NULL)

... :

value of optname1, followed by additional property/value pairs

Returns :

the new socket

SoupSocketCallback ()

void                (*SoupSocketCallback)               (SoupSocket *sock,
                                                         guint status,
                                                         gpointer user_data);

The callback function passed to soup_socket_connect_async().

sock :

the SoupSocket

status :

an HTTP status code indicating success or failure

user_data :

the data passed to soup_socket_connect_async()

soup_socket_connect_async ()

void                soup_socket_connect_async           (SoupSocket *sock,
                                                         GCancellable *cancellable,
                                                         SoupSocketCallback callback,
                                                         gpointer user_data);

Begins asynchronously connecting to sock's remote address. The socket will call callback when it succeeds or fails (but not before returning from this function).

If cancellable is non-NULL, it can be used to cancel the connection. callback will still be invoked in this case, with a status of SOUP_STATUS_CANCELLED.

sock :

a client SoupSocket (which must not already be connected)

cancellable :

a GCancellable, or NULL

callback :

callback to call after connecting

user_data :

data to pass to callback

soup_socket_connect_sync ()

guint               soup_socket_connect_sync            (SoupSocket *sock,
                                                         GCancellable *cancellable);

Attempt to synchronously connect sock to its remote address.

If cancellable is non-NULL, it can be used to cancel the connection, in which case soup_socket_connect_sync() will return SOUP_STATUS_CANCELLED.

sock :

a client SoupSocket (which must not already be connected)

cancellable :

a GCancellable, or NULL

Returns :

a success or failure code.

soup_socket_listen ()

gboolean            soup_socket_listen                  (SoupSocket *sock);

Makes sock start listening on its local address. When connections come in, sock will emit new_connection.

sock :

a server SoupSocket (which must not already be connected or listening)

Returns :

whether or not sock is now listening.

soup_socket_start_ssl ()

gboolean            soup_socket_start_ssl               (SoupSocket *sock,
                                                         GCancellable *cancellable);

Starts using SSL on socket.

sock :

the socket

cancellable :

a GCancellable

Returns :

success or failure

soup_socket_start_proxy_ssl ()

gboolean            soup_socket_start_proxy_ssl         (SoupSocket *sock,
                                                         const char *ssl_host,
                                                         GCancellable *cancellable);

Starts using SSL on socket, expecting to find a host named ssl_host.

sock :

the socket

ssl_host :

hostname of the SSL server

cancellable :

a GCancellable

Returns :

success or failure

soup_socket_is_ssl ()

gboolean            soup_socket_is_ssl                  (SoupSocket *sock);

sock :

Returns :


soup_socket_disconnect ()

void                soup_socket_disconnect              (SoupSocket *sock);

Disconnects sock. Any further read or write attempts on it will fail.

sock :

a SoupSocket

soup_socket_is_connected ()

gboolean            soup_socket_is_connected            (SoupSocket *sock);

Tests if sock is connected to another host

sock :

a SoupSocket

Returns :

TRUE or FALSE.

soup_socket_get_local_address ()

SoupAddress*        soup_socket_get_local_address       (SoupSocket *sock);

Returns the SoupAddress corresponding to the local end of sock.

sock :

a SoupSocket

Returns :

the SoupAddress

soup_socket_get_remote_address ()

SoupAddress*        soup_socket_get_remote_address      (SoupSocket *sock);

Returns the SoupAddress corresponding to the remote end of sock.

sock :

a SoupSocket

Returns :

the SoupAddress

enum SoupSocketIOStatus

typedef enum {
	SOUP_SOCKET_OK,
	SOUP_SOCKET_WOULD_BLOCK,
	SOUP_SOCKET_EOF,
	SOUP_SOCKET_ERROR
} SoupSocketIOStatus;

Return value from the SoupSocket IO methods.

SOUP_SOCKET_OK

Success

SOUP_SOCKET_WOULD_BLOCK

Cannot read/write any more at this time

SOUP_SOCKET_EOF

End of file

SOUP_SOCKET_ERROR

Other error

soup_socket_read ()

SoupSocketIOStatus  soup_socket_read                    (SoupSocket *sock,
                                                         gpointer buffer,
                                                         gsize len,
                                                         gsize *nread,
                                                         GCancellable *cancellable,
                                                         GError **error);

Attempts to read up to len bytes from sock into buffer. If some data is successfully read, soup_socket_read() will return SOUP_SOCKET_OK, and *nread will contain the number of bytes actually read.

If sock is non-blocking, and no data is available, the return value will be SOUP_SOCKET_WOULD_BLOCK. In this case, the caller can connect to the readable signal to know when there is more data to read. (NB: You MUST read all available data off the socket first. The readable signal will only be emitted after soup_socket_read() has returned SOUP_SOCKET_WOULD_BLOCK.)

sock :

the socket

buffer :

buffer to read into

len :

size of buffer in bytes

nread :

on return, the number of bytes read into buffer

cancellable :

a GCancellable, or NULL

error :

error pointer

Returns :

a SoupSocketIOStatus, as described above (or SOUP_SOCKET_EOF if the socket is no longer connected, or SOUP_SOCKET_ERROR on any other error, in which case error will also be set).

soup_socket_read_until ()

SoupSocketIOStatus  soup_socket_read_until              (SoupSocket *sock,
                                                         gpointer buffer,
                                                         gsize len,
                                                         gconstpointer boundary,
                                                         gsize boundary_len,
                                                         gsize *nread,
                                                         gboolean *got_boundary,
                                                         GCancellable *cancellable,
                                                         GError **error);

Like soup_socket_read(), but reads no further than the first occurrence of boundary. (If the boundary is found, it will be included in the returned data, and *got_boundary will be set to TRUE.) Any data after the boundary will returned in future reads.

sock :

the socket

buffer :

buffer to read into

len :

size of buffer in bytes

boundary :

boundary to read until

boundary_len :

length of boundary in bytes

nread :

on return, the number of bytes read into buffer

got_boundary :

on return, whether or not the data in buffer ends with the boundary string

cancellable :

a GCancellable, or NULL

error :

error pointer

Returns :

as for soup_socket_read()

soup_socket_write ()

SoupSocketIOStatus  soup_socket_write                   (SoupSocket *sock,
                                                         gconstpointer buffer,
                                                         gsize len,
                                                         gsize *nwrote,
                                                         GCancellable *cancellable,
                                                         GError **error);

Attempts to write len bytes from buffer to sock. If some data is successfully written, the resturn status will be SOUP_SOCKET_SUCCESS, and *nwrote will contain the number of bytes actually written.

If sock is non-blocking, and no data could be written right away, the return value will be SOUP_SOCKET_WOULD_BLOCK. In this case, the caller can connect to the writable signal to know when more data can be written. (NB: writable is only emitted after a SOUP_SOCKET_WOULD_BLOCK.)

sock :

the socket

buffer :

data to write

len :

size of buffer, in bytes

nwrote :

on return, number of bytes written

cancellable :

a GCancellable, or NULL

error :

error pointer

Returns :

a SoupSocketIOStatus, as described above (or SOUP_SOCKET_EOF or SOUP_SOCKET_ERROR. error will be set if the return value is SOUP_SOCKET_ERROR.)

SOUP_SSL_ERROR

#define SOUP_SSL_ERROR soup_ssl_error_quark()


enum SoupSSLError

typedef enum {
	SOUP_SSL_ERROR_HANDSHAKE_NEEDS_READ,
	SOUP_SSL_ERROR_HANDSHAKE_NEEDS_WRITE,
	SOUP_SSL_ERROR_CERTIFICATE,
} SoupSSLError;


SOUP_SOCKET_LOCAL_ADDRESS

#define SOUP_SOCKET_LOCAL_ADDRESS    "local-address"


SOUP_SOCKET_REMOTE_ADDRESS

#define SOUP_SOCKET_REMOTE_ADDRESS   "remote-address"


SOUP_SOCKET_FLAG_NONBLOCKING

#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"


SOUP_SOCKET_IS_SERVER

#define SOUP_SOCKET_IS_SERVER        "is-server"


SOUP_SOCKET_SSL_CREDENTIALS

#define SOUP_SOCKET_SSL_CREDENTIALS  "ssl-creds"


SOUP_SOCKET_ASYNC_CONTEXT

#define SOUP_SOCKET_ASYNC_CONTEXT    "async-context"


SOUP_SOCKET_TIMEOUT

#define SOUP_SOCKET_TIMEOUT	     "timeout"

Property Details

The "async-context" property

  "async-context"            gpointer              : Read / Write / Construct Only

The GMainContext to dispatch this socket's async I/O in.


The "is-server" property

  "is-server"                gboolean              : Read

Whether or not the socket is a server socket.

Default value: FALSE


The "local-address" property

  "local-address"            SoupAddress           : Read / Write / Construct Only

Address of local end of socket.


The "non-blocking" property

  "non-blocking"             gboolean              : Read / Write

Whether or not the socket uses non-blocking I/O.

Default value: TRUE


The "remote-address" property

  "remote-address"           SoupAddress           : Read / Write / Construct Only

Address of remote end of socket.


The "ssl-creds" property

  "ssl-creds"                gpointer              : Read / Write

SSL credential information, passed from the session to the SSL implementation.


The "timeout" property

  "timeout"                  guint                 : Read / Write

Value in seconds to timeout a blocking I/O.

Default value: 0

Signal Details

The "disconnected" signal

void                user_function                      (SoupSocket *sock,
                                                        gpointer    user_data)      : Run Last

Emitted when the socket is disconnected, for whatever reason.

sock :

the socket

user_data :

user data set when the signal handler was connected.

The "new-connection" signal

void                user_function                      (SoupSocket *sock,
                                                        SoupSocket *new,
                                                        gpointer    user_data)      : Run First

Emitted when a listening socket (set up with soup_socket_listen()) receives a new connection.

You must ref the new if you want to keep it; otherwise it will be destroyed after the signal is emitted.

sock :

the socket

new :

the new socket

user_data :

user data set when the signal handler was connected.

The "readable" signal

void                user_function                      (SoupSocket *sock,
                                                        gpointer    user_data)      : Run Last

Emitted when an async socket is readable. See soup_socket_read() and soup_socket_read_until().

sock :

the socket

user_data :

user data set when the signal handler was connected.

The "writable" signal

void                user_function                      (SoupSocket *sock,
                                                        gpointer    user_data)      : Run Last

Emitted when an async socket is writable. See soup_socket_write().

sock :

the socket

user_data :

user data set when the signal handler was connected.