![]() |
![]() |
![]() |
libsoup Reference Manual | ![]() |
---|---|---|---|---|
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); gboolean soup_address_is_resolved (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); gboolean soup_address_equal_by_name (gconstpointer addr1, gconstpointer addr2); guint soup_address_hash_by_name (gconstpointer addr); gboolean soup_address_equal_by_ip (gconstpointer addr1, gconstpointer addr2); guint soup_address_hash_by_ip (gconstpointer addr); #define SOUP_ADDRESS_FAMILY #define SOUP_ADDRESS_NAME #define SOUP_ADDRESS_PHYSICAL #define SOUP_ADDRESS_PORT #define SOUP_ADDRESS_SOCKADDR
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.
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 |
#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.
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 |
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 |
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 |
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()
|
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
|
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 .
|
gboolean soup_address_is_resolved (SoupAddress *addr);
Tests if addr
has already been resolved.
addr : |
a SoupAddress |
Returns : | TRUE if addr has been resolved.
|
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.
|
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
|
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
|
guint soup_address_get_port (SoupAddress *addr);
Returns the port associated with addr
.
addr : |
a SoupAddress |
Returns : | the port |
gboolean soup_address_equal_by_name (gconstpointer addr1, gconstpointer addr2);
Tests if addr1
and addr2
have the same "name". This method can be
used with soup_address_hash_by_name()
to create a GHashTable that
hashes on address "names".
Comparing by name normally means comparing the addresses by their hostnames. But if the address was originally created using an IP address literal, then it will be compared by that instead.
In particular, if "www.example.com" has the IP address 10.0.0.1,
and addr1
was created with the name "www.example.com" and addr2
was created with the name "10.0.0.1", then they will compare as
unequal for purposes of soup_address_equal_by_name()
.
This would be used to distinguish hosts in situations where different virtual hosts on the same IP address should be considered different. Eg, for purposes of HTTP authentication or cookies, two hosts with the same IP address but different names are considered to be different hosts.
See also soup_address_equal_by_ip()
, which compares by IP address
rather than by name.
addr1 : |
a SoupAddress with a resolved name |
addr2 : |
another SoupAddress with a resolved name |
Returns : | whether or not addr1 and addr2 have the same name
|
Since 2.26
guint soup_address_hash_by_name (gconstpointer addr);
A hash function (for GHashTable) that corresponds to
soup_address_equal_by_name()
, qv
addr : |
a SoupAddress |
Returns : | the named-based hash value for addr .
|
Since 2.26
gboolean soup_address_equal_by_ip (gconstpointer addr1, gconstpointer addr2);
Tests if addr1
and addr2
have the same IP address. This method
can be used with soup_address_hash_by_ip()
to create a
GHashTable that hashes on IP address.
This would be used to distinguish hosts in situations where different virtual hosts on the same IP address should be considered the same. Eg, if "www.example.com" and "www.example.net" have the same IP address, then a single SoupConnection can be used to talk to either of them.
See also soup_address_equal_by_name()
, which compares by name
rather than by IP address.
addr1 : |
a SoupAddress with a resolved IP address |
addr2 : |
another SoupAddress with a resolved IP address |
Returns : | whether or not addr1 and addr2 have the same IP
address.
|
Since 2.26
guint soup_address_hash_by_ip (gconstpointer addr);
A hash function (for GHashTable) that corresponds to
soup_address_equal_by_ip()
, qv
addr : |
a SoupAddress |
Returns : | the IP-based hash value for addr .
|
Since 2.26
#define SOUP_ADDRESS_FAMILY "family"
Alias for the "family" property. (The SoupAddressFamily for this address.)
#define SOUP_ADDRESS_NAME "name"
Alias for the "name" property. (The hostname for this address.)
#define SOUP_ADDRESS_PHYSICAL "physical"
An alias for the "physical" property. (The stringified IP address for this address.)
#define SOUP_ADDRESS_PORT "port"
An alias for the "port" property. (The port for this address.)