SoupSocket

SoupSocket — a network socket

Synopsis




struct              SoupSocket;
SoupSocket*         soup_socket_new                     (const char *optname1,
                                                         ...);
guint               soup_socket_connect                 (SoupSocket *sock,
                                                         SoupAddress *remote_addr);
gboolean            soup_socket_listen                  (SoupSocket *sock,
                                                         SoupAddress *local_addr);
gboolean            soup_socket_start_ssl               (SoupSocket *sock);
gboolean            soup_socket_start_proxy_ssl         (SoupSocket *sock,
                                                         const char *ssl_host);
void                soup_socket_disconnect              (SoupSocket *sock);
gboolean            soup_socket_is_connected            (SoupSocket *sock);
void                (*SoupSocketCallback)               (SoupSocket *sock,
                                                         guint status,
                                                         gpointer user_data);
void                (*SoupSocketListenerCallback)       (SoupSocket *listener,
                                                         SoupSocket *sock,
                                                         gpointer user_data);
SoupSocket*         soup_socket_client_new_async        (const char *hostname,
                                                         guint port,
                                                         gpointer ssl_creds,
                                                         SoupSocketCallback callback,
                                                         gpointer user_data);
SoupSocket*         soup_socket_client_new_sync         (const char *hostname,
                                                         guint port,
                                                         gpointer ssl_creds,
                                                         guint *status_ret);
SoupSocket*         soup_socket_server_new              (SoupAddress *local_addr,
                                                         gpointer ssl_creds,
                                                         SoupSocketListenerCallback callback,
                                                         gpointer user_data);
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);
SoupSocketIOStatus  soup_socket_read_until              (SoupSocket *sock,
                                                         gpointer buffer,
                                                         gsize len,
                                                         gconstpointer boundary,
                                                         gsize boundary_len,
                                                         gsize *nread,
                                                         gboolean *got_boundary);
SoupSocketIOStatus  soup_socket_write                   (SoupSocket *sock,
                                                         gconstpointer buffer,
                                                         gsize len,
                                                         gsize *nwrote);
#define             SOUP_SOCKET_FLAG_NONBLOCKING
#define             SOUP_SOCKET_FLAG_NODELAY
#define             SOUP_SOCKET_FLAG_REUSEADDR
#define             SOUP_SOCKET_FLAG_CLOEXEC
#define             SOUP_SOCKET_TIMEOUT
#define             SOUP_SOCKET_IS_SERVER
#define             SOUP_SOCKET_SSL_CREDENTIALS
#define             SOUP_SOCKET_ASYNC_CONTEXT

Object Hierarchy


  GObject
   +----SoupSocket

Properties


  "async-context"            gpointer              : Read / Write / Construct Only
  "cloexec"                  gboolean              : Read / Write
  "is-server"                gboolean              : Read
  "nodelay"                  gboolean              : Read / Write
  "non-blocking"             gboolean              : Read / Write
  "reuseaddr"                gboolean              : Read / Write
  "ssl-creds"                gpointer              : Read / Write
  "timeout"                  guint                 : Read / Write

Signals


  "connect-result"                                 : Run First
  "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

soup_socket_connect ()

guint               soup_socket_connect                 (SoupSocket *sock,
                                                         SoupAddress *remote_addr);

If SOUP_SOCKET_FLAG_NONBLOCKING has been set on the socket, this begins asynchronously connecting to the given address. The socket will emit connect_result when it succeeds or fails (but not before returning from this function).

If SOUP_SOCKET_FLAG_NONBLOCKING has not been set, this will attempt to synchronously connect.

sock :

 a client SoupSocket (which must not already be connected)

remote_addr :

 address to connect to

Returns :

 SOUP_STATUS_CONTINUE if connecting asynchronously, otherwise a success or failure code.

soup_socket_listen ()

gboolean            soup_socket_listen                  (SoupSocket *sock,
                                                         SoupAddress *local_addr);

Makes sock start listening on the given interface and port. When connections come in, sock will emit new_connection.

sock :

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

local_addr :

 Local address to bind to.

Returns :

 whether or not sock is now listening.

soup_socket_start_ssl ()

gboolean            soup_socket_start_ssl               (SoupSocket *sock);

Starts using SSL on socket.

sock :

 the socket

Returns :

 success or failure

soup_socket_start_proxy_ssl ()

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

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

sock :

 the socket

ssl_host :

 hostname of the SSL server

Returns :

 success or failure

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.

SoupSocketCallback ()

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

The callback function passed to soup_socket_client_new_async().

sock :

 the SoupSocket

status :

 an HTTP status code indicating success or failure

user_data :

 the data passed to soup_socket_client_new_async()

SoupSocketListenerCallback ()

void                (*SoupSocketListenerCallback)       (SoupSocket *listener,
                                                         SoupSocket *sock,
                                                         gpointer user_data);

The callback function passed to soup_socket_server_new(), which receives new connections.

