diff --git a/qubes/__init__.py b/qubes/__init__.py index cd8be9f9..6b7cd051 100644 --- a/qubes/__init__.py +++ b/qubes/__init__.py @@ -420,6 +420,11 @@ class PropertyHolder(qubes.events.Emitter): :param name: Property name :param oldvalue: Old value of the property + .. event:: clone-properties (subject, event, src, proplist) + + :param src: object, from which we are cloning + :param proplist: list of properties + Members: ''' diff --git a/qubes/app.py b/qubes/app.py index ba23512b..2a8ce023 100644 --- a/qubes/app.py +++ b/qubes/app.py @@ -548,6 +548,16 @@ class Qubes(qubes.PropertyHolder): :param event: Event name (``'domain-add'``) :param vm: Domain object + .. event:: domain-pre-delete (subject, event, vm) + + When domain is deleted. VM still has reference to ``app`` object, + and is contained within VMCollection. You may prevent removal by + raising an exception. + + :param subject: Event emitter + :param event: Event name (``'domain-pre-delete'``) + :param vm: Domain object + .. event:: domain-delete (subject, event, vm) When domain is deleted. VM still has reference to ``app`` object, diff --git a/qubes/vm/mix/net.py b/qubes/vm/mix/net.py index 83f3e7f6..b17bd356 100644 --- a/qubes/vm/mix/net.py +++ b/qubes/vm/mix/net.py @@ -323,7 +323,7 @@ class NetVMMixin(qubes.events.Emitter): self.create_qdb_entries() self.attach_network() - new_netvm.fire_event('net-domain-connect', self) # SEE: 1811 + new_netvm.fire_event('net-domain-connect', self) @qubes.events.handler('net-domain-connect') def on_net_domain_connect(self, event, vm): diff --git a/qubes/vm/qubesvm.py b/qubes/vm/qubesvm.py index 20061bf3..c09c42d7 100644 --- a/qubes/vm/qubesvm.py +++ b/qubes/vm/qubesvm.py @@ -148,7 +148,197 @@ def _setter_positive_int(self, prop, value): class QubesVM(qubes.vm.mix.net.NetVMMixin, qubes.vm.BaseVM): - '''Base functionality of Qubes VM shared between all VMs.''' + '''Base functionality of Qubes VM shared between all VMs. + + The following events are raised on this class or its subclasses: + + .. event:: domain-init (subject, event) + + Fired at the end of class' constructor. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-init'``) + + .. event:: domain-load (subject, event) + + Fired after the qube was loaded from :file:`qubes.xml` + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-loaded'``) + + .. event:: domain-pre-start (subject, event, preparing_dvm, start_guid, mem_required) + + Fired at the beginning of :py:meth:`start` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-pre-start'``) + + *other arguments are as in :py:meth:`start`* + + .. event:: domain-spawn (subject, event, preparing_dvm, start_guid) + + Fired after creating libvirt domain. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-spawn'``) + + *other arguments are as in :py:meth:`start`* + + .. event:: domain-start (subject, event, preparing_dvm, start_guid) + + Fired at the end of :py:meth:`start` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-start'``) + + *other arguments are as in :py:meth:`start`* + + .. event:: domain-pre-shutdown (subject, event, force) + + Fired at the beginning of :py:meth:`shutdown` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-pre-shutdown'``) + :param force: If the shutdown is to be forceful + + .. event:: domain-cmd-pre-run (subject, event, start_guid) + + Fired at the beginning of :py:meth:`run` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-cmd-pre-run'``) + :param start_guid: If the gui daemon can be started + + .. event:: domain-create-on-disk (subject, event) + + Fired at the end of :py:meth:`create_on_disk` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-create-on-disk'``) + + .. event:: domain-remove-from-disk (subject, event) + + Fired at the beginning of :py:meth:`remove_from_disk` method, before + the qube directory is removed. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-remove-from-disk'``) + + .. event:: domain-clone-files (subject, event, src) + + Fired at the end of :py:meth:`clone_disk_files` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-clone-files'``) + :param src: source qube + + .. event:: domain-verify-files (subject, event) + + Fired at the end of :py:meth:`clone_disk_files` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-verify-files'``) + + If you think some files are missing or damaged, raise an exception. + + .. event:: domain-is-fully-usable (subject, event) + + Fired at the end of :py:meth:`clone_disk_files` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-is-fully-usable'``) + + You may ``yield False`` from the handler if you think the qube is + not fully usable. This will cause the domain to be in "transient" + state in the domain lifecycle. + + .. event:: domain-qtb-create (subject, event) + + Fired at the end of :py:meth:`create_qdb_entries` method. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-qtb-create'``) + + This event is a good place to add your custom entries to the qdb. + + .. event:: backup-get-files (subject, event) + + Collects additional file to be included in a backup. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'backup-get-files'``) + + Handlers should yield paths of the files. + + .. event:: domain-restore (subject, event) + + Domain was just restored from backup, although the storage was not + yet verified and the app object was not yet saved. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-restore'``) + + .. event:: domain-feature-set (subject, event, key, value) + + A feature was changed. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-feature-set'``) + :param key: feature name + :param value: new value + + .. event:: domain-feature-delete (subject, event, key) + + A feature was removed. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'domain-feature-set'``) + :param key: feature name + + .. event:: feature-request (subject, event, *, untrusted_features) + + The domain is performing a feature request. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'feature-request'``) + :param untrusted_features: :py:class:`dict` containing the feature \ + request + + The content of the `untrusted_features` variable is, as the name + implies, **UNTRUSTED**. The remind this to programmer, the variable + name has to be exactly as provided. + + It is up to the extensions to decide, what to do with request, + ranging from plainly ignoring the request to verbatim copy into + :py:attr:`features` with only minimal sanitisation. + + .. event:: monitor-layout-change (subject, event, monitor_layout) + + Desktop layout was changed, probably because a display was plugged + in or out. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'monitor-layout-change'``) + :param monitor_layout: The new layout + + .. event:: firewall-changed (subject, event) + + Firewall was changed. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'firewall-changed'``) + + .. event:: net-domain-connect (subject, event, vm) + + Fired after connecting a domiain to this vm. + + :param subject: Event emitter (the qube object) + :param event: Event name (``'net-domain-connect'``) + :param vm: The domain that was just connected. + + On the `vm` object there was probably ``property-set:netvm`` fired + earlier. + ''' # # per-class properties