manpagez: man pages & more
html files: libsoup-2.4
Home | html | info | man

SoupAddress

SoupAddress — DNS support

Properties

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

Object Hierarchy

    GObject
    ╰── SoupAddress

Implemented Interfaces

SoupAddress implements GSocketConnectable.

Includes

#include <libsoup/soup.h>

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

Although SoupAddress is still used in some libsoup API's, it should not be used in new code; use GLib's GNetworkAddress or GSocketAddress instead.

Functions

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.

Parameters

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)

Parameters

sa

a pointer to a sockaddr

 

len

size of sa

 

Returns

the new SoupAddress.

[nullable]


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 using as a listening SoupSocket.

Parameters

family

the address family

 

port

the port number (usually SOUP_ADDRESS_ANY_PORT)

 

Returns

the new SoupAddress.

[nullable]


SoupAddressCallback ()

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

The callback function passed to soup_address_resolve_async().

Parameters

addr

the SoupAddress that was resolved

 

status

SOUP_STATUS_OK, SOUP_STATUS_CANT_RESOLVE, or SOUP_STATUS_CANCELLED

 

user_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.

It is safe to call this more than once on a given address, from the same thread, with the same async_context (and doing so will not result in redundant DNS queries being made). But it is not safe to call from multiple threads, or with different async_contexts , or mixed with calls to soup_address_resolve_sync().

Parameters

addr

a SoupAddress

 

async_context

the GMainContext to call callback from.

[allow-none]

cancellable

a GCancellable object, or NULL

 

callback

callback to call with the result.

[scope async]

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.

It is safe to call this more than once, even from different threads, but it is not safe to mix calls to soup_address_resolve_sync() with calls to soup_address_resolve_async() on the same address.

Parameters

addr

a SoupAddress

 

cancellable

a GCancellable object, or NULL

 

soup_address_is_resolved ()

gboolean
soup_address_is_resolved (SoupAddress *addr);

Tests if addr has already been resolved. Unlike the other SoupAddress "get" methods, this is safe to call when addr might be being resolved in another thread.

Parameters

addr

a SoupAddress

 

Returns

TRUE if addr has been resolved.


soup_address_get_name ()

const char *
soup_address_get_name (SoupAddress *addr);

Returns the hostname associated with addr .

This method is not thread-safe; if you call it while addr is being resolved in another thread, it may return garbage. You can use soup_address_is_resolved() to safely test whether or not an address is resolved before fetching its name or address.

Parameters

addr

a SoupAddress

 

Returns

the hostname, or NULL if it is not known.

[nullable]


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.

This method is not thread-safe; if you call it while addr is being resolved in another thread, it may return garbage. You can use soup_address_is_resolved() to safely test whether or not an address is resolved before fetching its name or address.

Parameters

addr

a SoupAddress

 

len

return location for sockaddr length

 

Returns

the sockaddr, or NULL.

[nullable][transfer none]


soup_address_get_gsockaddr ()

GSocketAddress *
soup_address_get_gsockaddr (SoupAddress *addr);

Creates a new GSocketAddress corresponding to addr (which is assumed to only have one socket address associated with it).

Parameters

addr

a SoupAddress

 

Returns

a new GSocketAddress.

[transfer full]

Since: 2.32


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.

This method is not thread-safe; if you call it while addr is being resolved in another thread, it may return garbage. You can use soup_address_is_resolved() to safely test whether or not an address is resolved before fetching its name or address.

Parameters

addr

a SoupAddress

 

Returns

the physical address, or NULL.

[nullable]


soup_address_get_port ()

guint
soup_address_get_port (SoupAddress *addr);

Returns the port associated with addr .

Parameters

addr

a SoupAddress

 

Returns

the port


soup_address_equal_by_name ()

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.

Parameters

addr1

a SoupAddress with a resolved name.

[type Soup.Address]

addr2

another SoupAddress with a resolved name.

[type Soup.Address]

Returns

whether or not addr1 and addr2 have the same name

Since: 2.26


soup_address_hash_by_name ()

guint
soup_address_hash_by_name (gconstpointer addr);

A hash function (for GHashTable) that corresponds to soup_address_equal_by_name(), qv

Parameters

addr

a SoupAddress.

[type Soup.Address]

Returns

the named-based hash value for addr .

Since: 2.26


soup_address_equal_by_ip ()

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 connection 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.

Parameters

addr1

a SoupAddress with a resolved IP address.

[type Soup.Address]

addr2

another SoupAddress with a resolved IP address.

[type Soup.Address]

Returns

whether or not addr1 and addr2 have the same IP address.

Since: 2.26


soup_address_hash_by_ip ()

guint
soup_address_hash_by_ip (gconstpointer addr);

A hash function (for GHashTable) that corresponds to soup_address_equal_by_ip(), qv

Parameters

addr

a SoupAddress.

[type Soup.Address]

Returns

the IP-based hash value for addr .

Since: 2.26

Types and Values

SoupAddress

typedef struct _SoupAddress SoupAddress;

enum SoupAddressFamily

The supported address families.

Members

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_FAMILY

#define SOUP_ADDRESS_FAMILY   "family"

Alias for the “family” property. (The SoupAddressFamily for this address.)


SOUP_ADDRESS_NAME

#define SOUP_ADDRESS_NAME     "name"

Alias for the “name” property. (The hostname for this address.)


SOUP_ADDRESS_PHYSICAL

#define SOUP_ADDRESS_PHYSICAL "physical"

An alias for the “physical” property. (The stringified IP address for this address.)


SOUP_ADDRESS_PORT

#define SOUP_ADDRESS_PORT     "port"

An alias for the “port” property. (The port for this address.)


SOUP_ADDRESS_SOCKADDR

#define SOUP_ADDRESS_SOCKADDR "sockaddr"

An alias for the “sockaddr” property. (A pointer to the struct sockaddr for this address.)


SOUP_ADDRESS_PROTOCOL

#define SOUP_ADDRESS_PROTOCOL "protocol"

Alias for the “protocol” property. (The URI scheme used with this address.)

Property Details

The “family” property

  “family”                   SoupAddressFamily

Address family for this address.

Owner: SoupAddress

Flags: Read / Write / Construct Only

Default value: SOUP_ADDRESS_FAMILY_INVALID


The “name” property

  “name”                     gchar *

Hostname for this address.

Owner: SoupAddress

Flags: Read / Write / Construct Only

Default value: NULL


The “physical” property

  “physical”                 gchar *

IP address for this address.

Owner: SoupAddress

Flags: Read

Default value: NULL


The “port” property

  “port”                     gint

Port for this address.

Owner: SoupAddress

Flags: Read / Write / Construct Only

Allowed values: [-1,65535]

Default value: -1


The “protocol” property

  “protocol”                 gchar *

URI scheme for this address.

Owner: SoupAddress

Flags: Read / Write / Construct Only

Default value: NULL


The “sockaddr” property

  “sockaddr”                 gpointer

struct sockaddr for this address.

Owner: SoupAddress

Flags: Read / Write / Construct Only

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.