![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
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
SoupSocket * soup_socket_new (const char *optname1
,...
);
Creates a new (disconnected) socket
|
name of first property to set (or NULL ) |
|
value of optname1 , followed by additional property/value pairs |
Returns : |
the new socket |
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.
|
a client SoupSocket (which must not already be connected) |
|
address to connect to |
Returns : |
SOUP_STATUS_CONTINUE if connecting asynchronously,
otherwise a success or failure code. |
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
.
|
a server SoupSocket (which must not already be connected or listening) |
|
Local address to bind to. |
Returns : |
whether or not sock is now listening. |
gboolean soup_socket_start_ssl (SoupSocket *sock
);
Starts using SSL on socket
.
|
the socket |
Returns : |
success or failure |
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
.
|
the socket |
|
hostname of the SSL server |
Returns : |
success or failure |
void soup_socket_disconnect (SoupSocket *sock
);
Disconnects sock
. Any further read or write attempts on it will
fail.
|
a SoupSocket |
gboolean soup_socket_is_connected (SoupSocket *sock
);
Tests if sock
is connected to another host
|
a SoupSocket |
Returns : |
TRUE or FALSE . |
void (*SoupSocketCallback) (SoupSocket *sock
,guint status
,gpointer user_data
);
The callback function passed to soup_socket_client_new_async()
.
|
the SoupSocket |
|
an HTTP status code indicating success or failure |
|
the data passed to soup_socket_client_new_async()
|
void (*SoupSocketListenerCallback) (SoupSocket *listener
,SoupSocket *sock
,gpointer user_data
);
The callback function passed to soup_socket_server_new()
, which
receives new connections.
|
the listening SoupSocket |
|
the newly-received SoupSocket |
|
the data passed to soup_socket_server_new() . |
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.
|
remote machine to connect to |
|
remote port to connect to |
|
SSL credentials structure, or NULL if not SSL |
|
callback to call when the socket is connected |
|
data for callback
|
Returns : |
the new socket (not yet ready for use). |
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.
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 address to bind to. (Use soup_address_any_new() to
accept connections on any local address) |
|
SSL credentials, or NULL if this is not an SSL server |
|
Callback to call when a client connects |
|
data to pass to callback . |
Returns : |
a new SoupSocket, or NULL if there was a failure. |
SoupAddress * soup_socket_get_local_address (SoupSocket *sock
);
Returns the SoupAddress corresponding to the local end of sock
.
|
a SoupSocket |
Returns : |
the SoupAddress |
SoupAddress * soup_socket_get_remote_address (SoupSocket *sock
);
Returns the SoupAddress corresponding to the remote end of sock
.
|
a SoupSocket |
Returns : |
the SoupAddress |
typedef enum { SOUP_SOCKET_OK, SOUP_SOCKET_WOULD_BLOCK, SOUP_SOCKET_EOF, SOUP_SOCKET_ERROR } SoupSocketIOStatus;
Return value from the SoupSocket IO methods.
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
.)
|
the socket |
|
buffer to read into |
|
size of buffer in bytes |
|
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). |
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.
|
the socket |
|
buffer to read into |
|
size of buffer in bytes |
|
boundary to read until |
|
length of boundary in bytes |
|
on return, the number of bytes read into buffer
|
|
on return, whether or not the data in buffer
ends with the boundary string |
Returns : |
as for soup_socket_read()
|
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
.)
|
the socket |
|
data to write |
|
size of buffer , in bytes |
|
on return, number of bytes written |
Returns : |
a SoupSocketIOStatus, as described above (or
SOUP_SOCKET_EOF or SOUP_SOCKET_ERROR ). |
#define SOUP_SOCKET_FLAG_NONBLOCKING "non-blocking"
An alias for the "non-blocking" property.
#define SOUP_SOCKET_FLAG_NODELAY "nodelay"
An alias for the "nodelay" property.
#define SOUP_SOCKET_FLAG_REUSEADDR "reuseaddr"
An alias for the "reuseaddr" property.
#define SOUP_SOCKET_FLAG_CLOEXEC "cloexec"
An alias for the "cloexec" property.
#define SOUP_SOCKET_IS_SERVER "is-server"
An alias for the "is-server" property.
#define SOUP_SOCKET_SSL_CREDENTIALS "ssl-creds"
An alias for the "ssl-creds" property.