From: "Daniel P. Berrange" <berrange@redhat.com> Flesh out the section intros for each of the Libvirt GLib library modules, providing using examples where needed, and adding any missing function docs. --- cfg.mk | 2 +- configure.ac | 1 + docs/libvirt-glib/Libvirt-glib-docs.xml | 7 +-- docs/libvirt-glib/Makefile.am | 2 + docs/libvirt-glib/version.xml.in | 1 + libvirt-glib/libvirt-glib-error.c | 56 +++++++++++++++++++---- libvirt-glib/libvirt-glib-event.c | 65 ++++++++++++++++++++++++++ libvirt-glib/libvirt-glib-main.c | 76 +++++++++++++++++++++++++++++++ 8 files changed, 198 insertions(+), 12 deletions(-) create mode 100644 docs/libvirt-glib/version.xml.in diff --git a/cfg.mk b/cfg.mk index ed46aee..099ffa3 100644 --- a/cfg.mk +++ b/cfg.mk @@ -124,7 +124,7 @@ sc_check_author_list: test $$fail = 0 -exclude_file_name_regexp--sc_bindtextdomain = ^(libvirt-gconfig/tests|examples)/ +exclude_file_name_regexp--sc_bindtextdomain = ^(libvirt-gconfig/tests|examples)/|libvirt-glib/libvirt-glib-event.c|libvirt-glib/libvirt-glib-main.c exclude_file_name_regexp--sc_preprocessor_indentation = ^*/*.[ch] diff --git a/configure.ac b/configure.ac index 31f82c9..4b974d4 100644 --- a/configure.ac +++ b/configure.ac @@ -259,6 +259,7 @@ AC_OUTPUT(Makefile vapi/Makefile docs/Makefile docs/libvirt-glib/Makefile + docs/libvirt-glib/version.xml docs/libvirt-gobject/Makefile docs/libvirt-gconfig/Makefile libvirt-glib-1.0.pc diff --git a/docs/libvirt-glib/Libvirt-glib-docs.xml b/docs/libvirt-glib/Libvirt-glib-docs.xml index 5b6a873..f2f3572 100644 --- a/docs/libvirt-glib/Libvirt-glib-docs.xml +++ b/docs/libvirt-glib/Libvirt-glib-docs.xml @@ -3,21 +3,22 @@ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> + <!ENTITY version SYSTEM "version.xml"> ]> <book id="index"> <bookinfo> - <title>Libvirt-glib Reference Manual</title> + <title>Libvirt GLib Reference Manual</title> </bookinfo> <chapter> - <title>Libvirt-glib</title> + <title>API Reference</title> <xi:include href="xml/libvirt-glib-main.xml"/> <xi:include href="xml/libvirt-glib-error.xml"/> <xi:include href="xml/libvirt-glib-event.xml"/> </chapter> <chapter id="object-tree"> <title>Object Hierarchy</title> - <xi:include href="xml/tree_index.sgml"/> + <xi:include href="xml/tree_index.sgml"/> </chapter> <index id="api-index-full"> <title>API Index</title> diff --git a/docs/libvirt-glib/Makefile.am b/docs/libvirt-glib/Makefile.am index e45f4e2..186f8ff 100644 --- a/docs/libvirt-glib/Makefile.am +++ b/docs/libvirt-glib/Makefile.am @@ -39,3 +39,5 @@ GTKDOC_LIBS = \ $(top_builddir)/libvirt-glib/libvirt-glib-1.0.la include $(top_srcdir)/gtk-doc.make + +EXTRA_DIST += version.xml.in diff --git a/docs/libvirt-glib/version.xml.in b/docs/libvirt-glib/version.xml.in new file mode 100644 index 0000000..d78bda9 --- /dev/null +++ b/docs/libvirt-glib/version.xml.in @@ -0,0 +1 @@ +@VERSION@ diff --git a/libvirt-glib/libvirt-glib-error.c b/libvirt-glib/libvirt-glib-error.c index 4a44216..7356aed 100644 --- a/libvirt-glib/libvirt-glib-error.c +++ b/libvirt-glib/libvirt-glib-error.c @@ -29,11 +29,51 @@ #include "libvirt-glib/libvirt-glib.h" /** - * gvir_error_new: (skip) + * SECTION:libvirt-glib-error + * @short_description: Convert libvirt error reports to GLib error reports + * @title: Error reporting + * @stability: Stable + * @include: libvirt-glib/libvirt-glib.h + * + * The libvirt API uses the <code>virError</code> structure for reporting + * errors back to the application programmer. The libvirt API errors are + * provided in thread-local variables, while the GLib standard practice is + * to return errors via out parameters. This library provides a simple way + * to fill in <code>GError **</code> output parameters with the contents + * of the most recent libvirt error object in the current thread. + * + * The <code>gvir_error_new</code>, <code>gvir_error_new_literal</code> and + * <code>gvir_error_new_valist</code> methods all return a newly created + * <code>GError *</code> object instance, differing only in the way the + * message needs to be provided. For most usage though, it is preferrable + * to use the <code>gvir_set_error</code>, <code>gvir_set_error_literal</code> + * and <code>gvir_set_error_valist</code> methods. These all accept a + * <code>GError **</code> argument and take care to only fill it if it + * points to a non-NULL location. + * + * <example> + * <title>Reporting GLib errors with libvirt APIs</title> + * <programlisting><![CDATA[ + * gboolean myapp_start_guest(const gchar *xml, GError **error) + * { + * if (virDomainCreate(conn, xml, 0) < 0) { + * gvir_set_error_literal(error, "Unable to start virtual machine"); + * return FALSE; + * } + * + * return TRUE; + * } + * ]]></programlisting> + * </example> + * + */ + +/** + * gvir_error_new: * @domain: error domain * @code: error code * @format: printf()-style format for error message - * @Varargs: parameters for message format + * @...: parameters for message format * * Creates a new #GError with the given @domain and @code, * and a message formatted with @format. @@ -61,7 +101,7 @@ GError *gvir_error_new(GQuark domain, } /** - * gvir_error_new_literal: (skip) + * gvir_error_new_literal: * @domain: error domain * @code: error code * @message: error message @@ -99,7 +139,7 @@ GError *gvir_error_new_literal(GQuark domain, } /** - * gvir_error_new_valist: (skip) + * gvir_error_new_valist: * @domain: error domain * @code: error code * @format: printf()-style format for error message @@ -129,12 +169,12 @@ GError *gvir_error_new_valist(GQuark domain, /** - * gvir_set_error: (skip) + * gvir_set_error: * @error: pointer to error location * @domain: error domain * @code: error code * @format: printf()-style format for error message - * @Varargs: parameters for message format + * @...: parameters for message format * * If @error is NULL this does nothing. Otherwise it * creates a new #GError with the given @domain and @code, @@ -164,7 +204,7 @@ void gvir_set_error(GError **error, /** - * gvir_set_error_literal: (skip) + * gvir_set_error_literal: * @error: pointer to error location * @domain: error domain * @code: error code @@ -190,7 +230,7 @@ void gvir_set_error_literal(GError **error, /** - * gvir_set_error_valist: (skip) + * gvir_set_error_valist: * @error: pointer to error location * @domain: error domain * @code: error code diff --git a/libvirt-glib/libvirt-glib-event.c b/libvirt-glib/libvirt-glib-event.c index 6d54b10..94f4de8 100644 --- a/libvirt-glib/libvirt-glib-event.c +++ b/libvirt-glib/libvirt-glib-event.c @@ -31,6 +31,53 @@ #include "libvirt-glib/libvirt-glib.h" +/** + * SECTION:libvirt-glib-event + * @short_description: Integrate libvirt with the GMain event framework + * @title: Event loop + * @stability: Stable + * @include: libvirt-glib/libvirt-glib.h + * + * The libvirt API has the ability to provide applications with asynchronous + * notifications of interesting events. To enable this functionality though, + * applications must provide libvirt with an event loop implementation. The + * libvirt-glib API provides such an implementation, which naturally integrates + * with the GMain event loop framework. + * + * To enable use of the GMain event loop glue, the <code>gvir_event_register()</code> + * should be invoked. Once this is done, it is mandatory to have the default + * GMain event loop run by a thread in the application, usually the primary + * thread, eg by using <code>gtk_main()</code> or <code>g_application_run()</code> + * + * <example> + * <title>Registering for events with a GTK application</title> + * <programlisting><![CDATA[ + * int main(int argc, char **argv) { + * ...setup... + * gvir_event_register(); + * ...more setup... + * gtk_main(); + * return 0; + * } + * ]]></programlisting> + * </example> + * + * <example> + * <title>Registering for events using Appplication</title> + * <programlisting><![CDATA[ + * int main(int argc, char **argv) { + * ...setup... + * GApplication *app = ...create some impl of GApplication... + * gvir_event_register(); + * ...more setup... + * g_application_run(app); + * return 0; + * } + * ]]></programlisting> + * </example> + */ + + #if GLIB_CHECK_VERSION(2, 31, 0) #define g_mutex_new() g_new0(GMutex, 1) #endif @@ -414,6 +461,24 @@ static gpointer event_register_once(gpointer data G_GNUC_UNUSED) return NULL; } + +/** + * gvir_event_register: + * + * Registers a libvirt event loop implementation that is backed + * by the default <code>GMain</code> context. If invoked more + * than once this method will be a no-op. Applications should, + * however, take care not to register any another non-GLib + * event loop with libvirt. + * + * After invoking this method, it is mandatory to run the + * default GMain event loop. Typically this can be satisfied + * by invoking <code>gtk_main</code> or <code>g_application_run</code> + * in the application's main thread. Failure to run the event + * loop will mean no libvirt events get dispatched, and the + * libvirt keepalive timer will kill off libvirt connections + * frequently. + */ void gvir_event_register(void) { static GOnce once = G_ONCE_INIT; diff --git a/libvirt-glib/libvirt-glib-main.c b/libvirt-glib/libvirt-glib-main.c index 0cb2dd5..3389de9 100644 --- a/libvirt-glib/libvirt-glib-main.c +++ b/libvirt-glib/libvirt-glib-main.c @@ -29,6 +29,36 @@ #include "libvirt-glib-main.h" +/** + * SECTION:libvirt-glib-main + * @short_description: Initialize the library + * @title: Library initialization + * @stability: Stable + * @include: libvirt-glib/libvirt-glib.h + * + * The Libvirt GLib library provides glue to integrate core libvirt + * infrastructure with the GLib library. This enables consistent + * error reporting procedures and a common event loop implementation + * for applications. + * + * Before using any functions in the Libvirt GLib library, it must be initialized + * by calling <code>gvir_init</code> or <code>gvir_init_check</code>. + * + * <example> + * <title>Initializing the Libvirt GLib library</title> + * <programlisting><![CDATA[ + * int main(int argc, char **argv) { + * ...setup... + * gvir_init(&argc, &argv); + * ...more setup... + * gtk_main(); + * return 0; + * } + * ]]></programlisting> + * </example> + * + */ + static void gvir_error_func(gpointer opaque G_GNUC_UNUSED, virErrorPtr err) @@ -37,6 +67,33 @@ gvir_error_func(gpointer opaque G_GNUC_UNUSED, } + +/** + * gvir_init: + * @argc: (inout): Address of the argc parameter of your main() function (or 0 + * if argv is NULL). This will be changed if any arguments were handled. + * @argv: (array length=argc) (inout) (allow-none): Address of the + * <parameter>argv</parameter> parameter of main(), or %NULL. Any options + * understood by GTK+ are stripped before return. + * + * Call this function before using any other Libvirt GLib functions in your applications. + * It will initialize everything needed to operate the toolkit and parses some standard + * command line options. + * + * Although you are expected to pass the @argc, @argv parameters from main() to this + * function, it is possible to pass NULL if @argv is not available or commandline + * handling is not required. + * + * @argc and @argv are adjusted accordingly so your own code will never see those + * standard arguments. + * + * This method will also turn on debug logging of the library if the + * <literal>LIBVIRT_GLIB_DEBUG</literal> environment variable is set. + * + * This function will terminate your program if it was unable to initialize + * for some reason. If you want the program to fall back to an alternate + * mode of operation call <code>gvir_init_check</code> instead. + */ void gvir_init(int *argc, char ***argv) { @@ -58,6 +115,25 @@ static void gvir_log_handler(const gchar *log_domain G_GNUC_UNUSED, } +/** + * gvir_init_check: + * @argc: (inout): Address of the argc parameter of your main() function (or 0 + * if argv is NULL). This will be changed if any arguments were handled. + * @argv: (array length=argc) (inout) (allow-none): Address of the + * <parameter>argv</parameter> parameter of main(), or %NULL. Any options + * understood by GTK+ are stripped before return. + * @err: filled with the error information if initialized failed. + * + * This function does the same work as gvir_init() with only a single + * change: It does not terminate the program if the Libvirt GLib library + * can't be initialized. Instead it returns %FALSE on failure. + * + * This way the application can fall back to some other mode of + * operation. + * + * Return value: %TRUE if the library was successfully initialized, + * %FALSE otherwise + */ gboolean gvir_init_check(int *argc G_GNUC_UNUSED, char ***argv G_GNUC_UNUSED, GError **err G_GNUC_UNUSED) -- 1.7.10