soup-socket

Name

soup-socket -- 

Synopsis



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

Description

Details

SOUP_SERVER_ANY_PORT

#define SOUP_SERVER_ANY_PORT 0


struct SoupAddress

struct SoupAddress;


SoupAddressNewId

typedef gpointer SoupAddressNewId;


enum SoupAddressStatus

typedef enum {
	SOUP_ADDRESS_STATUS_OK,
	SOUP_ADDRESS_STATUS_ERROR
} SoupAddressStatus;


SoupAddressNewFn ()

void        (*SoupAddressNewFn)             (SoupAddress *inetaddr,
                                             SoupAddressStatus status,
                                             gpointer user_data);

inetaddr :

status :

user_data :


soup_address_new ()

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 soup_address_new_cancel() to cancel it; NULL on immediate success or failure.


soup_address_new_cancel ()

void        soup_address_new_cancel         (SoupAddressNewId id);

Cancel an asynchronous SoupAddress creation that was started with soup_address_new().

id :

ID of the lookup


soup_address_new_sync ()

SoupAddress* soup_address_new_sync          (const gchar *name,
                                             const gint port);

name :

port :

Returns :


soup_address_ref ()

void        soup_address_ref                (SoupAddress *ia);

Increment the reference counter of the SoupAddress.

ia :

SoupAddress to reference


soup_address_unref ()

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


SoupAddressGetNameId

typedef gpointer SoupAddressGetNameId;


SoupAddressGetNameFn ()

void        (*SoupAddressGetNameFn)         (SoupAddress *inetaddr,
                                             SoupAddressStatus status,
                                             const gchar *name,
                                             gpointer user_data);

inetaddr :

status :

name :

user_data :


soup_address_get_name ()

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 soup_addressr_get_name_cancel() to cancel it; NULL on immediate success or failure.


soup_address_get_name_cancel ()

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


soup_address_get_canonical_name ()

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.


soup_address_get_port ()

gint        soup_address_get_port           (const SoupAddress *ia);

Get the port number.

ia :

Address to get the port number of.

Returns :

the port number.


soup_address_hash ()

guint       soup_address_hash               (const gpointer p);

Hash the address. This is useful for glib containers.

p :

Pointer to an SoupAddress.

Returns :

hash value.


soup_address_equal ()

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.


soup_address_noport_equal ()

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.


soup_address_gethostname ()

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.


soup_address_gethostaddr ()

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.


struct SoupSocket

struct SoupSocket;


SoupSocketConnectId

typedef gpointer SoupSocketConnectId;


enum SoupSocketConnectStatus

typedef enum {
	SOUP_SOCKET_CONNECT_ERROR_NONE,
	SOUP_SOCKET_CONNECT_ERROR_ADDR_RESOLVE,
	SOUP_SOCKET_CONNECT_ERROR_NETWORK
} SoupSocketConnectStatus;


SoupSocketConnectFn ()

void        (*SoupSocketConnectFn)          (SoupSocket *socket,
                                             SoupSocketConnectStatus status,
                                             gpointer data);

socket :

status :

data :


soup_socket_connect ()

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 soup_socket_connect_cancel() to cancel it; NULL if it succeeds or fails immediately.


soup_socket_connect_cancel ()

void        soup_socket_connect_cancel      (SoupSocketConnectId id);

Cancel an asynchronous connection that was started with soup_socket_connect().

id :

Id of the connection.


soup_socket_connect_sync ()

SoupSocket* soup_socket_connect_sync        (const gchar *hostname,
                                             const gint port);

hostname :

port :

Returns :


SoupSocketNewId

typedef gpointer SoupSocketNewId;


enum SoupSocketNewStatus

typedef enum {
	SOUP_SOCKET_NEW_STATUS_OK,
	SOUP_SOCKET_NEW_STATUS_ERROR
} SoupSocketNewStatus;


SoupSocketNewFn ()

void        (*SoupSocketNewFn)              (SoupSocket *socket,
                                             SoupSocketNewStatus status,
                                             gpointer data);

socket :

status :

data :


soup_socket_new ()

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 soup_socket_connect_cancel() to cancel it; NULL on failure.


soup_socket_new_cancel ()

void        soup_socket_new_cancel          (SoupSocketNewId id);

Cancel an asynchronous connection that was started with soup_socket_new().

id :

ID of the connection.


soup_socket_new_sync ()

SoupSocket* soup_socket_new_sync            (SoupAddress *addr);

addr :

Returns :


soup_socket_ref ()

void        soup_socket_ref                 (SoupSocket *s);

Increment the reference counter of the SoupSocket.

s :

SoupSocket to reference


soup_socket_unref ()

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


soup_socket_get_iochannel ()

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.


soup_socket_get_address ()

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.


soup_socket_get_port ()

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.


soup_socket_server_new ()

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.


soup_socket_server_accept ()

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.


soup_socket_server_try_accept ()

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.