Xapi Project Docs

Prototype

Class: Caller

XAPI caller description and rate limiting

Prototyped in:

XAPI 26.17.0 (26.17.0)

Fields

Prototype

bool auto_registered [RO/runtime]

True if this caller was created automatically by the rate limiter rather than by an administrator. Auto-registered callers are subject to the max-auto-registered-callers cap.

Default value:	false
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string client_ip [RO/constructor]

Client IP matching pattern. Same wildcard semantics as user_agent.

Default value:	""
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string set groups [RO/runtime]

Groups to which this caller has been assigned

Default value:	{}
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

datetime last_access [RO/runtime]

Last time a call was received from this caller

Default value:	19700101T00:00:00Z
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string name_description [RW]

a notes field containing human-readable description

Default value:	""
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string name_label [RW]

a human-readable name

Default value:	""
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

Rate_limit ref rate_limit [RO/runtime]

Rate limiter attached to this caller, if any. Populated via Rate_limit.add_caller rather than set directly.

Default value:	OpaqueRef:NULL
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string user_agent [RO/constructor]

User agent matching pattern. Empty string is a full wildcard; a trailing '*' makes the field a prefix pattern; otherwise the field is matched exactly.

Default value:	""
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string uuid [RO/runtime]

Unique identifier/object reference

Prototyped in:

XAPI 26.17.0 (26.17.0)

Messages

Prototype

void add_group (session ref, Caller ref, string)

Add a caller to a group

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	The caller to update
	string group	Group the caller is being added to
Minimum role:	pool-operator
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

Caller ref create (session ref, Caller record)

Create a new Caller instance, and return its handle. The constructor args are: name_label, name_description, user_agent, client_ip (* = non-optional).

Parameters:	session ref session_id	Reference to a valid session
	Caller record args	All constructor arguments
Minimum role:	pool-admin
Result:	reference to the newly created object
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

void destroy (session ref, Caller ref)

Destroy the specified Caller instance.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	pool-admin
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

Caller ref set get_all (session ref)

Return a list of all the Callers known to the system.

Parameters:	session ref session_id	Reference to a valid session
Minimum role:	read-only
Result:	references to all objects
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

(Caller ref → Caller record) map get_all_records (session ref)

Return a map of Caller references to Caller records for all Callers known to the system.

Parameters:	session ref session_id	Reference to a valid session
Minimum role:	read-only
Result:	records of all objects
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

bool get_auto_registered (session ref, Caller ref)

Get the auto_registered field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

Caller ref set get_by_name_label (session ref, string)

Get all the Caller instances with the given label.

Parameters:	session ref session_id	Reference to a valid session
	string label	label of object to return
Minimum role:	read-only
Result:	references to objects with matching names
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

Caller ref get_by_uuid (session ref, string)

Get a reference to the Caller instance with the specified UUID.

Parameters:	session ref session_id	Reference to a valid session
	string uuid	UUID of object to return
Minimum role:	read-only
Result:	reference to the object
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string get_client_ip (session ref, Caller ref)

Get the client_ip field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string set get_groups (session ref, Caller ref)

Get the groups field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

datetime get_last_access (session ref, Caller ref)

Get the last_access field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string get_name_description (session ref, Caller ref)

Get the name/description field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string get_name_label (session ref, Caller ref)

Get the name/label field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

Rate_limit ref get_rate_limit (session ref, Caller ref)

Get the rate_limit field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

Caller record get_record (session ref, Caller ref)

Get a record containing the current state of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	all fields from the object
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string get_user_agent (session ref, Caller ref)

Get the user_agent field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string get_uuid (session ref, Caller ref)

Get the uuid field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
Minimum role:	read-only
Result:	value of the field
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

string set set query_all_usage (session ref)

Return per-caller usage for every known caller, sorted by token use descending.

Parameters:	session ref session_id	Reference to a valid session
Minimum role:	pool-operator
Result:	Rows of [uuid; name_label; tokens; calls], highest tokens first
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

int query_call_count (session ref, Caller ref)

Return number of calls made by this caller since Xapi startup

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	The caller to query
Minimum role:	pool-operator
Result:	Calls made by the caller since Xapi startup
Prototyped in:	XAPI 26.15.0 (26.15.0)

Prototype

int query_group_call_count (session ref, string)

Return number of calls made since Xapi startup by the callers in the named group.

Parameters:	session ref session_id	Reference to a valid session
	string group	Caller group to aggregate over
Minimum role:	pool-operator
Result:	Number of calls made by the callers in the group
Prototyped in:	XAPI 26.15.0 (26.15.0)

Prototype

float query_group_token_usage (session ref, string)

Return tokens used since Xapi startup by the callers in the named group.

Parameters:	session ref session_id	Reference to a valid session
	string group	Caller group to aggregate over
Minimum role:	pool-operator
Result:	Tokens used by the group since Xapi startup
Prototyped in:	XAPI 26.15.0 (26.15.0)

Prototype

float query_token_usage (session ref, Caller ref)

Return tokens used by this caller since Xapi startup

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	The caller to query
Minimum role:	pool-operator
Result:	Tokens used by the caller since Xapi startup
Prototyped in:	XAPI 26.15.0 (26.15.0)

Prototype

void remove_group (session ref, Caller ref, string)

Remove a caller from a group

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	The caller to update
	string group	Group the caller is removed from
Minimum role:	pool-operator
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

void set_name_description (session ref, Caller ref, string)

Set the name/description field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
	string value	New value to set
Minimum role:	pool-admin
Prototyped in:	XAPI 26.17.0 (26.17.0)

Prototype

void set_name_label (session ref, Caller ref, string)

Set the name/label field of the given Caller.

Parameters:	session ref session_id	Reference to a valid session
	Caller ref self	reference to the object
	string value	New value to set
Minimum role:	pool-admin
Prototyped in:	XAPI 26.17.0 (26.17.0)

Class: Caller

Fields

Messages Hide implicit

Classes

Messages