| GError * | gvir_error_new () |
| GError * | gvir_error_new_literal () |
| GError * | gvir_error_new_valist () |
| void | gvir_set_error () |
| void | gvir_set_error_literal () |
| void | gvir_set_error_valist () |
| void | gvir_critical () |
| void | gvir_warning () |
The libvirt API uses the virError 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 GError ** output parameters with the contents
of the most recent libvirt error object in the current thread.
The gvir_error_new, gvir_error_new_literal and
gvir_error_new_valist methods all return a newly created
GError * object instance, differing only in the way the
message needs to be provided. For most usage though, it is preferable
to use the gvir_set_error, gvir_set_error_literal
and gvir_set_error_valist methods. These all accept a
GError ** argument and take care to only fill it if it
points to a non-NULL location.
Example 2. Reporting GLib errors with libvirt APIs
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;
}
GError * gvir_error_new (GQuark domain,gint code,const gchar *format,...);
Creates a new GError with the given domain
and code
,
and a message formatted with format
.
GError * gvir_error_new_literal (GQuark domain,gint code,const gchar *message);
Creates a new GError; unlike gvir_error_new(), message
is
not a printf()-style format string. Use this function if
message
contains text you don't have control over,
that could include printf() escape sequences.
GError * gvir_error_new_valist (GQuark domain,gint code,const gchar *format,va_list args);
Creates a new GError with the given domain
and code
,
and a message formatted with format
.
domain |
error domain |
|
code |
error code |
|
format |
printf()-style format for error message |
|
args |
va_list of parameters for the message format |
void gvir_set_error (GError **error,GQuark domain,gint code,const gchar *format,...);
If error
is NULL this does nothing. Otherwise it
creates a new GError with the given domain
and code
,
and a message formatted with format
, and stores it
in error
.
void gvir_set_error_literal (GError **error,GQuark domain,gint code,const gchar *message);
If error
is NULL this does nothing. Otherwise it
creates a new GError and stores it in error
; unlike
gvir_set_error(), message
is not a printf()-style
format string. Use this function if message
contains
text you don't have control over, that could include
printf() escape sequences.
void gvir_set_error_valist (GError **error,GQuark domain,gint code,const gchar *format,va_list args);
If error
is NULL this does nothing. Otherwise it
creates a new GError with the given domain
and code
,
and a message formatted with format
, and stores it
in error
.
error |
pointer to error location |
|
domain |
error domain |
|
code |
error code |
|
format |
printf()-style format for error message |
|
args |
va_list of parameters for the message format |