Class: task
A long-running asynchronous task
| Published in: | XenServer 4.0 (rio) | A long-running asynchronous task |
Enums
task_allowed_operations
| Values: | cancel | refers to the operation "cancel" |
| destroy | refers to the operation "destroy" |
task_status_type
| Values: | pending | task is in progress |
| success | task was completed successfully | |
| failure | task has failed | |
| cancelling | task is being cancelled | |
| cancelled | task has been cancelled |
Fields
enum task_allowed_operations set
allowed_operations
[RO/runtime]
list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
| Default value: | {} | |
| Published in: | XenServer 4.0 (rio) | list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client. |
string
backtrace
[RO/runtime]
Function call trace for debugging.
| Default value: | "()" | |
| Published in: | XenServer 7.0 (dundee) | Function call trace for debugging. |
datetime
created
[RO/runtime]
Time task was created
| Published in: | XenServer 4.0 (rio) | Time task was created |
(string → enum task_allowed_operations) map
current_operations
[RO/runtime]
links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
| Default value: | {} | |
| Published in: | XenServer 4.0 (rio) | links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task. |
string set
error_info
[RO/runtime]
if the task has failed, this field contains the set of associated error strings. Undefined otherwise.
| Published in: | XenServer 4.0 (rio) | if the task has failed, this field contains the set of associated error strings. Undefined otherwise. |
datetime
finished
[RO/runtime]
Time task finished (i.e. succeeded or failed). If task-status is pending, then the value of this field has no meaning
| Published in: | XenServer 4.0 (rio) | Time task finished (i.e. succeeded or failed). If task-status is pending, then the value of this field has no meaning |
string
name_description
[RO/runtime]
a notes field containing human-readable description
| Default value: | "" | |
| Published in: | XenServer 4.0 (rio) | a notes field containing human-readable description |
string
name_label
[RO/runtime]
a human-readable name
| Default value: | "" | |
| Published in: | XenServer 4.0 (rio) | a human-readable name |
(string → string) map
other_config
[RW]
additional configuration
| Default value: | {} | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
float
progress
[RO/runtime]
This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used.
| Published in: | XenServer 4.0 (rio) | This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used. |
host ref
resident_on
[RO/runtime]
the host on which the task is running
| Published in: | XenServer 4.0 (rio) | the host on which the task is running |
string
result
[RO/runtime]
if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise.
| Published in: | XenServer 4.0 (rio) | if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise. |
enum task_status_type
status
[RO/runtime]
current status of the task
| Published in: | XenServer 4.0 (rio) | current status of the task |
task ref
subtask_of
[RO/runtime]
Ref pointing to the task this is a substask of.
| Default value: | Null | |
| Published in: | XenServer 5.0 (orlando) | Ref pointing to the task this is a substask of. |
task ref set
subtasks
[RO/runtime]
List pointing to all the substasks.
| Published in: | XenServer 5.0 (orlando) | List pointing to all the substasks. |
string
type
[RO/runtime]
if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise.
| Published in: | XenServer 4.0 (rio) | if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise. |
string
uuid
[RO/runtime]
Unique identifier/object reference
| Published in: | XenServer 4.0 (rio) | Unique identifier/object reference |
Messages
void
add_to_other_config
(session ref, task ref, string, string)
Add the given key-value pair to the other_config field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| string key | Key to add | |
| string value | Value to add | |
| Minimum role: | pool-operator | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
void
cancel
(session ref, task ref)
Request that a task be cancelled. Note that a task may fail to be cancelled and may complete or fail normally and note that, even when a task does cancel, it might take an arbitrary amount of time.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref task | The task | |
| Minimum role: | read-only | |
| Errors: | OPERATION_NOT_ALLOWED | You attempted an operation that was not allowed. |
| Published in: | XenServer 4.0 (rio) | Request that a task be cancelled. Note that a task may fail to be cancelled and may complete or fail normally and note that, even when a task does cancel, it might take an arbitrary amount of time. |
task ref
create
(session ref, string, string)
Create a new task object which must be manually destroyed.
| Parameters: | session ref session_id | Reference to a valid session |
| string label | short label for the new task | |
| string description | longer description for the new task | |
| Minimum role: | read-only | |
| Result: | The reference of the created task object | |
| Published in: | XenServer 4.0 (rio) | Create a new task object which must be manually destroyed. |
void
destroy
(session ref, task ref)
Destroy the task object
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | Reference to the task object | |
| Minimum role: | read-only | |
| Published in: | XenServer 4.0 (rio) | Destroy the task object |
task ref set
get_all
(session ref)
Return a list of all the tasks known to the system.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | references to all objects | |
| Published in: | XenServer 4.0 (rio) | A long-running asynchronous task |
(task ref → task record) map
get_all_records
(session ref)
Return a map of task references to task records for all tasks known to the system.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | records of all objects | |
| Published in: | XenServer 4.0 (rio) | A long-running asynchronous task |
enum task_allowed_operations set
get_allowed_operations
(session ref, task ref)
Get the allowed_operations field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client. |
string
get_backtrace
(session ref, task ref)
Get the backtrace field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 7.0 (dundee) | Function call trace for debugging. |
task ref set
get_by_name_label
(session ref, string)
Get all the task 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 | |
| Published in: | XenServer 4.0 (rio) | A long-running asynchronous task |
task ref
get_by_uuid
(session ref, string)
Get a reference to the task 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 long-running asynchronous task |
datetime
get_created
(session ref, task ref)
Get the created field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | Time task was created |
(string → enum task_allowed_operations) map
get_current_operations
(session ref, task ref)
Get the current_operations field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task. |
string set
get_error_info
(session ref, task ref)
Get the error_info field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | if the task has failed, this field contains the set of associated error strings. Undefined otherwise. |
datetime
get_finished
(session ref, task ref)
Get the finished field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | Time task finished (i.e. succeeded or failed). If task-status is pending, then the value of this field has no meaning |
string
get_name_description
(session ref, task ref)
Get the name/description field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | a notes field containing human-readable description |
string
get_name_label
(session ref, task ref)
Get the name/label field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | a human-readable name |
(string → string) map
get_other_config
(session ref, task ref)
Get the other_config field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
float
get_progress
(session ref, task ref)
Get the progress field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used. |
task record
get_record
(session ref, task ref)
Get a record containing the current state of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | all fields from the object | |
| Published in: | XenServer 4.0 (rio) | A long-running asynchronous task |
host ref
get_resident_on
(session ref, task ref)
Get the resident_on field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | the host on which the task is running |
string
get_result
(session ref, task ref)
Get the result field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise. |
enum task_status_type
get_status
(session ref, task ref)
Get the status field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | current status of the task |
task ref
get_subtask_of
(session ref, task ref)
Get the subtask_of field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.0 (orlando) | Ref pointing to the task this is a substask of. |
task ref set
get_subtasks
(session ref, task ref)
Get the subtasks field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 5.0 (orlando) | List pointing to all the substasks. |
string
get_type
(session ref, task ref)
Get the type field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| Minimum role: | read-only | |
| Result: | value of the field | |
| Published in: | XenServer 4.0 (rio) | if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise. |
string
get_uuid
(session ref, task ref)
Get the uuid field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task 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 |
void
remove_from_other_config
(session ref, task ref, string)
Remove the given key and its corresponding value from the other_config field of the given task. If the key is not in that Map, then do nothing.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| string key | Key to remove | |
| Minimum role: | pool-operator | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
void
set_error_info
(session ref, task ref, string set)
Set the task error info
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | Reference to the task object | |
| string set value | Task error info to be set | |
| Minimum role: | read-only | |
| Published in: | XAPI 21.3.0 (21.3.0) | Set the task error info |
void
set_other_config
(session ref, task ref, (string → string) map)
Set the other_config field of the given task.
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | reference to the object | |
| (string → string) map value | New value to set | |
| Minimum role: | pool-operator | |
| Published in: | XenServer 4.1 (miami) | additional configuration |
void
set_progress
(session ref, task ref, float)
Set the task progress
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | Reference to the task object | |
| float value | Task progress value to be set | |
| Minimum role: | read-only | |
| Published in: | Citrix Hypervisor 8.2 (stockholm) | Set the task progress |
void
set_result
(session ref, task ref, string)
Set the task result
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | Reference to the task object | |
| string value | Task result to be set | |
| Minimum role: | read-only | |
| Published in: | XAPI 21.3.0 (21.3.0) | Set the task result |
void
set_status
(session ref, task ref, enum task_status_type)
Set the task status
| Parameters: | session ref session_id | Reference to a valid session |
| task ref self | Reference to the task object | |
| enum task_status_type value | task status value to be set | |
| Minimum role: | read-only | |
| Published in: | XenServer 7.2 (falcon) | Set the task status |