![]() |
![]() |
![]() |
GConf Reference Manual | ![]() |
---|---|---|---|---|
enum GConfError; GError* gconf_error_new (GConfError en, const gchar *format, ...); GQuark gconf_error_quark (void); void gconf_set_error (GError **err, GConfError en, const gchar *format, ...); GError* gconf_compose_errors (GError *err1, GError *err2);
The GError object is used to report errors that occur in GConf library routines. All functions that report errors work the same way:
The last argument to the function is a GError**, a pointer to a location where a GError* can be placed.
This last argument may be NULL, in which case no error will be returned.
If non-NULL, the argument should be the address of a GError* variable, which should be initialized to NULL.
If an error occurs, a GError will be allocated and placed in the
return location; the caller must free the GError with
g_error_free()
. If no error occurs, the return location will be
left untouched. That is, the test error != NULL
should always be a reliable indicator of whether the operation failed.
It's also common that the return value of a function indicates whether or not an error occurred. Typically, TRUE is returned on success. In some cases, a NULL return value indicates failure. Either way, if the return value indicates failure and you passed a non-NULL value for the last argument to the function, a GError will be returned. If the return value indicates success, then a GError will never be returned. These relationships are guaranteed; that is, you can reliably use the return value to decide whether a GError was placed in the return location. If a function does not indicate success/failure by return value, you must check whether the GError is NULL to detect errors.
Here's a short error handling example:
GError* err = NULL; if (!gconf_init(&err)) { fprintf(stderr, _("Failed to init GConf: %s\n"), err->message); g_error_free(err); err = NULL; }
typedef enum { GCONF_ERROR_SUCCESS = 0, GCONF_ERROR_FAILED = 1, /* Something didn't work, don't know why, probably unrecoverable so there's no point having a more specific errno */ GCONF_ERROR_NO_SERVER = 2, /* Server can't be launched/contacted */ GCONF_ERROR_NO_PERMISSION = 3, /* don't have permission for that */ GCONF_ERROR_BAD_ADDRESS = 4, /* Address couldn't be resolved */ GCONF_ERROR_BAD_KEY = 5, /* directory or key isn't valid (contains bad characters, or malformed slash arrangement) */ GCONF_ERROR_PARSE_ERROR = 6, /* Syntax error when parsing */ GCONF_ERROR_CORRUPT = 7, /* Fatal error parsing/loading information inside the backend */ GCONF_ERROR_TYPE_MISMATCH = 8, /* Type requested doesn't match type found */ GCONF_ERROR_IS_DIR = 9, /* Requested key operation on a dir */ GCONF_ERROR_IS_KEY = 10, /* Requested dir operation on a key */ GCONF_ERROR_OVERRIDDEN = 11, /* Read-only source at front of path has set the value */ GCONF_ERROR_OAF_ERROR = 12, /* liboaf error */ GCONF_ERROR_LOCAL_ENGINE = 13, /* Tried to use remote operations on a local engine */ GCONF_ERROR_LOCK_FAILED = 14, /* Failed to get a lockfile */ GCONF_ERROR_NO_WRITABLE_DATABASE = 15, /* nowhere to write a value */ GCONF_ERROR_IN_SHUTDOWN = 16 /* server is shutting down */ } GConfError;
The GConfError enumeration allows client applications to differentiate between different kinds of error. You may wish to take specific actions depending on the error type.
GCONF_ERROR_SUCCESS
|
indicates that no error occurred, won't be returned in a GError. |
GCONF_ERROR_FAILED
|
indicates failure, but no more specific GConfError applied. |
GCONF_ERROR_NO_SERVER
|
indicates that the GConf server couldn't be contacted, probably a CORBA problem. |
GCONF_ERROR_NO_PERMISSION
|
indicates that permission to access some resource was denied. |
GCONF_ERROR_BAD_ADDRESS
|
indicates that a configuration source address was syntactically invalid or impossible to resolve. |
GCONF_ERROR_BAD_KEY
|
indicates that a key was malformed. |
GCONF_ERROR_PARSE_ERROR
|
indicates that some parsing was done (perhaps in a backend) and it failed. |
GCONF_ERROR_CORRUPT
|
indicates that some part of the database is corrupt. |
GCONF_ERROR_TYPE_MISMATCH
|
indicates that a specific type was required, and another type was found. |
GCONF_ERROR_IS_DIR
|
indicates that an operation only applicable to keys was performed on a directory. |
GCONF_ERROR_IS_KEY
|
indicates that an operation only applicable to directories was performed on a key. |
GCONF_ERROR_OVERRIDDEN
|
indicates that the administrator has imposed a mandatory value, and it could not be changed. |
GCONF_ERROR_OAF_ERROR
|
|
GCONF_ERROR_LOCAL_ENGINE
|
|
GCONF_ERROR_LOCK_FAILED
|
|
GCONF_ERROR_NO_WRITABLE_DATABASE
|
|
GCONF_ERROR_IN_SHUTDOWN
|
GError* gconf_error_new (GConfError en, const gchar *format, ...);
Creates a new error. Normally the GConf library does this, but you
might find a reason to do it as well. en
is the error number, format
is a printf()
-style format for the error message, and the variable
argument list is the same as in printf()
.
en : |
the error number. |
format : |
printf() -style format for error description.
|
... : |
arguments required by the format .
|
Returns : | newly-allocated GError. |
GQuark gconf_error_quark (void);
Converts the string 'gconf-error-quark' to a GQuark and returns the value.
Returns : | the GQuark representing the string. |
void gconf_set_error (GError **err, GConfError en, const gchar *format, ...);
Internal function.
err : |
|
en : |
|
format : |
|
... : |