9:24 a.m.
It's not too clear from the patch, so I have also extracted the new
API from <guestfs.h> and the relevant section of the man page.
Rich.
----------------------------------------------------------------------
/* Events. */
#define GUESTFS_EVENT_CLOSE 0x0001
#define GUESTFS_EVENT_SUBPROCESS_QUIT 0x0002
#define GUESTFS_EVENT_LAUNCH_DONE 0x0004
#define GUESTFS_EVENT_PROGRESS 0x0008
#define GUESTFS_EVENT_APPLIANCE 0x0010
#define GUESTFS_EVENT_LIBRARY 0x0020
#define GUESTFS_EVENT_TRACE 0x0040
#define GUESTFS_EVENT_ALL UINT64_MAX
#ifndef GUESTFS_TYPEDEF_EVENT_CALLBACK
#define GUESTFS_TYPEDEF_EVENT_CALLBACK 1
typedef void (*guestfs_event_callback) (
guestfs_h *g,
void *opaque,
uint64_t event,
int event_handle,
int flags,
const char *buf, size_t buf_len,
const uint64_t *array, size_t array_len);
#endif
#define LIBGUESTFS_HAVE_SET_EVENT_CALLBACK 1
int guestfs_set_event_callback (guestfs_h *g,
guestfs_event_callback cb,
uint64_t event_bitmask,
int flags,
void *opaque);
#define LIBGUESTFS_HAVE_DELETE_EVENT_CALLBACK 1
void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
----------------------------------------------------------------------
SETTING CALLBACKS TO HANDLE EVENTS
Note: This section documents the new-style event mechanism, which you
should use in new code if possible. The old functions
"guestfs_set_log_message_callback",
"guestfs_set_subprocess_quit_callback",
"guestfs_set_launch_done_callback",
"guestfs_set_close_callback" and
"guestfs_set_progress_callback" are no longer documented in this manual
page.
Handles generate events when certain things happen, such as log
messages being generated, progress messages during long-running
operations, or the handle being closed. The API calls described below
let you register a callback to be called when events happen. You can
register multiple callbacks (for the same, different or overlapping
sets of events), and individually remove callbacks. If callbacks are
not removed, then they remain in force until the handle is closed.
In the current implementation, events are only generated synchronously:
that means that events (and hence callbacks) can only happen while you
are in the middle of making another libguestfs call. The callback is
called in the same thread.
Events may contain a payload, usually nothing (void), an array of 64
bit unsigned integers, or a message buffer. Payloads are discussed
later on.
CLASSES OF EVENTS
GUESTFS_EVENT_CLOSE (payload type: void)
The callback function will be called while the handle is being
closed (synchronously from "guestfs_close").
Note that libguestfs installs an atexit(3) handler to try to clean
up handles that are open when the program exits. This means that
this callback might be called indirectly from exit(3), which can
cause unexpected problems in higher-level languages (eg. if your
HLL interpreter has already been cleaned up by the time this is
called, and if your callback then jumps into some HLL function).
If no callback is registered: the handle is closed without any
callback being invoked.
GUESTFS_EVENT_SUBPROCESS_QUIT (payload type: void)
The callback function will be called when the child process quits,
either asynchronously or if killed by "guestfs_kill_subprocess".
(This corresponds to a transition from any state to the CONFIG
state).
If no callback is registered: the event is ignored.
GUESTFS_EVENT_LAUNCH_DONE (payload type: void)
The callback function will be called when the child process becomes
ready first time after it has been launched. (This corresponds to
a transition from LAUNCHING to the READY state).
If no callback is registered: the event is ignored.
GUESTFS_EVENT_PROGRESS (payload type: array of 4 x uint64_t)
Some long-running operations can generate progress messages. If
this callback is registered, then it will be called each time a
progress message is generated (usually two seconds after the
operation started, and three times per second thereafter until it
completes, although the frequency may change in future versions).
The callback receives in the payload four unsigned 64 bit numbers
which are (in order): "proc_nr", "serial",
"position", "total".
The units of "total" are not defined, although for some operations
"total" may relate in some way to the amount of data to be
transferred (eg. in bytes or megabytes), and "position" may be the
portion which has been transferred.
The only defined and stable parts of the API are:
· The callback can display to the user some type of progress bar
or indicator which shows the ratio of
"position":"total".
· 0 <= "position" <= "total"
· If any progress notification is sent during a call, then a
final progress notification is always sent when "position" =
"total".
This is to simplify caller code, so callers can easily set the
progress indicator to "100%" at the end of the operation,
without requiring special code to detect this case.
The callback also receives the procedure number ("proc_nr") and
serial number ("serial") of the call. These are only useful for
debugging protocol issues, and the callback can normally ignore
them. The callback may want to print these numbers in error
messages or debugging messages.
If no callback is registered: progress messages are discarded.
GUESTFS_EVENT_APPLIANCE (payload type: message buffer)
The callback function is called whenever a log message is generated
by qemu, the appliance kernel, guestfsd (daemon), or utility
programs.
If the verbose flag ("guestfs_set_verbose") is set before launch
("guestfs_launch") then additional debug messages are generated.
If no callback is registered: the messages are discarded unless the
verbose flag is set in which case they are sent to stderr. You can
override the printing of verbose messages to stderr by setting up a
callback.
GUESTFS_EVENT_LIBRARY (payload type: message buffer)
The callback function is called whenever a log message is generated
by the library part of libguestfs.
If the verbose flag ("guestfs_set_verbose") is set then additional
debug messages are generated.
If no callback is registered: the messages are discarded unless the
verbose flag is set in which case they are sent to stderr. You can
override the printing of verbose messages to stderr by setting up a
callback.
GUESTFS_EVENT_TRACE (payload type: message buffer)
The callback function is called whenever a trace message is
generated. This only applies if the trace flag
("guestfs_set_trace") is set.
If no callback is registered: the messages are discarded unless the
verbose flag is set in which case they are sent to stderr. You can
override the printing of verbose messages to stderr by setting up a
callback.
guestfs_set_event_callback
int guestfs_set_event_callback (guestfs_h *g,
guestfs_event_callback cb,
uint64_t event_bitmask,
int flags,
void *opaque);
This function registers a callback ("cb") for all event classes in the
"event_bitmask".
For example, to register for all log message events, you could call
this function with the bitmask
"GUESTFS_EVENT_APPLIANCE|GUESTFS_EVENT_LIBRARY". To register a single
callback for all possible classes of events, use "GUESTFS_EVENT_ALL".
"flags" should always be passed as 0.
"opaque" is an opaque pointer which is passed to the callback. You can
use it for any purpose.
The return value is the event handle (an integer) which you can use to
delete the callback (see below).
If there is an error, this function returns "-1", and sets the error in
the handle in the usual way (see "guestfs_last_error" etc.)
Callbacks remain in effect until they are deleted, or until the handle
is closed.
In the case where multiple callbacks are registered for a particular
event class, all of the callbacks are called. The order in which
multiple callbacks are called is not defined.
guestfs_delete_event_callback
void guestfs_delete_event_callback (guestfs_h *g, int event_handle);
Delete a callback that was previously registered. "event_handle"
should be the integer that was returned by a previous call to
"guestfs_set_event_callback" on the same handle.
guestfs_event_callback
typedef void (*guestfs_event_callback) (
guestfs_h *g,
void *opaque,
uint64_t event,
int event_handle,
int flags,
const char *buf, size_t buf_len,
const uint64_t *array, size_t array_len);
This is the type of the event callback function that you have to
provide.
The basic parameters are: the handle ("g"), the opaque user pointer
("opaque"), the event class (eg. "GUESTFS_EVENT_PROGRESS"), the
event
handle, and "flags" which in the current API you should ignore.
The remaining parameters contain the event payload (if any). Each
event may contain a payload, which usually relates to the event class,
but for future proofing your code should be written to handle any
payload for any event class.
"buf" and "buf_len" contain a message buffer (if "buf_len
== 0", then
there is no message buffer). Note that this message buffer can contain
arbitrary 8 bit data, including NUL bytes.
"array" and "array_len" is an array of 64 bit unsigned
integers. At
the moment this is only used for progress messages.
--
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming blog: http://rwmj.wordpress.com
Fedora now supports 80 OCaml packages (the OPEN alternative to F#)
http://cocan.org/getting_started_with_ocaml_on_red_hat_and_fedora