IAllocation

#include <icy/turn/iallocation.h>

class IAllocation

Defined in src/turn/include/icy/turn/iallocation.h:75

Subclassed by: Client, ServerAllocation

All TURN operations revolve around allocations, and all TURN messages are associated with an allocation. An allocation conceptually consists of:

the relayed transport address;
the 5-tuple: client's IP address, client's port, server IP address, server port, and transport protocol;
the authentication information;
the time-to-expiry;
a list of permissions;
a list of channel-to-peer bindings.

The relayed transport address is the transport address allocated by the server for communicating with peers, while the 5-tuple describes the communication path between the client and the server. On the client, the 5-tuple uses the client's host transport address; on the server, the 5-tuple uses the client's server-reflexive transport address.

Both the relayed transport address and the 5-tuple must be unique across all allocations, so either one can be used to uniquely identify the allocation.

The authentication information, such as username, password, realm, and nonce, is used to verify subsequent requests and compute the message integrity of responses. The username, realm, and nonce values are initially those used in the authenticated Allocate request that creates the allocation, though the server can change the nonce during the allocation lifetime using a 438 (Stale Nonce) reply. Rather than storing the password explicitly, a server may prefer to store the key value, which is an MD5 hash over the username, realm, and password as described by RFC 5389.

The time-to-expiry is the time left until the allocation expires. Each Allocate or Refresh transaction resets this timer, which then ticks down toward zero. By default, each Allocate or Refresh resets the lifetime to 600 seconds (10 minutes), but the client can request a different value in the Allocate and Refresh requests. Allocations can only be refreshed using Refresh; sending data to a peer does not refresh an allocation. When an allocation expires, the state data associated with it can be freed.

Friends

Name	Description
`operator<<` inline

operator<<

inline

friend inline std::ostream & operator<<(std::ostream & stream, const IAllocation & alloc)

Defined in src/turn/include/icy/turn/iallocation.h:187

Public Methods

Return	Name	Description
	`IAllocation`
	`~IAllocation` virtual
	`IAllocation`	Deleted constructor.
`IAllocation` &	`operator=`	Deleted assignment operator.
	`IAllocation`	Deleted constructor.
`IAllocation` &	`operator=`	Deleted assignment operator.
`void`	`updateUsage` virtual	Updates the last-activity timestamp and accumulates bandwidth usage. Call this whenever data is relayed through the allocation.
`void`	`setLifetime` virtual	Sets the allocation lifetime in seconds and resets the activity timestamp, effectively extending the expiry from the current moment.
`void`	`setBandwidthLimit` virtual	Sets the maximum number of bytes this allocation may relay in its lifetime. Pass 0 to disable bandwidth limiting.
`bool`	`expired` virtual const
`bool`	`deleted` virtual const	Returns true if the allocation's deleted flag is set and or if the allocation has expired.
`std::int64_t`	`bandwidthLimit` virtual const
`std::int64_t`	`bandwidthUsed` virtual const
`std::int64_t`	`bandwidthRemaining` virtual const
`std::int64_t`	`timeRemaining` virtual const
`FiveTuple` &	`tuple` virtual
`std::string`	`username` virtual const
`std::int64_t`	`lifetime` virtual const
`PermissionList`	`permissions` virtual const
`net::Address`	`relayedAddress` virtual const
`void`	`addPermission` virtual	Adds a permission for `ip`, or refreshes the existing one.
`void`	`addPermission` virtual	Adds a permission for `address`, or refreshes the existing one. The port is ignored; TURN permissions are IP-only.
`void`	`addPermissions` virtual	Adds (or refreshes) permissions for multiple IPs.
`void`	`removePermission` virtual	Removes the permission for `ip` if present.
`void`	`removePermission` virtual	Removes the permission for `address` if present. The port is ignored; TURN permissions are IP-only.
`void`	`removeAllPermissions` virtual	Removes all permissions from the list.
`void`	`removeExpiredPermissions` virtual	Removes any permissions whose 5-minute lifetime has elapsed.
`bool`	`hasPermission` virtual	Checks whether a permission exists for `peerIP`. Local addresses (192.168.x.x and 127.x.x.x) are always permitted.
`bool`	`hasPermission` virtual	Checks whether a permission exists for `peerAddress`. The port is ignored; TURN permissions are IP-only.
`void`	`print` virtual const inline

