SoupAddress

SoupAddress — DNS support

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,
                                                         GMainContext *async_context,
                                                         GCancellable *cancellable,
                                                         SoupAddressCallback callback,
                                                         gpointer user_data);
guint               soup_address_resolve_sync           (SoupAddress *addr,
                                                         GCancellable *cancellable);

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

#define             SOUP_ADDRESS_FAMILY
#define             SOUP_ADDRESS_NAME
#define             SOUP_ADDRESS_PHYSICAL
#define             SOUP_ADDRESS_PORT
#define             SOUP_ADDRESS_SOCKADDR


Object Hierarchy


  GObject
   +----SoupAddress

Properties


  "family"                   SoupAddressFamily     : Read / Write / Construct Only
  "name"                     gchar*                : Read / Write / Construct Only
  "physical"                 gchar*                : Read
  "port"                     gint                  : Read / Write / Construct Only
  "sockaddr"                 gpointer              : Read / Write / Construct Only

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_INVALID = -1,

	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_INVALID

an invalid SoupAddress

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, SOUP_STATUS_CANT_RESOLVE, or SOUP_STATUS_CANCELLED

data :

the user data that was passed to soup_address_resolve_async()

soup_address_resolve_async ()

void                soup_address_resolve_async          (SoupAddress *addr,
                                                         GMainContext *async_context,
                                                         GCancellable *cancellable,
                                                         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().)

If cancellable is non-NULL, it can be used to cancel the resolution. callback will still be invoked in this case, with a status of SOUP_STATUS_CANCELLED.

addr :

a SoupAddress

async_context :

the GMainContext to call callback from

cancellable :

a GCancellable object, or NULL

callback :

callback to call with the result

user_data :

data for callback

soup_address_resolve_sync ()

guint               soup_address_resolve_sync           (SoupAddress *addr,
                                                         GCancellable *cancellable);

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

If cancellable is non-NULL, it can be used to cancel the resolution. soup_address_resolve_sync() will then return a status of SOUP_STATUS_CANCELLED.

addr :

a SoupAddress

cancellable :

a GCancellable object, or NULL

Returns :

SOUP_STATUS_OK, SOUP_STATUS_CANT_RESOLVE, or SOUP_STATUS_CANCELLED.

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

SOUP_ADDRESS_FAMILY

#define SOUP_ADDRESS_FAMILY   "family"


SOUP_ADDRESS_NAME

#define SOUP_ADDRESS_NAME     "name"


SOUP_ADDRESS_PHYSICAL

#define SOUP_ADDRESS_PHYSICAL "physical"


SOUP_ADDRESS_PORT

#define SOUP_ADDRESS_PORT     "port"


SOUP_ADDRESS_SOCKADDR

#define SOUP_ADDRESS_SOCKADDR "sockaddr"

Property Details

The "family" property

  "family"                   SoupAddressFamily     : Read / Write / Construct Only

Address family for this address.

Default value: SOUP_ADDRESS_FAMILY_INVALID


The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

Hostname for this address.

Default value: NULL


The "physical" property

  "physical"                 gchar*                : Read

IP address for this address.

Default value: NULL


The "port" property

  "port"                     gint                  : Read / Write / Construct Only

Port for this address.

Allowed values: [G_MAXULONG,65535]

Default value: -1


The "sockaddr" property

  "sockaddr"                 gpointer              : Read / Write / Construct Only

struct sockaddr for this address.