mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-02-01 17:35:17 +00:00
docs: improve event-related documentation
While looking at event code, I noticed that the documentation was trying to refer me to functions that don't exist. Also fix some typos and poor formatting. * src/libvirt.c (virConnectDomainEventDeregister) (virConnectDomainEventRegisterAny) (virConnectDomainEventDeregisterAny) (virConnectNetworkEventRegisterAny) (virConnectNetworkEventDeregisterAny): Link to correct function. * include/libvirt.h.in (VIR_DOMAIN_EVENT_CALLBACK) (VIR_NETWORK_EVENT_CALLBACK): Likewise. (virDomainEventID, virConnectDomainEventGenericCallback) (virNetworkEventID, virConnectNetworkEventGenericCallback): Improve docs. Signed-off-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Eric Blake
parent
3a96cebceb
commit
3e67714e48
@ -4508,14 +4508,17 @@ int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
|
||||
int virDomainSnapshotRef(virDomainSnapshotPtr snapshot);
|
||||
int virDomainSnapshotFree(virDomainSnapshotPtr snapshot);
|
||||
|
||||
/*
|
||||
/**
|
||||
* virConnectDomainEventGenericCallback:
|
||||
* @conn: the connection pointer
|
||||
* @dom: the domain pointer
|
||||
* @opaque: application specified data
|
||||
*
|
||||
* A generic domain event callback handler. Specific events usually
|
||||
* have a customization with extra parameters
|
||||
* A generic domain event callback handler, for use with
|
||||
* virConnectDomainEventRegisterAny(). Specific events usually
|
||||
* have a customization with extra parameters, often with @opaque being
|
||||
* passed in a different parameter position; use VIR_DOMAIN_EVENT_CALLBACK()
|
||||
* when registering an appropriate handler.
|
||||
*/
|
||||
typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn,
|
||||
virDomainPtr dom,
|
||||
@ -4930,11 +4933,18 @@ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
|
||||
* VIR_DOMAIN_EVENT_CALLBACK:
|
||||
*
|
||||
* Used to cast the event specific callback into the generic one
|
||||
* for use for virDomainEventRegister
|
||||
* for use for virConnectDomainEventRegisterAny()
|
||||
*/
|
||||
#define VIR_DOMAIN_EVENT_CALLBACK(cb) ((virConnectDomainEventGenericCallback)(cb))
|
||||
|
||||
|
||||
/**
|
||||
* virDomainEventID:
|
||||
*
|
||||
* An enumeration of supported eventId parameters for
|
||||
* virConnectDomainEventRegisterAny(). Each event id determines which
|
||||
* signature of callback function will be used.
|
||||
*/
|
||||
typedef enum {
|
||||
VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0, /* virConnectDomainEventCallback */
|
||||
VIR_DOMAIN_EVENT_ID_REBOOT = 1, /* virConnectDomainEventGenericCallback */
|
||||
@ -5015,10 +5025,17 @@ typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn,
|
||||
* VIR_NETWORK_EVENT_CALLBACK:
|
||||
*
|
||||
* Used to cast the event specific callback into the generic one
|
||||
* for use for virNetworkEventRegister
|
||||
* for use for virConnectNetworkEventRegisterAny()
|
||||
*/
|
||||
#define VIR_NETWORK_EVENT_CALLBACK(cb) ((virConnectNetworkEventGenericCallback)(cb))
|
||||
|
||||
/**
|
||||
* virNetworkEventID:
|
||||
*
|
||||
* An enumeration of supported eventId parameters for
|
||||
* virConnectNetworkEventRegisterAny(). Each event id determines which
|
||||
* signature of callback function will be used.
|
||||
*/
|
||||
typedef enum {
|
||||
VIR_NETWORK_EVENT_ID_LIFECYCLE = 0, /* virConnectNetworkEventLifecycleCallback */
|
||||
|
||||
@ -5032,14 +5049,17 @@ typedef enum {
|
||||
#endif
|
||||
} virNetworkEventID;
|
||||
|
||||
/*
|
||||
/**
|
||||
* virConnectNetworkEventGenericCallback:
|
||||
* @conn: the connection pointer
|
||||
* @net: the network pointer
|
||||
* @opaque: application specified data
|
||||
*
|
||||
* A generic network event callback handler. Specific events usually
|
||||
* have a customization with extra parameters
|
||||
* A generic network event callback handler, for use with
|
||||
* virConnectNetworkEventRegisterAny(). Specific events usually
|
||||
* have a customization with extra parameters, often with @opaque being
|
||||
* passed in a different parameter position; use VIR_NETWORK_EVENT_CALLBACK()
|
||||
* when registering an appropriate handler.
|
||||
*/
|
||||
typedef void (*virConnectNetworkEventGenericCallback)(virConnectPtr conn,
|
||||
virNetworkPtr net,
|
||||
|
||||
@ -16127,7 +16127,7 @@ error:
|
||||
* occurring on a connection
|
||||
*
|
||||
* Use of this method is no longer recommended. Instead applications
|
||||
* should try virConnectDomainEventRegisterAny which has a more flexible
|
||||
* should try virConnectDomainEventRegisterAny() which has a more flexible
|
||||
* API contract
|
||||
*
|
||||
* The virDomainPtr object handle passed into the callback upon delivery
|
||||
@ -16178,7 +16178,7 @@ error:
|
||||
* function.
|
||||
*
|
||||
* Use of this method is no longer recommended. Instead applications
|
||||
* should try virConnectDomainEventUnregisterAny which has a more flexible
|
||||
* should try virConnectDomainEventDeregisterAny() which has a more flexible
|
||||
* API contract
|
||||
*
|
||||
* Returns 0 on success, -1 on failure
|
||||
@ -19069,7 +19069,7 @@ error:
|
||||
* Adds a callback to receive notifications of arbitrary domain events
|
||||
* occurring on a domain.
|
||||
*
|
||||
* If dom is NULL, then events will be monitored for any domain. If dom
|
||||
* If @dom is NULL, then events will be monitored for any domain. If @dom
|
||||
* is non-NULL, then only the specific domain will be monitored
|
||||
*
|
||||
* Most types of event have a callback providing a custom set of parameters
|
||||
@ -19080,13 +19080,13 @@ error:
|
||||
* The virDomainPtr object handle passed into the callback upon delivery
|
||||
* of an event is only valid for the duration of execution of the callback.
|
||||
* If the callback wishes to keep the domain object after the callback returns,
|
||||
* it shall take a reference to it, by calling virDomainRef.
|
||||
* it shall take a reference to it, by calling virDomainRef().
|
||||
* The reference can be released once the object is no longer required
|
||||
* by calling virDomainFree.
|
||||
* by calling virDomainFree().
|
||||
*
|
||||
* The return value from this method is a positive integer identifier
|
||||
* for the callback. To unregister a callback, this callback ID should
|
||||
* be passed to the virDomainEventUnregisterAny method
|
||||
* be passed to the virConnectDomainEventDeregisterAny() method.
|
||||
*
|
||||
* Returns a callback identifier on success, -1 on failure
|
||||
*/
|
||||
@ -19143,7 +19143,7 @@ error:
|
||||
* @callbackID: the callback identifier
|
||||
*
|
||||
* Removes an event callback. The callbackID parameter should be the
|
||||
* vaule obtained from a previous virDomainEventRegisterAny method.
|
||||
* value obtained from a previous virConnectDomainEventRegisterAny() method.
|
||||
*
|
||||
* Returns 0 on success, -1 on failure
|
||||
*/
|
||||
@ -19188,7 +19188,7 @@ error:
|
||||
* Adds a callback to receive notifications of arbitrary network events
|
||||
* occurring on a network.
|
||||
*
|
||||
* If net is NULL, then events will be monitored for any network. If net
|
||||
* If @net is NULL, then events will be monitored for any network. If @net
|
||||
* is non-NULL, then only the specific network will be monitored
|
||||
*
|
||||
* Most types of event have a callback providing a custom set of parameters
|
||||
@ -19199,13 +19199,13 @@ error:
|
||||
* The virNetworkPtr object handle passed into the callback upon delivery
|
||||
* of an event is only valid for the duration of execution of the callback.
|
||||
* If the callback wishes to keep the network object after the callback
|
||||
* returns, it shall take a reference to it, by calling virNetworkRef.
|
||||
* returns, it shall take a reference to it, by calling virNetworkRef().
|
||||
* The reference can be released once the object is no longer required
|
||||
* by calling virNetworkFree.
|
||||
* by calling virNetworkFree().
|
||||
*
|
||||
* The return value from this method is a positive integer identifier
|
||||
* for the callback. To unregister a callback, this callback ID should
|
||||
* be passed to the virNetworkEventUnregisterAny method
|
||||
* be passed to the virConnectNetworkEventDeregisterAny() method.
|
||||
*
|
||||
* Returns a callback identifier on success, -1 on failure
|
||||
*/
|
||||
@ -19266,7 +19266,7 @@ error:
|
||||
* @callbackID: the callback identifier
|
||||
*
|
||||
* Removes an event callback. The callbackID parameter should be the
|
||||
* vaule obtained from a previous virNetworkEventRegisterAny method.
|
||||
* value obtained from a previous virConnectNetworkEventRegisterAny() method.
|
||||
*
|
||||
* Returns 0 on success, -1 on failure
|
||||
*/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user