IAllocation

IAllocation(const FiveTuple & tuple = FiveTuple(), const std::string & username = "", std::int64_t lifetime = kDefaultAllocationLifetime)

Defined in src/turn/include/icy/turn/iallocation.h:81

Parameters

Parameter	Type	Description
`tuple`	const `FiveTuple` &	The 5-tuple identifying this allocation.
`username`	`const std::string &`	Authenticated username associated with this allocation.
`lifetime`	`std::int64_t`	Initial lifetime in seconds.

~IAllocation

virtual

virtual ~IAllocation()

Defined in src/turn/include/icy/turn/iallocation.h:84

IAllocation

IAllocation(const IAllocation &) = delete

Defined in src/turn/include/icy/turn/iallocation.h:86

Deleted constructor.

operator=

IAllocation & operator=(const IAllocation &) = delete

Defined in src/turn/include/icy/turn/iallocation.h:87

Deleted assignment operator.

IAllocation

IAllocation(IAllocation &&) = delete

Defined in src/turn/include/icy/turn/iallocation.h:88

Deleted constructor.

operator=

IAllocation & operator=(IAllocation &&) = delete

Defined in src/turn/include/icy/turn/iallocation.h:89

Deleted assignment operator.

updateUsage

virtual

virtual void updateUsage(std::int64_t numBytes = 0)

Defined in src/turn/include/icy/turn/iallocation.h:94

Updates the last-activity timestamp and accumulates bandwidth usage. Call this whenever data is relayed through the allocation.

Parameters

Parameter	Type	Description
`numBytes`	`std::int64_t`	Number of bytes relayed (0 just refreshes the timestamp).

setLifetime

virtual

virtual void setLifetime(std::int64_t lifetime)

Defined in src/turn/include/icy/turn/iallocation.h:99

Sets the allocation lifetime in seconds and resets the activity timestamp, effectively extending the expiry from the current moment.

Parameters

Parameter	Type	Description
`lifetime`	`std::int64_t`	New lifetime in seconds.

setBandwidthLimit

virtual

virtual void setBandwidthLimit(std::int64_t numBytes)

Defined in src/turn/include/icy/turn/iallocation.h:104

Sets the maximum number of bytes this allocation may relay in its lifetime. Pass 0 to disable bandwidth limiting.

Parameters

Parameter	Type	Description
`numBytes`	`std::int64_t`	Bandwidth cap in bytes (0 = unlimited).

expired

virtual const

virtual bool expired() const

Defined in src/turn/include/icy/turn/iallocation.h:108

Returns

true if the allocation's lifetime has elapsed or the bandwidth quota has been exhausted.

deleted

virtual const

virtual bool deleted() const

Defined in src/turn/include/icy/turn/iallocation.h:116

Returns true if the allocation's deleted flag is set and or if the allocation has expired.

This signifies that the allocation is ready to be destroyed via async garbage collection. See Server::onTimer() and Client::onTimer()

bandwidthLimit

virtual const

virtual std::int64_t bandwidthLimit() const

Defined in src/turn/include/icy/turn/iallocation.h:119

Returns

The configured bandwidth limit in bytes (0 means unlimited).

bandwidthUsed

virtual const

virtual std::int64_t bandwidthUsed() const

Defined in src/turn/include/icy/turn/iallocation.h:122

Returns

Total bytes transferred through this allocation since creation.

bandwidthRemaining

virtual const

virtual std::int64_t bandwidthRemaining() const

Defined in src/turn/include/icy/turn/iallocation.h:126

Returns

Bytes remaining before the bandwidth quota is exhausted. Returns a large sentinel value when no limit is configured.

timeRemaining

virtual const

virtual std::int64_t timeRemaining() const

Defined in src/turn/include/icy/turn/iallocation.h:129

Returns

