Class: session
A session
| Published in: | XenServer 4.0 (rio) | A session |
Fields
string
auth_user_name
[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.
| Default value: | "" | |
| Published in: | XenServer 5.6 (midnight-ride) | 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. |
string
auth_user_sid
[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.
| Default value: | "" | |
| Published in: | XenServer 5.5 (george) | 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. |
bool
client_certificate
[RO/runtime]
indicates whether this session was authenticated using a client certificate
| Default value: | false | |
| Published in: | XAPI 21.2.0 (21.2.0) | indicates whether this session was authenticated using a client certificate |
bool
is_local_superuser
[RO/runtime]
true iff this session was created using local superuser credentials
| Default value: | false | |
| Published in: | XenServer 5.5 (george) | true iff this session was created using local superuser credentials |
datetime
last_active
[RO/runtime]
Timestamp for last time session was active
| Published in: | XenServer 4.0 (rio) | Timestamp for last time session was active |
string
originator
[RO/runtime]
a key string provided by a API user to distinguish itself from other users sharing the same login name
| Default value: | "" | |
| Published in: | XenServer 6.2 (clearwater) | a key string provided by a API user to distinguish itself from other users sharing the same login name |
(string → string) map
other_config
[RW]
additional configuration
| Default value: | {} | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
session ref
parent
[RO/constructor]
references the parent session that created this session
| Default value: | OpaqueRef:NULL | |
| Published in: | XenServer 5.6 (midnight-ride) | references the parent session that created this session |
bool
pool
[RO/runtime]
True if this session relates to a intra-pool login, false otherwise
| Published in: | XenServer 4.0 (rio) | True if this session relates to a intra-pool login, false otherwise |
string set
rbac_permissions
[RO/constructor]
list with all RBAC permissions for this session
| Default value: | {} | |
| Published in: | XenServer 5.6 (midnight-ride) | list with all RBAC permissions for this session |
subject ref
subject
[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.
| Default value: | OpaqueRef:NULL | |
| Published in: | XenServer 5.5 (george) | 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. |
task ref set
tasks
[RO/runtime]
list of tasks created using the current session
| Published in: | XenServer 5.6 (midnight-ride) | list of tasks created using the current session |
host ref
this_host
[RO/runtime]
Currently connected host
| Published in: | XenServer 4.0 (rio) | Currently connected host |
user ref
this_user
[RO/runtime]
Currently connected user
| Published in: | XenServer 4.0 (rio) | Currently connected user |
string
uuid
[RO/runtime]
Unique identifier/object reference
| Published in: | XenServer 4.0 (rio) | Unique identifier/object reference |
datetime
validation_time
[RO/runtime]
time when session was last validated
| Default value: | 19700101T00:00:00Z | |
| Published in: | XenServer 5.5 (george) | time when session was last validated |
Messages
void
add_to_other_config
(session ref, session ref, string, string)
Add the given key-value pair to the other_config field of the given session.
| Parameters: | session ref session_id | 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 | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
void
change_password
(session ref, string, string)
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
| Parameters: | session ref session_id | Reference to a valid session |
| string old_pwd | Old password for account | |
| string new_pwd | New password for account | |
| Minimum role: | ||
| Published in: | XenServer 4.0 (rio) | 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 |
session ref
create_from_db_file
(session ref, string)
| Parameters: | session ref session_id | Reference to a valid session |
| string filename | Database dump filename. | |
| Minimum role: | ||
| Result: | ID of newly created session | |
| Published in: | XenServer 7.0 (dundee) | |
string set
get_all_subject_identifiers
(session ref)
Return a list of all the user subject-identifiers of all existing sessions
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | The list of user subject-identifiers of all existing sessions | |
| Published in: | XenServer 5.5 (george) | Return a list of all the user subject-identifiers of all existing sessions |
string
get_auth_user_name
(session ref, session ref)
Get the auth_user_name field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.6 (midnight-ride) | 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. |
string
get_auth_user_sid
(session ref, session ref)
Get the auth_user_sid field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.5 (george) | 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. |
session ref
get_by_uuid
(session ref, string)
Get a reference to the session 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 | |
| Published in: | XenServer 4.0 (rio) | A session |
bool
get_client_certificate
(session ref, session ref)
Get the client_certificate field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XAPI 21.2.0 (21.2.0) | indicates whether this session was authenticated using a client certificate |
bool
get_is_local_superuser
(session ref, session ref)
Get the is_local_superuser field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.5 (george) | true iff this session was created using local superuser credentials |
datetime
get_last_active
(session ref, session ref)
Get the last_active field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | Timestamp for last time session was active |
string
get_originator
(session ref, session ref)
Get the originator field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 6.2 (clearwater) | a key string provided by a API user to distinguish itself from other users sharing the same login name |
(string → string) map
get_other_config
(session ref, session ref)
Get the other_config field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
session ref
get_parent
(session ref, session ref)
Get the parent field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.6 (midnight-ride) | references the parent session that created this session |
bool
get_pool
(session ref, session ref)
Get the pool field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | True if this session relates to a intra-pool login, false otherwise |
string set
get_rbac_permissions
(session ref, session ref)
Get the rbac_permissions field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.6 (midnight-ride) | list with all RBAC permissions for this session |
session record
get_record
(session ref, session ref)
Get a record containing the current state of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | all fields from the object | |
| Published in: | XenServer 4.0 (rio) | A session |
subject ref
get_subject
(session ref, session ref)
Get the subject field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.5 (george) | 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. |
task ref set
get_tasks
(session ref, session ref)
Get the tasks field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.6 (midnight-ride) | list of tasks created using the current session |
host ref
get_this_host
(session ref, session ref)
Get the this_host field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | Currently connected host |
user ref
get_this_user
(session ref, session ref)
Get the this_user field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | Currently connected user |
string
get_uuid
(session ref, session ref)
Get the uuid field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | Unique identifier/object reference |
datetime
get_validation_time
(session ref, session ref)
Get the validation_time field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.5 (george) | time when session was last validated |
void
local_logout
(session ref)
Log out of local session.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | pool-admin | |
| Published in: | XenServer 4.1 (miami) | Log out of local session. |
session ref
login_with_password
(string, string, string, string)
Attempt to authenticate the user, returning a session reference if successful
| Parameters: | 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 | |
| Result: | reference of newly created session | |
| Errors: | SESSION_AUTHENTICATION_FAILED | The credentials given by the user are incorrect, so access has been denied, and you have not been issued a session handle. |
| HOST_IS_SLAVE | You cannot make regular API calls directly on a supporter. Please pass API calls via the coordinator host. | |
| Published in: | XenServer 4.0 (rio) | Attempt to authenticate the user, returning a session reference if successful |
void
logout
(session ref)
Log out of a session
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Published in: | XenServer 4.0 (rio) | Log out of a session |
void
logout_subject_identifier
(session ref, string)
Log out all sessions associated to a user subject-identifier, except the session associated with the context calling this function
| Parameters: | session ref session_id | Reference to a valid session |
| string subject_identifier | User subject-identifier of the sessions to be destroyed | |
| Minimum role: | pool-operator | |
| Published in: | XenServer 5.5 (george) | Log out all sessions associated to a user subject-identifier, except the session associated with the context calling this function |
void
remove_from_other_config
(session ref, session ref, string)
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.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| string key | Key to remove | |
| Minimum role: | pool-admin | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
void
set_other_config
(session ref, session ref, (string → string) map)
Set the other_config field of the given session.
| Parameters: | session ref session_id | Reference to a valid session |
| session ref self | reference to the object | |
| (string → string) map value | New value to set | |
| Minimum role: | pool-admin | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
session ref
slave_local_login_with_password
(string, string)
Authenticate locally against a slave in emergency mode. Note the resulting sessions are only good for use on this host.
| Parameters: | string uname | Username for login. |
| string pwd | Password for login. | |
| Minimum role: | pool-admin | |
| Result: | ID of newly created session | |
| Published in: | XenServer 4.1 (miami) | Authenticate locally against a slave in emergency mode. Note the resulting sessions are only good for use on this host. |