navigation
Class: event
Asynchronous event registration and handling
| Published in: | XenServer 4.0 (rio) |
Enums
event_operation
| Values: | add | An object has been created |
| del | An object has been deleted | |
| mod | An object has been modified |
Fields
string
class
[RO/constructor]
The name of the class of the object that changed
| Published in: | XenServer 4.0 (rio) | The name of the class of the object that changed |
int
id
[RO/constructor]
An ID, monotonically increasing, and local to the current session
| Published in: | XenServer 4.0 (rio) | An ID, monotonically increasing, and local to the current session |
Deprecated
string
obj_uuid
[RO/constructor]
The uuid of the object that changed
| Published in: | XenServer 4.0 (rio) | The uuid of the object that changed |
| Deprecated in: | XenServer 6.0 (boston) |
enum event_operation
operation
[RO/constructor]
The operation that was performed
| Published in: | XenServer 4.0 (rio) | The operation that was performed |
string
ref
[RO/constructor]
A reference to the object that changed
| Published in: | XenServer 4.0 (rio) | A reference to the object that changed |
<class> record
snapshot
[RO/runtime]
The record of the database object that was added, changed or deleted
| Published in: | XenServer 6.0 (boston) |
Deprecated
datetime
timestamp
[RO/constructor]
The time at which the event occurred
| Published in: | XenServer 4.0 (rio) | The time at which the event occurred |
| Deprecated in: | XenServer 6.0 (boston) |
Messages
an event batch
from
(session ref, string set, string, float)
Blocking call which returns a new token and a (possibly empty) batch of events. The returned token can be used in subsequent calls to this function.
| Parameters: | session ref session_id | Reference to a valid session |
| string set classes | register for events for the indicated classes | |
| string token | A token representing the point from which to generate database events. The empty string represents the beginning. | |
| float timeout | Return after this many seconds if no events match | |
| Minimum role: | read-only | |
| Result: | a structure consisting of a token ('token'), a map of valid references per object type ('valid_ref_counts'), and a set of event records ('events'). | |
| Errors: | SESSION_NOT_REGISTERED | This session is not registered to receive events. You must call event.register before event.next. The session handle you are using is echoed. |
| EVENTS_LOST | Some events have been lost from the queue and cannot be retrieved. | |
| Published in: | XenServer 6.0 (boston) | Blocking call which returns a new token and a (possibly empty) batch of events. The returned token can be used in subsequent calls to this function. |
int
get_current_id
(session ref)
Return the ID of the next event to be generated by the system
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | the event ID | |
| Published in: | XenServer 4.0 (rio) | Return the ID of the next event to be generated by the system |
string
inject
(session ref, string, string)
Injects an artificial event on the given object and returns the corresponding ID in the form of a token, which can be used as a point of reference for database events. For example, to check whether an object has reached the right state before attempting an operation, one can inject an artificial event on the object and wait until the token returned by consecutive event.from calls is lexicographically greater than the one returned by event.inject.
| Parameters: | session ref session_id | Reference to a valid session |
| string class | class of the object | |
| string ref | A reference to the object that will be changed. | |
| Minimum role: | read-only | |
| Result: | the event ID in the form of a token | |
| Published in: | XenServer 6.1 (tampa) | Injects an artificial event on the given object and returns the corresponding ID in the form of a token, which can be used as a point of reference for database events. For example, to check whether an object has reached the right state before attempting an operation, one can inject an artificial event on the object and wait until the token returned by consecutive event.from calls is lexicographically greater than the one returned by event.inject. |
Deprecated
event record set
next
(session ref)
Blocking call which returns a (possibly empty) batch of events. This method is only recommended for legacy use. New development should use event.from which supercedes this method.
| Parameters: | session ref session_id | Reference to a valid session |
| Minimum role: | read-only | |
| Result: | A set of events | |
| Errors: | SESSION_NOT_REGISTERED | This session is not registered to receive events. You must call event.register before event.next. The session handle you are using is echoed. |
| EVENTS_LOST | Some events have been lost from the queue and cannot be retrieved. | |
| Published in: | XenServer 4.0 (rio) | Blocking call which returns a (possibly empty) batch of events. This method is only recommended for legacy use. New development should use event.from which supercedes this method. |
| Deprecated in: | XenServer 6.0 (boston) | |
Deprecated
void
register
(session ref, string set)
Registers this session with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
| Parameters: | session ref session_id | Reference to a valid session |
| string set classes | the classes for which the session will register with the event system; specifying * as the desired class will register for all classes | |
| Minimum role: | read-only | |
| Published in: | XenServer 4.0 (rio) | Registers this session with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next. |
| Deprecated in: | XenServer 6.0 (boston) | |
Deprecated
void
unregister
(session ref, string set)
Removes this session's registration with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next.
| Parameters: | session ref session_id | Reference to a valid session |
| string set classes | the classes for which the session's registration with the event system will be removed | |
| Minimum role: | read-only | |
| Published in: | XenServer 4.0 (rio) | Removes this session's registration with the event system for a set of given classes. This method is only recommended for legacy use in conjunction with event.next. |
| Deprecated in: | XenServer 6.0 (boston) | |