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