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` ()
	`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()¶

Returns:

the sockaddr, or None

len:: return location for sockaddr length

Return type:

(object or None, len: int)

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