Product documentation
Develop for XenServer
8 Citrix Hypervisor 8.2 CU1
View PDF

Class: session

June 19, 2024
Contributed by: 
X X

A session

Fields for class: session

Field Type Qualifier Description
auth_user_name string RO/runtime the subject name of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
auth_user_sid string RO/runtime the subject identifier of the user that was externally authenticated. If a session instance has is_local_superuser set, then the value of this field is undefined.
client_certificate bool RO/runtime indicates whether this session was authenticated using a client certificate
is_local_superuser bool RO/runtime true iff this session was created using local superuser credentials
last_active datetime RO/runtime Timestamp for last time session was active
originator string RO/runtime a key string provided by a API user to distinguish itself from other users sharing the same login name
other_config (string -> string) map RW additional configuration
parent session ref RO/constructor references the parent session that created this session
pool bool RO/runtime True if this session relates to a intra-pool login, false otherwise
rbac_permissions string set RO/constructor list with all RBAC permissions for this session
subject subject ref RO/runtime references the subject instance that created the session. If a session instance has is_local_superuser set, then the value of this field is undefined.
tasks task ref set RO/runtime list of tasks created using the current session
this_host host ref RO/runtime Currently connected host
this_user user ref RO/runtime Currently connected user
uuid string RO/runtime Unique identifier/object reference
validation_time datetime RO/runtime time when session was last validated

RPCs associated with class: session

RPC name: add_to_other_config

Overview:

Add the given key-value pair to the other_config field of the given session.

Signature:

void add_to_other_config (session ref session_ref, session ref self, string key, string value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
string key Key to add
string value Value to add

Minimum Role: pool-admin

Return Type: void

RPC name: change_password

Overview:

Change the account password; if your session is authenticated with root privileges then the old_pwd is validated and the new_pwd is set regardless

Signature:

void change_password (session ref session_ref, string old_pwd, string new_pwd)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string old_pwd Old password for account
string new_pwd New password for account

Return Type: void

RPC name: create_from_db_file

Overview:

Signature:

session ref create_from_db_file (session ref session_ref, string filename)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string filename Database dump filename.

Return Type: session ref

ID of newly created session

RPC name: get_all_subject_identifiers

Overview:

Return a list of all the user subject-identifiers of all existing sessions

Signature:

string set get_all_subject_identifiers (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: string set

The list of user subject-identifiers of all existing sessions

RPC name: get_auth_user_name

Overview:

Get the auth_user_name field of the given session.

Signature:

string get_auth_user_name (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_auth_user_sid

Overview:

Get the auth_user_sid field of the given session.

Signature:

string get_auth_user_sid (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_by_uuid

Overview:

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

Signature:

session ref get_by_uuid (session ref session_ref, string uuid)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return

Minimum Role: read-only

Return Type: session ref

reference to the object

RPC name: get_client_certificate

Overview:

Get the client_certificate field of the given session.

Signature:

bool get_client_certificate (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_is_local_superuser

Overview:

Get the is_local_superuser field of the given session.

Signature:

bool get_is_local_superuser (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_last_active

Overview:

Get the last_active field of the given session.

Signature:

datetime get_last_active (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: datetime

value of the field

RPC name: get_originator

Overview:

Get the originator field of the given session.

Signature:

string get_originator (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_other_config

Overview:

Get the other_config field of the given session.

Signature:

(string -> string) map get_other_config (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: (string -> string) map

value of the field

RPC name: get_parent

Overview:

Get the parent field of the given session.

Signature:

session ref get_parent (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: session ref

value of the field

RPC name: get_pool

Overview:

Get the pool field of the given session.

Signature:

bool get_pool (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: bool

value of the field

RPC name: get_rbac_permissions

Overview:

Get the rbac_permissions field of the given session.

Signature:

string set get_rbac_permissions (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: string set

value of the field

RPC name: get_record

Overview:

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

Signature:

session record get_record (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: session record

all fields from the object

RPC name: get_subject

Overview:

Get the subject field of the given session.

Signature:

subject ref get_subject (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: subject ref

value of the field

RPC name: get_tasks

Overview:

Get the tasks field of the given session.

Signature:

task ref set get_tasks (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: task ref set

value of the field

RPC name: get_this_host

Overview:

Get the this_host field of the given session.

Signature:

host ref get_this_host (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: host ref

value of the field

RPC name: get_this_user

Overview:

Get the this_user field of the given session.

Signature:

user ref get_this_user (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: user ref

value of the field

RPC name: get_uuid

Overview:

Get the uuid field of the given session.

Signature:

string get_uuid (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: string

value of the field

RPC name: get_validation_time

Overview:

Get the validation_time field of the given session.

Signature:

datetime get_validation_time (session ref session_ref, session ref self)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object

Minimum Role: read-only

Return Type: datetime

value of the field

RPC name: local_logout

Overview:

Log out of local session.

Signature:

void local_logout (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: pool-admin

Return Type: void

RPC name: login_with_password

Overview:

Attempt to authenticate the user, returning a session reference if successful

Signature:

session ref login_with_password (string uname, string pwd, string version, string originator)
<!--NeedCopy-->

Arguments:

Type Name Description
string uname Username for login.
string pwd Password for login.
string version Client API version.
string originator Key string for distinguishing different API users sharing the same login name.

Minimum Role: read-only

Return Type: session ref

reference of newly created session

Possible Error Codes: SESSION_AUTHENTICATION_FAILED, HOST_IS_SLAVE

RPC name: logout

Overview:

Log out of a session

Signature:

void logout (session ref session_ref)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session

Minimum Role: read-only

Return Type: void

RPC name: logout_subject_identifier

Overview:

Log out all sessions associated to a user subject-identifier, except the session associated with the context calling this function

Signature:

void logout_subject_identifier (session ref session_ref, string subject_identifier)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
string subject_identifier User subject-identifier of the sessions to be destroyed

Minimum Role: pool-operator

Return Type: void

RPC name: remove_from_other_config

Overview:

Remove the given key and its corresponding value from the other_config field of the given session. If the key is not in that Map, then do nothing.

Signature:

void remove_from_other_config (session ref session_ref, session ref self, string key)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
string key Key to remove

Minimum Role: pool-admin

Return Type: void

RPC name: set_other_config

Overview:

Set the other_config field of the given session.

Signature:

void set_other_config (session ref session_ref, session ref self, (string -> string) map value)
<!--NeedCopy-->

Arguments:

Type Name Description
session ref session_ref Reference to a valid session
session ref self reference to the object
(string -> string) map value New value to set

Minimum Role: pool-admin

Return Type: void

RPC name: slave_local_login_with_password

Overview:

Authenticate locally against a slave in emergency mode. Note the resulting sessions are only good for use on this host.

Signature:

session ref slave_local_login_with_password (string uname, string pwd)
<!--NeedCopy-->

Arguments:

Type Name Description
string uname Username for login.
string pwd Password for login.

Minimum Role: pool-admin

Return Type: session ref

ID of newly created session

Class: session
June 19, 2024
Contributed by: 
X X
June 19, 2024
Contributed by: 
X X

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.