Seconds until the allocation expires (0 if already expired).

Reimplemented by

ServerAllocation::timeRemaining

tuple

virtual

virtual FiveTuple & tuple()

Defined in src/turn/include/icy/turn/iallocation.h:132

Returns

Reference to the 5-tuple identifying this allocation.

username

virtual const

virtual std::string username() const

Defined in src/turn/include/icy/turn/iallocation.h:135

Returns

The username associated with this allocation.

lifetime

virtual const

virtual std::int64_t lifetime() const

Defined in src/turn/include/icy/turn/iallocation.h:138

Returns

The configured lifetime in seconds.

permissions

virtual const

virtual PermissionList permissions() const

Defined in src/turn/include/icy/turn/iallocation.h:141

Returns

A copy of the current permission list.

relayedAddress

virtual const

virtual net::Address relayedAddress() const

Defined in src/turn/include/icy/turn/iallocation.h:144

Returns

The relay transport address assigned to this allocation.

Reimplemented by

addPermission

virtual

virtual void addPermission(const std::string & ip)

Defined in src/turn/include/icy/turn/iallocation.h:148

Adds a permission for ip, or refreshes the existing one.

Reimplemented by

Parameters

Parameter	Type	Description
`ip`	`const std::string &`	IPv4 address string to permit.

addPermission

virtual

virtual void addPermission(const net::Address & address)

Defined in src/turn/include/icy/turn/iallocation.h:152

Adds a permission for address, or refreshes the existing one. The port is ignored; TURN permissions are IP-only.

Reimplemented by

Client::addPermission

addPermissions

virtual

virtual void addPermissions(const IPList & ips)

Defined in src/turn/include/icy/turn/iallocation.h:156

Adds (or refreshes) permissions for multiple IPs.

Parameters

Parameter	Type	Description
`ips`	const `IPList` &	List of IPv4 address strings.

removePermission

virtual

virtual void removePermission(const std::string & ip)

Defined in src/turn/include/icy/turn/iallocation.h:160

Removes the permission for ip if present.

Reimplemented by

Client::removePermission

Parameters

Parameter	Type	Description
`ip`	`const std::string &`	IPv4 address string to remove.

removePermission

virtual

virtual void removePermission(const net::Address & address)

Defined in src/turn/include/icy/turn/iallocation.h:164

Removes the permission for address if present. The port is ignored; TURN permissions are IP-only.

Reimplemented by

Client::removePermission

removeAllPermissions

virtual

virtual void removeAllPermissions()

Defined in src/turn/include/icy/turn/iallocation.h:167

Removes all permissions from the list.

removeExpiredPermissions

virtual

virtual void removeExpiredPermissions()

Defined in src/turn/include/icy/turn/iallocation.h:170

Removes any permissions whose 5-minute lifetime has elapsed.

hasPermission

virtual

virtual bool hasPermission(const std::string & peerIP)

Defined in src/turn/include/icy/turn/iallocation.h:176

Checks whether a permission exists for peerIP. Local addresses (192.168.x.x and 127.x.x.x) are always permitted.

Returns

true if a valid (non-expired) permission exists.

Reimplemented by

Parameters

Parameter	Type	Description
`peerIP`	`const std::string &`	IPv4 address string to check.

hasPermission

virtual

virtual bool hasPermission(const net::Address & peerAddress)

Defined in src/turn/include/icy/turn/iallocation.h:180

Checks whether a permission exists for peerAddress. The port is ignored; TURN permissions are IP-only.

Reimplemented by

print

virtual const inline

virtual inline void print(std::ostream & os) const

Defined in src/turn/include/icy/turn/iallocation.h:182

Reimplemented by

ServerAllocation::print

Protected Attributes

Return	Name	Description
`FiveTuple`	`_tuple`
`std::string`	`_username`
`PermissionList`	`_permissions`
`std::int64_t`	`_lifetime`
`std::int64_t`	`_bandwidthLimit`
`std::int64_t`	`_bandwidthUsed`
`time_t`	`_createdAt`
`time_t`	`_updatedAt`
`bool`	`_deleted`