listener :

 the listening SoupSocket

sock :

 the newly-received SoupSocket

user_data :

 the data passed to soup_socket_server_new().

soup_socket_client_new_async ()

SoupSocket*         soup_socket_client_new_async        (const char *hostname,
                                                         guint port,
                                                         gpointer ssl_creds,
                                                         SoupSocketCallback callback,
                                                         gpointer user_data);

Creates a connection to hostname and port. callback will be called when the connection completes (or fails).

Uses the default GMainContext. If you need to use an alternate context, use soup_socket_new() and soup_socket_connect() directly.

hostname :

 remote machine to connect to

port :

 remote port to connect to

ssl_creds :

 SSL credentials structure, or NULL if not SSL

callback :

 callback to call when the socket is connected

user_data :

 data for callback

Returns :

 the new socket (not yet ready for use).

soup_socket_client_new_sync ()

SoupSocket*         soup_socket_client_new_sync         (const char *hostname,
                                                         guint port,
                                                         gpointer ssl_creds,
                                                         guint *status_ret);

Creates a connection to hostname and port. If status_ret is not NULL, it will contain a status code on return.

hostname :

 remote machine to connect to

port :

 remote port to connect to

ssl_creds :

 SSL credentials structure, or NULL if not SSL

status_ret :

 pointer to return the soup status in

Returns :

 the new socket, or NULL if it could not connect.

soup_socket_server_new ()

SoupSocket*         soup_socket_server_new              (SoupAddress *local_addr,
                                                         gpointer ssl_creds,
                                                         SoupSocketListenerCallback callback,
                                                         gpointer user_data);

Create and open a new SoupSocket listening on the specified address. callback will be called each time a client connects, with a new SoupSocket.

Uses the default GMainContext. If you need to use an alternate context, use soup_socket_new() and soup_socket_listen() directly.

local_addr :

 Local address to bind to. (Use soup_address_any_new() to accept connections on any local address)

ssl_creds :

 SSL credentials, or NULL if this is not an SSL server

callback :

 Callback to call when a client connects

user_data :

 data to pass to callback.

Returns :

 a new SoupSocket, or NULL if there was a failure.

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);

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

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

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);

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

Returns :

 as for soup_socket_read()

soup_socket_write ()

SoupSocketIOStatus  soup_socket_write                   (SoupSocket *sock,
                                                         gconstpointer buffer,
                                                         gsize len,
                                                         gsize *nwrote);

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

Returns :

 a SoupSocketIOStatus, as described above (or SOUP_SOCKET_EOF or SOUP_SOCKET_ERROR).

SOUP_SOCKET_FLAG_NONBLOCKING

#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"

An alias for the "non-blocking" property.

SOUP_SOCKET_FLAG_NODELAY

#define SOUP_SOCKET_FLAG_NODELAY     "nodelay"

An alias for the "nodelay" property.

SOUP_SOCKET_FLAG_REUSEADDR

#define SOUP_SOCKET_FLAG_REUSEADDR   "reuseaddr"

An alias for the "reuseaddr" property.

SOUP_SOCKET_FLAG_CLOEXEC

#define SOUP_SOCKET_FLAG_CLOEXEC     "cloexec"

An alias for the "cloexec" property.

SOUP_SOCKET_TIMEOUT

#define SOUP_SOCKET_TIMEOUT	     "timeout"

An alias for the "timeout" property.

SOUP_SOCKET_IS_SERVER

#define SOUP_SOCKET_IS_SERVER        "is-server"

An alias for the "is-server" property.

SOUP_SOCKET_SSL_CREDENTIALS

#define SOUP_SOCKET_SSL_CREDENTIALS  "ssl-creds"

An alias for the "ssl-creds" property.

SOUP_SOCKET_ASYNC_CONTEXT

#define SOUP_SOCKET_ASYNC_CONTEXT    "async-context"

An alias for the "async-context" property.

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 "cloexec" property

  "cloexec"                  gboolean              : Read / Write

Whether or not the socket will be closed automatically on exec().

Default value: FALSE

The "is-server" property

  "is-server"                gboolean              : Read

Whether or not the socket is a server socket.

Default value: FALSE

The "nodelay" property

  "nodelay"                  gboolean              : Read / Write

Whether or not the socket uses TCP NODELAY.

Default value: TRUE

The "non-blocking" property

  "non-blocking"             gboolean              : Read / Write

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

Default value: TRUE

The "reuseaddr" property

  "reuseaddr"                gboolean              : Read / Write

Whether or not the socket uses the TCP REUSEADDR flag.

Default value: TRUE

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 "connect-result" signal

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

Emitted when a connection attempt succeeds or fails. This is used internally by soup_socket_client_new_async().

sock :

 the socket

status :

 the status

user_data :

 user data set when the signal handler was connected.

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() or soup_socket_server_new()) receives a new connection.

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.