![]() | ![]() | ![]() | SOUP Reference Manual | ![]() |
---|
#define SOUP_SERVER_ANY_PORT struct SoupAddress; typedef SoupAddressNewId; enum SoupAddressStatus; void (*SoupAddressNewFn) (SoupAddress *inetaddr, SoupAddressStatus status, gpointer user_data); SoupAddressNewId soup_address_new (const gchar *name, const gint port, SoupAddressNewFn func, gpointer data); void soup_address_new_cancel (SoupAddressNewId id); SoupAddress* soup_address_new_sync (const gchar *name, const gint port); void soup_address_ref (SoupAddress *ia); void soup_address_unref (SoupAddress *ia); typedef SoupAddressGetNameId; void (*SoupAddressGetNameFn) (SoupAddress *inetaddr, SoupAddressStatus status, const gchar *name, gpointer user_data); SoupAddressGetNameId soup_address_get_name (SoupAddress *ia, SoupAddressGetNameFn func, gpointer data); void soup_address_get_name_cancel (SoupAddressGetNameId id); gchar* soup_address_get_canonical_name (SoupAddress *ia); gint soup_address_get_port (const SoupAddress *ia); guint soup_address_hash (const gpointer p); gint soup_address_equal (const gpointer p1, const gpointer p2); gint soup_address_noport_equal (const gpointer p1, const gpointer p2); gchar* soup_address_gethostname (void); SoupAddress* soup_address_gethostaddr (void); struct SoupSocket; typedef SoupSocketConnectId; enum SoupSocketConnectStatus; void (*SoupSocketConnectFn) (SoupSocket *socket, SoupSocketConnectStatus status, gpointer data); SoupSocketConnectId soup_socket_connect (const gchar *hostname, const gint port, SoupSocketConnectFn func, gpointer data); void soup_socket_connect_cancel (SoupSocketConnectId id); SoupSocket* soup_socket_connect_sync (const gchar *hostname, const gint port); typedef SoupSocketNewId; enum SoupSocketNewStatus; void (*SoupSocketNewFn) (SoupSocket *socket, SoupSocketNewStatus status, gpointer data); SoupSocketNewId soup_socket_new (SoupAddress *addr, SoupSocketNewFn func, gpointer data); void soup_socket_new_cancel (SoupSocketNewId id); SoupSocket* soup_socket_new_sync (SoupAddress *addr); void soup_socket_ref (SoupSocket *s); void soup_socket_unref (SoupSocket *s); GIOChannel* soup_socket_get_iochannel (SoupSocket *socket); SoupAddress* soup_socket_get_address (const SoupSocket *socket); gint soup_socket_get_port (const SoupSocket *socket); SoupSocket* soup_socket_server_new (const gint port); SoupSocket* soup_socket_server_accept (SoupSocket *socket); SoupSocket* soup_socket_server_try_accept (SoupSocket *socket);
typedef enum { SOUP_ADDRESS_STATUS_OK, SOUP_ADDRESS_STATUS_ERROR } SoupAddressStatus;
void (*SoupAddressNewFn) (SoupAddress *inetaddr, SoupAddressStatus status, gpointer user_data);
inetaddr : | |
status : | |
user_data : |
|
SoupAddressNewId soup_address_new (const gchar *name, const gint port, SoupAddressNewFn func, gpointer data);
Create a SoupAddress from a name and port asynchronously. Once the structure is created, it will call the callback. It may call the callback before the function returns. It will call the callback if there is a failure.
The Unix version forks and does the lookup, which can cause some problems. In general, this will work ok for most programs most of the time. It will be slow or even fail when using operating systems that copy the entire process when forking.
If you need to lookup a lot of addresses, we recommend calling g_main_iteration(FALSE) between calls. This will help prevent an explosion of processes.
If you need a more robust library for Unix, look at <ulink url="http://www.gnu.org/software/adns/adns.html">GNU ADNS</ulink>. GNU ADNS is under the GNU GPL.
The Windows version should work fine. Windows has an asynchronous DNS lookup function.
name : | a nice name (eg, mofo.eecs.umich.edu) or a dotted decimal name (eg, 141.213.8.59). You can delete the after the function is called. |
port : | port number (0 if the port doesn't matter) |
func : | Callback function. |
data : | User data passed when callback function is called. |
Returns : | ID of the lookup which can be used with
|
void soup_address_new_cancel (SoupAddressNewId id);
Cancel an asynchronous SoupAddress creation that was started with
soup_address_new()
.
id : | ID of the lookup |
SoupAddress* soup_address_new_sync (const gchar *name, const gint port);
name : | |
port : | |
Returns : |
|
void soup_address_ref (SoupAddress *ia);
Increment the reference counter of the SoupAddress.
ia : | SoupAddress to reference |
void soup_address_unref (SoupAddress *ia);
Remove a reference from the SoupAddress. When reference count reaches 0, the address is deleted.
ia : | SoupAddress to unreference |
void (*SoupAddressGetNameFn) (SoupAddress *inetaddr, SoupAddressStatus status, const gchar *name, gpointer user_data);
inetaddr : | |
status : | |
name : | |
user_data : |
|
SoupAddressGetNameId soup_address_get_name (SoupAddress *ia, SoupAddressGetNameFn func, gpointer data);
Get the nice name of the address (eg, "mofo.eecs.umich.edu"). This function will use the callback once it knows the nice name. It may even call the callback before it returns. The callback will be called if there is an error.
The Unix version forks and does the reverse lookup. This has
problems. See the notes for soup_address_new()
. The
Windows version should work fine.
ia : | Address to get the name of. |
func : | Callback function. |
data : | User data passed when callback function is called. |
Returns : | ID of the lookup which can be used with
|
void soup_address_get_name_cancel (SoupAddressGetNameId id);
Cancel an asynchronous nice name lookup that was started with
soup_address_get_name()
.
id : | ID of the lookup |
gchar* soup_address_get_canonical_name (SoupAddress *ia);
Get the "canonical" name of an address (eg, for IP4 the dotted decimal name 141.213.8.59).
ia : | Address to get the canonical name of. |
Returns : | NULL if there was an error. The caller is responsible for deleting the returned string. |
gint soup_address_get_port (const SoupAddress *ia);
Get the port number.
ia : | Address to get the port number of. |
Returns : | the port number. |
guint soup_address_hash (const gpointer p);
Hash the address. This is useful for glib containers.
p : | Pointer to an SoupAddress. |
Returns : | hash value. |
gint soup_address_equal (const gpointer p1, const gpointer p2);
Compare two SoupAddress's.
p1 : | Pointer to first SoupAddress. |
p2 : | Pointer to second SoupAddress. |
Returns : | 1 if they are the same; 0 otherwise. |
gint soup_address_noport_equal (const gpointer p1, const gpointer p2);
Compare two SoupAddress's, but does not compare the port numbers.
p1 : | Pointer to first SoupAddress. |
p2 : | Pointer to second SoupAddress. |
Returns : | 1 if they are the same; 0 otherwise. |
gchar* soup_address_gethostname (void);
Get the primary host's name.
Returns : | the name of the host; NULL if there was an error. The caller is responsible for deleting the returned string. |
SoupAddress* soup_address_gethostaddr (void);
Get the primary host's SoupAddress.
Returns : | the SoupAddress of the host; NULL if there was an error. The caller is responsible for deleting the returned SoupAddress. |
typedef enum { SOUP_SOCKET_CONNECT_ERROR_NONE, SOUP_SOCKET_CONNECT_ERROR_ADDR_RESOLVE, SOUP_SOCKET_CONNECT_ERROR_NETWORK } SoupSocketConnectStatus;
void (*SoupSocketConnectFn) (SoupSocket *socket, SoupSocketConnectStatus status, gpointer data);
socket : | |
status : | |
data : |
|
SoupSocketConnectId soup_socket_connect (const gchar *hostname, const gint port, SoupSocketConnectFn func, gpointer data);
A quick and easy non-blocking SoupSocket constructor. This connects to the specified address and port and then calls the callback with the data. Use this function when you're a client connecting to a server and you don't want to block or mess with SoupAddress's. It may call the callback before the function returns. It will call the callback if there is a failure.
hostname : | Name of host to connect to |
port : | Port to connect to |
func : | Callback function |
data : | User data passed when callback function is called. |
Returns : | ID of the connection which can be used with
|
void soup_socket_connect_cancel (SoupSocketConnectId id);
Cancel an asynchronous connection that was started with
soup_socket_connect()
.
id : | Id of the connection. |
SoupSocket* soup_socket_connect_sync (const gchar *hostname, const gint port);
hostname : | |
port : | |
Returns : |
|
typedef enum { SOUP_SOCKET_NEW_STATUS_OK, SOUP_SOCKET_NEW_STATUS_ERROR } SoupSocketNewStatus;
void (*SoupSocketNewFn) (SoupSocket *socket, SoupSocketNewStatus status, gpointer data);
socket : | |
status : | |
data : |
|
SoupSocketNewId soup_socket_new (SoupAddress *addr, SoupSocketNewFn func, gpointer data);
Connect to a specifed address asynchronously. When the connection is complete or there is an error, it will call the callback. It may call the callback before the function returns. It will call the callback if there is a failure.
addr : | Address to connect to. |
func : | Callback function. |
data : | User data passed when callback function is called. |
Returns : | ID of the connection which can be used with
|
void soup_socket_new_cancel (SoupSocketNewId id);
Cancel an asynchronous connection that was started with
soup_socket_new()
.
id : | ID of the connection. |
void soup_socket_ref (SoupSocket *s);
Increment the reference counter of the SoupSocket.
s : | SoupSocket to reference |
void soup_socket_unref (SoupSocket *s);
Remove a reference from the SoupSocket. When reference count reaches 0, the socket is deleted.
s : | SoupSocket to unreference |
GIOChannel* soup_socket_get_iochannel (SoupSocket *socket);
Get the GIOChannel for the SoupSocket.
For a client socket, the GIOChannel represents the data stream. Use it like you would any other GIOChannel.
For a server socket however, the GIOChannel represents incoming connections. If you can read from it, there's a connection waiting.
There is one channel for every socket. This function refs the channel before returning it. You should unref the channel when you are done with it. However, you should not close the channel - this is done when you delete the socket.
socket : | SoupSocket to get GIOChannel from. |
Returns : | A GIOChannel; NULL on failure. |
SoupAddress* soup_socket_get_address (const SoupSocket *socket);
Get the address of the socket. If the socket is client socket,
the address is the address of the remote host it is connected to.
If the socket is a server socket, the address is the address of
the local host. (Though you should use
soup_address_gethostaddr()
to get the SoupAddress of the local
host.)
socket : | SoupSocket to get address of. |
Returns : | SoupAddress of socket; NULL on failure. |
gint soup_socket_get_port (const SoupSocket *socket);
Get the port number the socket is bound to.
socket : | SoupSocket to get the port number of. |
Returns : | Port number of the socket. |
SoupSocket* soup_socket_server_new (const gint port);
Create and open a new SoupSocket with the specified port number. Use this sort of socket when your are a server and you know what the port number should be (or pass 0 if you don't care what the port is).
port : | Port number for the socket (SOUP_SERVER_ANY_PORT if you don't care). |
Returns : | a new SoupSocket, or NULL if there was a failure. |
SoupSocket* soup_socket_server_accept (SoupSocket *socket);
Accept a connection from the socket. The socket must have been
created using soup_socket_server_new()
. This function will
block (use soup_socket_server_try_accept()
if you don't
want to block). If the socket's GIOChannel is readable, it DOES
NOT mean that this function will not block.
socket : | SoupSocket to accept connections from. |
Returns : | a new SoupSocket if there is another connect, or NULL if there's an error. |
SoupSocket* soup_socket_server_try_accept (SoupSocket *socket);
Accept a connection from the socket without blocking. The socket
must have been created using soup_socket_server_new()
. This
function is best used with the sockets GIOChannel. If the
channel is readable, then you PROBABLY have a connection. It is
possible for the connection to close by the time you call this, so
it may return NULL even if the channel was readable.
socket : | SoupSocket to accept connections from. |
Returns : | a new SoupSocket if there is another connect, or NULL otherwise. |
<<< soup-server | soup-uri >>> |