*/
/**
* 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.
*
* 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,
* 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.
**/
* 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.
*
* - 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:
*
* 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