Soup.Address¶

Subclasses:	None

Methods¶

Inherited:	GObject.Object (37), Gio.SocketConnectable (3)
Structs:	GObject.ObjectClass (5)

class	`new` (name, port)
class	`new_any` (family, port)
class	`new_from_sockaddr` (sa, len)
	`equal_by_ip` (addr2)
	`equal_by_name` (addr2)
	`get_gsockaddr` ()
	`get_name` ()
	`get_physical` ()
	`get_port` ()
	`get_sockaddr` (len)
	`hash_by_ip` ()
	`hash_by_name` ()
	`is_resolved` ()
	`resolve_async` (async_context, cancellable, callback, *user_data)
	`resolve_sync` (cancellable)

Virtual Methods¶

Inherited:	GObject.Object (7), Gio.SocketConnectable (3)

Properties¶

Name	Type	Flags	Short Description
`family`	`Soup.AddressFamily`	r/w/co	Address family for this address
`name`	`str`	r/w/co	Hostname for this address
`physical`	`str`	r	IP address for this address
`port`	`int`	r/w/co	Port for this address
`protocol`	`str`	r/w/co	URI scheme for this address
`sockaddr`	`int`	r/w/co	struct sockaddr for this address

Signals¶

Inherited:	GObject.Object (1)

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Soup.Address(**kwargs)¶

Bases:	`GObject.Object`, `Gio.SocketConnectable`
Abstract:	No
Structure:	`Soup.AddressClass`

classmethod new(name, port)¶

Parameters:	name (`str`) – a hostname or physical address port (`int`) – a port number
Returns:	a `Soup.Address`
Return type:	`Soup.Address`

Creates a Soup.Address from name and port. The Soup.Address’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.

classmethod new_any(family, port)¶

Parameters:	family (`Soup.AddressFamily`) – the address family port (`int`) – the port number (usually `Soup.ADDRESS_ANY_PORT`)
Returns:	the new `Soup.Address`
Return type:	`Soup.Address` or `None`

Returns a Soup.Address corresponding to the “any” address for family (or None if family isn’t supported), suitable for using as a listening Soup.Socket.

classmethod new_from_sockaddr(sa, len)¶

Parameters:	sa (`object` or `None`) – a pointer to a sockaddr len (`int`) – size of sa
Returns:	the new `Soup.Address`
Return type:	`Soup.Address` or `None`

Returns a Soup.Address equivalent to sa (or None if sa’s address family isn’t supported)

equal_by_ip(addr2)¶

Parameters:	addr2 (`Soup.Address`) – another `Soup.Address` with a resolved IP address
Returns:	whether or not self and addr2 have the same IP address.
Return type:	`bool`

Tests if self and addr2 have the same IP address. This method can be used with Soup.Address.hash_by_ip() to create a GLib.HashTable 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.

New in version 2.26.

equal_by_name(addr2)¶

Parameters:	addr2 (`Soup.Address`) – another `Soup.Address` with a resolved name
Returns:	whether or not self and addr2 have the same name
Return type:	`bool`

Tests if self and addr2 have the same “name”. This method can be used with Soup.Address.hash_by_name() to create a GLib.HashTable 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 self 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.

New in version 2.26.

get_gsockaddr()¶

Returns:	a new `Gio.SocketAddress`
Return type:	`Gio.SocketAddress`

Creates a new Gio.SocketAddress corresponding to self (which is assumed to only have one socket address associated with it).

New in version 2.32.

get_name()¶

Returns:	the hostname, or `None` if it is not known.
Return type:	`str` or `None`

Returns the hostname associated with self.

This method is not thread-safe; if you call it while self 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.

get_physical()¶

Returns:	the physical address, or `None`
Return type:	`str` or `None`

Returns the physical address associated with self as a string. (Eg, “127.0.0.1”). If the address is not yet known, returns None.

This method is not thread-safe; if you call it while self 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.

get_port()¶

Returns:	the port
Return type:	`int`

Returns the port associated with self.

get_sockaddr(len)¶

Parameters:	len (`int`) – return location for sockaddr length
Returns:	the sockaddr, or `None`
Return type:	`object` or `None`

Returns the sockaddr associated with self, with its length in len. If the sockaddr is not yet known, returns None.

This method is not thread-safe; if you call it while self 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.

hash_by_ip()¶

Returns:	the IP-based hash value for self.
Return type:	`int`

A hash function (for GLib.HashTable) that corresponds to Soup.Address.equal_by_ip(), qv

New in version 2.26.

hash_by_name()¶

Returns:	the named-based hash value for self.
Return type:	`int`

A hash function (for GLib.HashTable) that corresponds to Soup.Address.equal_by_name(), qv

New in version 2.26.

is_resolved()¶

Returns:	`True` if self has been resolved.
Return type:	`bool`

Tests if self has already been resolved. Unlike the other Soup.Address “get” methods, this is safe to call when self might be being resolved in another thread.

resolve_async(async_context, cancellable, callback, *user_data)¶

Parameters:	async_context (`GLib.MainContext` or `None`) – the `GLib.MainContext` to call callback from cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable` object, or `None` callback (`Soup.AddressCallback`) – callback to call with the result user_data (`object` or `None`) – data for callback

Asynchronously resolves the missing half of self (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-None, 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().

resolve_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable` object, or `None`
Returns:	`Soup.Status.OK`, `Soup.Status.CANT_RESOLVE`, or `Soup.Status.CANCELLED`.
Return type:	`int`

Synchronously resolves the missing half of self, as with Soup.Address.resolve_async().

If cancellable is non-None, 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.

Property Details¶

Soup.Address.props.family¶

Name:	`family`
Type:	`Soup.AddressFamily`
Default Value:	`Soup.AddressFamily.INVALID`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Address family for this address

Soup.Address.props.name¶

Name:	`name`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Hostname for this address

Soup.Address.props.physical¶

Name:	`physical`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`

IP address for this address

Soup.Address.props.port¶

Name:	`port`
Type:	`int`
Default Value:	`-1`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Port for this address

Soup.Address.props.protocol¶

Name:	`protocol`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

URI scheme for this address

Soup.Address.props.sockaddr¶

Name:	`sockaddr`
Type:	`int`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

struct sockaddr for this address