IAllocation

#include <icy/turn/iallocation.h>

class IAllocation

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

Subclassed by: Client, ServerAllocation

Base class for TURN relay allocations shared by client and server flows.

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.

List of all members

Name	Kind	Owner
`operator<<`	`friend`	Declared here
`IAllocation`	`function`	Declared here
`~IAllocation`	`function`	Declared here
`IAllocation`	`function`	Declared here
`operator=`	`function`	Declared here
`IAllocation`	`function`	Declared here
`operator=`	`function`	Declared here
`updateUsage`	`function`	Declared here
`setLifetime`	`function`	Declared here
`setBandwidthLimit`	`function`	Declared here
`expired`	`function`	Declared here
`deleted`	`function`	Declared here
`bandwidthLimit`	`function`	Declared here
`bandwidthUsed`	`function`	Declared here
`bandwidthRemaining`	`function`	Declared here
`timeRemaining`	`function`	Declared here
`tuple`	`function`	Declared here
`username`	`function`	Declared here
`lifetime`	`function`	Declared here
`permissions`	`function`	Declared here
`relayedAddress`	`function`	Declared here
`addPermission`	`function`	Declared here
`addPermission`	`function`	Declared here
`addPermissions`	`function`	Declared here
`removePermission`	`function`	Declared here
`removePermission`	`function`	Declared here
`removeAllPermissions`	`function`	Declared here
`removeExpiredPermissions`	`function`	Declared here
`hasPermission`	`function`	Declared here
`hasPermission`	`function`	Declared here
`print`	`function`	Declared here
`_tuple`	`variable`	Declared here
`_username`	`variable`	Declared here
`_permissions`	`variable`	Declared here
`_lifetime`	`variable`	Declared here
`_bandwidthLimit`	`variable`	Declared here
`_bandwidthUsed`	`variable`	Declared here
`_createdAt`	`variable`	Declared here
`_updatedAt`	`variable`	Declared here
`_deleted`	`variable`	Declared here

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`	Deleted constructor.
	`IAllocation`	Deleted constructor.
`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

tuple The 5-tuple identifying this allocation.
username Authenticated username associated with this allocation.
lifetime Initial lifetime in seconds.

IAllocation

IAllocation(const IAllocation &) = delete

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

Deleted constructor.

IAllocation

IAllocation(IAllocation &&) = delete

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

Deleted constructor.

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

numBytes 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

lifetime 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

numBytes 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

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.

Parameters

ip IPv4 address string to permit.

Reimplemented by

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

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

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

Parameters

ip IPv4 address string to remove.

Reimplemented by

removePermission

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

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.

Parameters

peerIP IPv4 address string to check.

Returns

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

Reimplemented by

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

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`