/*
 * call-seq:
 *   Libvirt::event_invoke_handle_callback(handle, fd, events, opaque) -> Qnil
 *
 * Unlike most of the other functions in the ruby-libvirt bindings, this one
 * does not directly correspond to a libvirt API function.  Instead, this
 * module method (and event_invoke_timeout_callback) are meant to be called
 * when there is an event of interest to libvirt on one of the file descriptors
 * that libvirt uses.  The application is notified of the file descriptors
 * that libvirt uses via the callbacks from Libvirt::event_register_impl.  When
 * there is an event of interest, the application must call
 * event_invoke_timeout_callback to ensure proper operation.
 *
 * Libvirt::event_invoke_handle_callback takes 4 arguments:
 *
 * handle
 *          an application specific handle ID.  This can be any integer, but
 *          must be unique from all other libvirt handles in the application.
 * fd
 *          the file descriptor of interest.  This was given to the application
 *          as a callback to add_handle of Libvirt::event_register_impl
 * events
 *          the events that have occured on the fd.  Note that the events are
 *          libvirt specific, and are some combination of
 *          Libvirt::EVENT_HANDLE_READABLE, Libvirt::EVENT_HANDLE_WRITABLE,
 *          Libvirt::EVENT_HANDLE_ERROR, Libvirt::EVENT_HANDLE_HANGUP.  To
 *          notify libvirt of more than one event at a time, these values should
 *          be logically OR'ed together.
 * opaque
 *          the opaque data passed from libvirt during the
 *          Libvirt::event_register_impl add_handle callback.  To ensure proper
 *          operation this data must be passed through to
 *          event_invoke_handle_callback without modification.
 */
static VALUE libvirt_event_invoke_handle_callback(VALUE m, VALUE handle,
                                                  VALUE fd, VALUE events,
                                                  VALUE opaque) {

/*
 * call-seq:
 *   Libvirt::event_invoke_timeout_callback(timer, opaque) -> Qnil
 *
 * Unlike most of the other functions in the ruby-libvirt bindings, this one
 * does not directly correspond to a libvirt API function.  Instead, this
 * module method (and event_invoke_handle_callback) are meant to be called
 * when there is a timeout of interest to libvirt.  The application is
 * notified of the timers that libvirt uses via the callbacks from
 * Libvirt::event_register_impl.  When a timeout expires, the application must
 * call event_invoke_timeout_callback to ensure proper operation.
 *
 * Libvirt::event_invoke_timeout_callback takes 2 arguments:
 *
 * handle
 *          an application specific timer ID.  This can be any integer, but
 *          must be unique from all other libvirt timers in the application.
 * opaque
 *          the opaque data passed from libvirt during the
 *          Libvirt::event_register_impl add_handle callback.  To ensure proper
 *          operation this data must be passed through to
 *          event_invoke_handle_callback without modification.
 */
static VALUE libvirt_event_invoke_timeout_callback(VALUE m, VALUE timer,
                                                   VALUE opaque) {

/*
 * call-seq:
 *   Libvirt::event_register_impl(add_handle=nil, update_handle=nil, remove_handle=nil, add_timeout=nil, update_timeout=nil, remove_timeout=nil) -> Qnil
 *
 * Call
 * +virEventRegisterImpl+[http://www.libvirt.org/html/libvirt-libvirt.html#virEventRegisterImpl]
 * to register callback handlers for handles and timeouts.  These handles and
 * timeouts are used as part of the libvirt infrastructure for generating
 * domain events.  Each callback must be a Symbol (that is the name of a
 * method to callback), a Proc, or nil (to disable the callback).  In the
 * end-user application program, these callbacks are typically used to track
 * the file descriptors or timers that libvirt is interested in (and is intended
 * to be integrated into the "main loop" of a UI program).  The individual
 * callbacks will be given a certain number of arguments, and must return
 * certain values.  Those arguments and return types are:
 *
 * add_handle(fd, events, opaque) => Fixnum
 *
 * update_handle(handleID, event) => nil
 *
 * remove_handle(handleID) => opaque data from add_handle
 *
 * add_timeout(interval, opaque) => Fixnum
 *
 * update_timeout(timerID, timeout) => nil
 *
 * remove_timeout(timerID) => opaque data from add_timeout
 *
 * Any arguments marked as "opaque" must be accepted from the library and saved
 * without modification.  The values passed to the callbacks are meant to be
 * passed to the event_invoke_handle_callback and event_invoke_timeout_callback
 * module methods; see the documentation for those methods for more details.
 */
static VALUE libvirt_conn_event_register_impl(int argc, VALUE *argv, VALUE c) {

/*
 * call-seq:
 *   Libvirt::open(uri=nil) -> Libvirt::Connect
 *
 * Call
 * +virConnectOpen+[http://www.libvirt.org/html/libvirt-libvirt.html#virConnectOpen]
 * to open a connection to a URL.
 */
static VALUE libvirt_open(int argc, VALUE *argv, VALUE m) {

/*
 * call-seq:
 *   Libvirt::open_auth(uri=nil, credlist=nil, userdata=nil, flags=0) {|...| authentication block} -> Libvirt::Connect
 *
 * Call
 * +virConnectOpenAuth+[http://www.libvirt.org/html/libvirt-libvirt.html#virConnectOpenAuth]
 * to open a connection to a libvirt URI, with a possible authentication block.
 * If an authentication block is desired, then credlist should be an array that
 * specifies which credentials the authentication block is willing to support;
 * the full list is available at http://libvirt.org/html/libvirt-libvirt.html#virConnectCredentialType.
 * If userdata is not nil and an authentication block is given, userdata will
 * be passed unaltered into the authentication block.  The flags parameter
 * controls how to open connection.  The only options currently available for
 * flags are 0 for a read/write connection and Libvirt::CONNECT_RO for a
 * read-only connection.
 *
 * If the credlist is not empty, and an authentication block is given, the
 * authentication block will be called once for each credential necessary
 * to complete the authentication.  The authentication block will be passed a
 * single parameter, which is a hash of values containing information necessary
 * to complete authentication.  This hash contains 5 elements:
 *
 * type - the type of credential to be examined
 *
 * prompt - a suggested prompt to show to the user
 *
 * challenge - any additional challenge information
 *
 * defresult - a default result to use if credentials could not be obtained
 *
 * userdata - the userdata passed into open_auth initially
 *
 * The authentication block should return the result of collecting the
 * information; these results will then be sent to libvirt for authentication.
 */
static VALUE libvirt_open_auth(int argc, VALUE *argv, VALUE m) {

/*
 * call-seq:
 *   Libvirt::open_read_only(uri=nil) -> Libvirt::Connect
 *
 * Call
 * +virConnectOpenReadOnly+[http://www.libvirt.org/html/libvirt-libvirt.html#virConnectOpenReadOnly]
 * to open a read-only connection to a URL.
 */
static VALUE libvirt_open_read_only(int argc, VALUE *argv, VALUE m) {

/*
 * call-seq:
 *   Libvirt::version(type=nil) -> [ libvirt_version, type_version ]
 *
 * Call
 * +virGetVersion+[http://www.libvirt.org/html/libvirt-libvirt.html#virGetVersion]
 * to get the version of libvirt and of the hypervisor TYPE.
 */
static VALUE libvirt_version(int argc, VALUE *argv, VALUE m) {