luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Clarify expectations with error codes like G_IO_ERROR_FAILED

Browse Source 
If an error code enumeration is expected to be extended in the future,
people shouldn't compare explicitly against its generic "FAILED" value.

https://bugzilla.gnome.org/show_bug.cgi?id=726775
This commit is contained in:
Dan Winship 2014-03-20 09:25:19 -04:00
parent 9c19f6dfa1
commit c67d23aa2f
3 changed files with 35 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
gio/gioenums.h
View File

@ -416,7 +416,8 @@ typedef enum {
*/
/**
* GIOErrorEnum:
* @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
* @G_IO_ERROR_FAILED: Generic error condition for when an operation fails
* and no more specific #GIOErrorEnum value is defined.
* @G_IO_ERROR_NOT_FOUND: File not found.
* @G_IO_ERROR_EXISTS: File already exists.
* @G_IO_ERROR_IS_DIRECTORY: File is a directory.
@ -472,6 +473,19 @@ typedef enum {
*
* Error codes returned by GIO functions.
*
* Note that this domain may be extended in future GLib releases. In
* general, new error codes either only apply to new APIs, or else
* replace #G_IO_ERROR_FAILED in cases that were not explicitly
* distinguished before. You should therefore avoid writing code like
* |[<!-- language="C" -->
* if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED))
* {
* // Assume that this is EPRINTERONFIRE
* ...
* }
* ]|
* but should instead treat all unrecognized error codes the same as
* #G_IO_ERROR_FAILED.
**/
typedef enum {
G_IO_ERROR_FAILED,

12
gio/gioerror.c
View File

@ -44,7 +44,10 @@ G_DEFINE_QUARK (g-io-error-quark, g_io_error)
* g_io_error_from_errno:
* @err_no: Error number as defined in errno.h.
*
* Converts errno.h error codes into GIO error codes.
* Converts errno.h error codes into GIO error codes. The fallback
* value %G_IO_ERROR_FAILED is returned for error codes not currently
* handled (but note that future GLib releases may return a more
* specific value instead).
*
* Returns: #GIOErrorEnum value for the given errno.h error number.
**/
@ -229,9 +232,10 @@ g_io_error_from_errno (gint err_no)
* g_io_error_from_win32_error:
* @error_code: Windows error number.
*
* Converts some common error codes into GIO error codes. The
* fallback value G_IO_ERROR_FAILED is returned for error codes not
* handled.
* Converts some common error codes into GIO error codes. The fallback
* value %G_IO_ERROR_FAILED is returned for error codes not currently
* handled (but note that future GLib releases may return a more
* specific value instead).
*
* Returns: #GIOErrorEnum value for the given error number.
*

13
glib/gerror.c
View File

@ -271,7 +271,11 @@
* - If there's a "generic" or "unknown" error code for unrecoverable
* errors it doesn't make sense to distinguish with specific codes,
* it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
* for example %G_SPAWN_ERROR_FAILED.
* for example %G_SPAWN_ERROR_FAILED. In the case of error code
* enumerations that may be extended in future releases, you should
* generally not handle this error code explicitly, but should
* instead treat any unrecognized error code as equivalent to
* FAILED.
*
* Summary of rules for use of #GError:
*
@ -502,6 +506,13 @@ g_error_copy (const GError *error)
* otherwise. In particular, when @error is %NULL, %FALSE will
* be returned.
*
* If @domain contains a `FAILED` (or otherwise generic) error code,
* you should generally not check for it explicitly, but should
* instead treat any not-explicitly-recognized error code as being
* equilalent to the `FAILED` code. This way, if the domain is
* extended in the future to provide a more specific error code for
* a certain case, your code will still work.
*
* Returns: whether @error has @domain and @code
*/
gboolean