![]() |
![]() |
Gwyddion Application Library Reference Manual | ![]() |
|
---|---|---|---|---|
Top | Description |
#include <app/gwyapp.h> enum GwyDataError; enum GwyDataValidateFlags; GwyDataValidationFailure; GSList * gwy_data_validate (GwyContainer *data
,GwyDataValidateFlags flags
); const gchar * gwy_data_error_desrcibe (GwyDataError error
); void gwy_data_validation_failure_list_free (GSList *list
);
A GwyContainer can be used to represent all sorts of data. However,
Gwyddion, the application, follows certain conventions in data organization.
Function gwy_data_validate()
checks whether the data actually follows them.
This includes but is not limited to representability of keys in ASCII,
conformance to the key naming convention, types of objects and other items
corresponding to expectation, string values being valid UTF-8 and no stray
secondary data.
typedef enum { GWY_DATA_ERROR_KEY_FORMAT = 1, GWY_DATA_ERROR_KEY_CHARACTERS, GWY_DATA_ERROR_KEY_UNKNOWN, GWY_DATA_ERROR_KEY_ID, GWY_DATA_ERROR_ITEM_TYPE, GWY_DATA_ERROR_NON_UTF8_STRING, GWY_DATA_ERROR_REF_COUNT, GWY_DATA_ERROR_STRAY_SECONDARY_DATA, } GwyDataError;
Type of data validation errors.
Key format is invalid (e.g. does not start
with GWY_CONTAINER_PATHSEP ).
|
|
Key contains unprintable characters or characters not representable in ASCII. | |
Key does not correspond to any data item known to this version of Gwyddion. | |
Key corresponds to a data item with bogus id number. | |
Wrong item type (for instance an integer at key
"/0/data" ).
|
|
String value is not valid UTF-8. | |
Reference count is higher than 1. | |
Secondary data item (e.g. mask, selection or visibility) without a corresponding valid primary data item. |
Since 2.9
typedef enum { GWY_DATA_VALIDATE_UNKNOWN = 1 << 0, GWY_DATA_VALIDATE_REF_COUNT = 1 << 1, GWY_DATA_VALIDATE_ALL = 0x0003, GWY_DATA_VALIDATE_CORRECT = 1 << 16, GWY_DATA_VALIDATE_NO_REPORT = 1 << 17, } GwyDataValidateFlags;
Flags controlling gwy_data_validate()
behaviour.
Note passing GWY_DATA_VALIDATE_NO_REPORT
is allowed only if
GWY_DATA_VALIDATE_CORRECT
is present too.
Report all unknown keys as
GWY_DATA_ERROR_KEY_UNKNOWN errors. Note while
a data item unknown to the current version of
Gwyddion can come from a newer version therefore
it can be in certain sense valid.
|
|
Report all object items with reference count
higher than 1 as GWY_DATA_ERROR_REF_COUNT
errors. Obviously this makes sense only with
`fresh' data containers.
|
|
All above flags combined. | |
Attempt to correct problems. | |
Do not report problems. |
Since 2.9
typedef struct { GwyDataError error; GQuark key; gchar *details; } GwyDataValidationFailure;
Information about one data validate error.
Note the structure may contain more private fields.
GwyDataError |
Error type. |
GQuark |
Key of the problematic data item. |
gchar * |
Error details, may be NULL for some types of error . This is
a dynamically allocated string owned by the caller, however, he
normally frees the complete errors lists with
gwy_data_validation_failure_list_free() which frees these fields
too. |
Since 2.9
GSList * gwy_data_validate (GwyContainer *data
,GwyDataValidateFlags flags
);
Checks the contents of a data file.
If GWY_DATA_VALIDATE_CORRECT
is given in flags
, correctable problems are
corrected. At present correctable problems are those that can be fixed
by removal of the offending data.
|
Data container. It should not be managed by the data browser (yet)
if flags contain GWY_DATA_VALIDATE_CORRECT (because things can
in principle break during the correction) or
GWY_DATA_VALIDATE_REF_COUNT (because the application took some
references). |
|
Validation flags. Some influence what is checked, some determine what to do when problems are found. |
Returns : |
List of errors found, free
with gwy_data_validation_failure_list_free() .
The list is independent on whether GWY_DATA_VALIDATE_CORRECT is
given in flags, even though the offending items may be no longer
exist in the container after correction. If
GWY_DATA_VALIDATE_NO_REPORT is present in flags, NULL is always
returned. |
Since 2.9
const gchar * gwy_data_error_desrcibe (GwyDataError error
);
Describes a data validation error type.
|
Data validation error type. |
Returns : |
Error description as an untranslated string owned by the library. |
Since 2.9
void gwy_data_validation_failure_list_free
(GSList *list
);
Frees a data validation failure list.
|
Failure list returned by gwy_data_validate() . |
Since 2.9