SoupAddress

SoupAddress — Higher-level IP address object

Synopsis




struct      SoupAddress;
enum        SoupAddressFamily;
#define     SOUP_ADDRESS_ANY_PORT
SoupAddress* soup_address_new               (const char *name,
                                             guint port);
SoupAddress* soup_address_new_from_sockaddr (struct sockaddr *sa,
                                             int len);
SoupAddress* soup_address_new_any           (SoupAddressFamily family,
                                             guint port);
void        (*SoupAddressCallback)          (SoupAddress *addr,
                                             guint status,
                                             gpointer data);
void        soup_address_resolve_async      (SoupAddress *addr,
                                             SoupAddressCallback callback,
                                             gpointer user_data);
guint       soup_address_resolve_sync       (SoupAddress *addr);
const char* soup_address_get_name           (SoupAddress *addr);
struct sockaddr* soup_address_get_sockaddr  (SoupAddress *addr,
                                             int *len);
const char* soup_address_get_physical       (SoupAddress *addr);
guint       soup_address_get_port           (SoupAddress *addr);

Object Hierarchy


  GObject
   +----SoupAddress

Signal Prototypes


"dns-result"
            void        user_function      (SoupAddress *addr,
                                            gint status,
                                            gpointer user_data);

Description

SoupAddress represents the address of a TCP connection endpoint; both the IP address and the port. (It is somewhat like an object-oriented version of struct sockaddr.)

If libsoup was built with IPv6 support, SoupAddress will allow both IPv4 and IPv6 addresses.

Details

struct SoupAddress

struct SoupAddress;


enum SoupAddressFamily

typedef enum {
	SOUP_ADDRESS_FAMILY_IPV4 = AF_INET,
	SOUP_ADDRESS_FAMILY_IPV6 = AF_INET6
} SoupAddressFamily;

The supported address families. Note that the SOUP_ADDRESS_FAMILY_IPV6 constant is available even if libsoup was built without IPv6 support, but attempting to create an IPv6 address will fail in that case.

SOUP_ADDRESS_FAMILY_IPV4 an IPv4 address
SOUP_ADDRESS_FAMILY_IPV6 an IPv6 address

SOUP_ADDRESS_ANY_PORT

#define SOUP_ADDRESS_ANY_PORT 0

This can be passed to any SoupAddress method that expects a port, to indicate that you don't care what port is used.


soup_address_new ()

SoupAddress* soup_address_new               (const char *name,
                                             guint port);

Creates a SoupAddress from name and port. The SoupAddress's IP address may not be available right away; the caller can call soup_address_resolve_async() or soup_address_resolve_sync() to force a DNS resolution.

name : a hostname or physical address
port : a port number
Returns : a SoupAddress

soup_address_new_from_sockaddr ()

SoupAddress* soup_address_new_from_sockaddr (struct sockaddr *sa,
                                             int len);

Returns a SoupAddress equivalent to sa (or NULL if sa's address family isn't supported)

sa : a pointer to a sockaddr
len : size of sa
Returns : the new SoupAddress

soup_address_new_any ()

SoupAddress* soup_address_new_any           (SoupAddressFamily family,
                                             guint port);

Returns a SoupAddress corresponding to the "any" address for family (or NULL if family isn't supported), suitable for passing to soup_socket_server_new().

family : the address family
port : the port number (usually SOUP_ADDRESS_ANY_PORT)
Returns : the new SoupAddress

SoupAddressCallback ()

void        (*SoupAddressCallback)          (SoupAddress *addr,
                                             guint status,
                                             gpointer data);

The callback function passed to soup_address_resolve_async().

addr : the SoupAddress that was resolved
status : SOUP_STATUS_OK or SOUP_STATUS_CANT_RESOLVE
data : the user data that was passed to soup_address_resolve_async()

soup_address_resolve_async ()

void        soup_address_resolve_async      (SoupAddress *addr,
                                             SoupAddressCallback callback,
                                             gpointer user_data);

Asynchronously resolves the missing half of addr. (Its IP address if it was created with soup_address_new(), or its hostname if it was created with soup_address_new_from_sockaddr() or soup_address_new_any().) callback will be called when the resolution finishes (successfully or not).

addr : a SoupAddress
callback : callback to call with the result
user_data : data for callback

soup_address_resolve_sync ()

guint       soup_address_resolve_sync       (SoupAddress *addr);

Synchronously resolves the missing half of addr, as with soup_address_resolve_async().

addr : a SoupAddress
Returns : SOUP_STATUS_OK or SOUP_STATUS_CANT_RESOLVE

soup_address_get_name ()

const char* soup_address_get_name           (SoupAddress *addr);

Returns the hostname associated with addr.

addr : a SoupAddress
Returns : the hostname, or NULL if it is not known.

soup_address_get_sockaddr ()

struct sockaddr* soup_address_get_sockaddr  (SoupAddress *addr,
                                             int *len);

Returns the sockaddr associated with addr, with its length in *len. If the sockaddr is not yet known, returns NULL.

addr : a SoupAddress
len : return location for sockaddr length
Returns : the sockaddr, or NULL

soup_address_get_physical ()

const char* soup_address_get_physical       (SoupAddress *addr);

Returns the physical address associated with addr as a string. (Eg, "127.0.0.1"). If the address is not yet known, returns NULL.

addr : a SoupAddress
Returns : the physical address, or NULL

soup_address_get_port ()

guint       soup_address_get_port           (SoupAddress *addr);

Returns the port associated with addr.

addr : a SoupAddress
Returns : the port

Signals

The "dns-result" signal

void        user_function                  (SoupAddress *addr,
                                            gint status,
                                            gpointer user_data);

Emitted when an address resolution completes. (This is used internally by soup_address_resolve_async() itself.)

addr : the SoupAddress
status : the DNS status code
user_data :user data set when the signal handler was connected.