## gwymodule-file

gwymodule-file — File loading and saving modules

## Synopsis

    #include <libgwymodule/gwymodule.h>

    #define             GWY_FILE_DETECT_BUFFER_SIZE
    #define             GWY_MODULE_FILE_ERROR
    enum                GwyModuleFileError;
                        GwyFileDetectInfo;
    gint                (*GwyFileDetectFunc)                (const GwyFileDetectInfo *fileinfo,
                                                             gboolean only_name,
                                                             const gchar *name);
    GwyContainer*       (*GwyFileLoadFunc)                  (const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error,
                                                             const gchar *name);
    gboolean            (*GwyFileSaveFunc)                  (GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error,
                                                             const gchar *name);
    gboolean            gwy_file_func_register              (const gchar *name,
                                                             const gchar *description,
                                                             GwyFileDetectFunc detect,
                                                             GwyFileLoadFunc load,
                                                             GwyFileSaveFunc save,
                                                             GwyFileSaveFunc export_);
    gint                gwy_file_func_run_detect            (const gchar *name,
                                                             const gchar *filename,
                                                             gboolean only_name);
    GwyContainer*       gwy_file_func_run_load              (const gchar *name,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);
    gboolean            gwy_file_func_run_save              (const gchar *name,
                                                             GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);
    gboolean            gwy_file_func_run_export            (const gchar *name,
                                                             GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);
    gboolean            gwy_file_func_exists                (const gchar *name);
    GwyFileOperationType gwy_file_func_get_operations       (const gchar *name);
    const gchar*        gwy_file_func_get_description       (const gchar *name);
    void                gwy_file_func_foreach               (GFunc function,
                                                             gpointer user_data);
    const gchar*        gwy_file_detect                     (const gchar *filename,
                                                             gboolean only_name,
                                                             GwyFileOperationType operations);
    const gchar*        gwy_file_detect_with_score          (const gchar *filename,
                                                             gboolean only_name,
                                                             GwyFileOperationType operations,
                                                             gint *score);
    GwyContainer*       gwy_file_load                       (const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);
    GwyFileOperationType gwy_file_save                      (GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);
    gboolean            gwy_file_get_data_info              (GwyContainer *data,
                                                             const gchar **name,
                                                             const gchar **filename_sys);
    GQuark              gwy_module_file_error_quark         (void);

## Description

File modules implement file loading, saving and file type detection functions. Not all fuctions has to be implemented, a file module can be import-only or export-only. If it does not implement file type detection, files of this type can be read/written only on user's explicite request.

For file module writers, the only useful function here is the registration function `gwy_file_func_register()` and the signatures of particular file operations: GwyFileDetectFunc, GwyFileLoadFunc, and GwyFileSaveFunc.

## Details

### GWY_FILE_DETECT_BUFFER_SIZE

    #define GWY_FILE_DETECT_BUFFER_SIZE 4096U

The size of GwyFileDetectInfo buffer for initial part of file. It should be enough for any normal kind of magic header test.

### GWY_MODULE_FILE_ERROR

    #define GWY_MODULE_FILE_ERROR gwy_module_file_error_quark()

Error domain for file module operations. Errors in this domain will be from the GwyModuleFileError enumeration. See GError for information on error domains.

### enum GwyModuleFileError

    typedef enum {
        GWY_MODULE_FILE_ERROR_CANCELLED,
        GWY_MODULE_FILE_ERROR_UNIMPLEMENTED,
        GWY_MODULE_FILE_ERROR_IO,
        GWY_MODULE_FILE_ERROR_DATA,
        GWY_MODULE_FILE_ERROR_INTERACTIVE,
        GWY_MODULE_FILE_ERROR_SPECIFIC
    } GwyModuleFileError;

Error codes returned by file module operations.

File module functions can return any of these codes, except `GWY_MODULE_FILE_ERROR_UNIMPLEMENTED` which is normally only returned by high-level functions `gwy_file_load()` and `gwy_file_save()`. Module functions can return it only when they are called with a wrong function name.

`GWY_MODULE_FILE_ERROR_CANCELLED` | Interactive operation was cancelled by user.
`GWY_MODULE_FILE_ERROR_UNIMPLEMENTED` | No module implements requested operation.
`GWY_MODULE_FILE_ERROR_IO` | Input/output error occured.
`GWY_MODULE_FILE_ERROR_DATA` | Data is corrupted or in an unsupported format.
`GWY_MODULE_FILE_ERROR_INTERACTIVE` | Operation requires user input, but it was run as GWY_RUN_NONINTERACTIVE.
`GWY_MODULE_FILE_ERROR_SPECIFIC` | Special module errors that do not fall into any other category. Should be rarely used.

### GwyFileDetectInfo

    typedef struct {
        const gchar *name;
        const gchar *name_lowercase;
        gsize file_size;
        guint buffer_len;
        const guchar *head;
        const guchar *tail;
    } GwyFileDetectInfo;

File detection data for GwyFileDetectFunc.

It contains the common information file type detection routines need to obtain. It is shared between file detection functions and they must not modify its contents. Some fields are set only when the detection routines are to check the file contents, these are marked `Undefined if `only_name`'.

The `head` and `tail` buffers are always nul-terminated and thus safely usable with string functions. When file is shorter than `GWY_FILE_DETECT_BUFFER_SIZE` bytes, `'\0'` is appended to the end (therefore `buffer_len` = `file_size` + 1), otherwise the last byte is overwritten with `'\0'`. In either case the last byte of `head` and `tail` cannot be assumed to be identical as in the file (or being a part of the file at all).

const gchar *`name`; | File name, in GLib filename encoding.
const gchar *`name_lowercase`; | File name in lowercase (for eventual case-insensitive name check).
gsize `file_size`; | File size in bytes. Undefined if `only_name`.
guint `buffer_len`; | The size of `head` and `tail` in bytes. Normally it's `GWY_FILE_DETECT_BUFFER_SIZE` except when file is shorter than that. Undefined if `only_name`.
const guchar *`head`; | Initial part of file. Undefined if `only_name`.
const guchar *`tail`; | Final part of file. Undefined if `only_name`.

### GwyFileDetectFunc ()

    gint                (*GwyFileDetectFunc)                (const GwyFileDetectInfo *fileinfo,
                                                             gboolean only_name,
                                                             const gchar *name);

The type of file type detection function.

When called with `TRUE` `only_name` it should not try to access the file.

`fileinfo` : | Information about file to detect the filetype of, see GwyFileDetectInfo.
`only_name` : | Whether the type should be guessed only from file name.
`name` : | Function name from as registered with `gwy_file_func_register()` (single-function modules can safely ignore this argument).
Returns : | An integer likehood score (see `gwy_file_func_run_detect()` for description).

### GwyFileLoadFunc ()

    GwyContainer*       (*GwyFileLoadFunc)                  (const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error,
                                                             const gchar *name);

The type of file loading function.

`filename` : | A file name to load data from.
`mode` : | Run mode, this is either `GWY_RUN_NONINTERACTIVE` or `GWY_RUN_INTERACTIVE`.
`error` : | Return location for a GError (or `NULL`).
`name` : | Function name from as registered with `gwy_file_func_register()` (single-function modules can safely ignore this argument).
Returns : | A newly created data container, or `NULL` on failure.

### GwyFileSaveFunc ()

    gboolean            (*GwyFileSaveFunc)                  (GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error,
                                                             const gchar *name);

The type of file saving function.

`data` : | A GwyContainer to save.
`filename` : | A file name to save `data` as.
`mode` : | Run mode, this is either `GWY_RUN_NONINTERACTIVE` or `GWY_RUN_INTERACTIVE`.
`error` : | Return location for a GError (or `NULL`).
`name` : | Function name from as registered with `gwy_file_func_register()` (single-function modules can safely ignore this argument).
Returns : | `TRUE` if file save succeeded, `FALSE` otherwise.

### gwy_file_func_register ()

    gboolean            gwy_file_func_register              (const gchar *name,
                                                             const gchar *description,
                                                             GwyFileDetectFunc detect,
                                                             GwyFileLoadFunc load,
                                                             GwyFileSaveFunc save,
                                                             GwyFileSaveFunc export_);

Registered a file function.

At least one of `load`, `save`, and `export_` must be non-`NULL`. See GwyFileOperationType for differences between save and export.

Note: the string arguments are not copied as modules are not expected to vanish. If they are constructed (non-constant) strings, do not free them. Should modules ever become unloadable they will get chance to clean-up.

`name` : | Name of function to register. It should be a valid identifier and if a module registers only one function, module and function names should be the same.
`description` : | File type description (will be used in file type selectors).
`detect` : | Detection function. It may be `NULL`, files of such a type can can be then loaded and saved only on explict user request.
`load` : | File load/import function.
`save` : | File save function.
`export_` : | File export function.
Returns : | Normally `TRUE`; `FALSE` on failure.

### gwy_file_func_run_detect ()

    gint                gwy_file_func_run_detect            (const gchar *name,
                                                             const gchar *filename,
                                                             gboolean only_name);

Runs a file type detection function identified by `name`.

Value of `only_name` should be `TRUE` if the file doesn't exist (is to be written) so its contents can't be used for file type detection.

This is a low-level function, consider using `gwy_file_detect()` if you simply want to detect a file type.

`name` : | A file type function name.
`filename` : | A file name to detect.
`only_name` : | Whether to use only file name for a guess, or try to actually access the file.
Returns : | An integer score expressing the likehood of the file being loadable as this type. A basic scale is 20 for a good extension, 100 for good magic header, more for more thorough tests.

### gwy_file_func_run_load ()

    GwyContainer*       gwy_file_func_run_load              (const gchar *name,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);

Runs a file load function identified by `name`.

This is a low-level function, consider using `gwy_file_load()` if you simply want to load a file.

`name` : | A file load function name.
`filename` : | A file name to load data from.
`mode` : | Run mode.
`error` : | Return location for a GError (or `NULL`).
Returns : | A new GwyContainer with data from `filename`, or `NULL`.

### gwy_file_func_run_save ()

    gboolean            gwy_file_func_run_save              (const gchar *name,
                                                             GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);

Runs a file save function identified by `name`.

It guarantees the container lifetime spans through the actual file saving, so the module function doesn't have to care about it.

This is a low-level function, consider using `gwy_file_save()` if you simply want to save a file.

`name` : | A file save function name.
`data` : | A GwyContainer to save.
`filename` : | A file name to save `data` as.
`mode` : | Run mode.
`error` : | Return location for a GError (or `NULL`).
Returns : | `TRUE` if file save succeeded, `FALSE` otherwise.

### gwy_file_func_run_export ()

    gboolean            gwy_file_func_run_export            (const gchar *name,
                                                             GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);

Runs a file export function identified by `name`.

It guarantees the container lifetime spans through the actual file saving, so the module function doesn't have to care about it.

This is a low-level function, consider using `gwy_file_save()` if you simply want to save a file.

`name` : | A file save function name.
`data` : | A GwyContainer to save.
`filename` : | A file name to save `data` as.
`mode` : | Run mode.
`error` : | Return location for a GError (or `NULL`).
Returns : | `TRUE` if file save succeeded, `FALSE` otherwise.

### gwy_file_func_exists ()

    gboolean            gwy_file_func_exists                (const gchar *name);

Checks whether a file type function exists.

`name` : | File type function name.
Returns : | `TRUE` if function `name` exists, `FALSE` otherwise.

### gwy_file_func_get_operations ()

    GwyFileOperationType gwy_file_func_get_operations       (const gchar *name);

Returns operations supported by a file type function.

`name` : | File type function name.
Returns : | The file operation bit mask, zero if `name` does not exist.

### gwy_file_func_get_description ()

    const gchar*        gwy_file_func_get_description       (const gchar *name);

Gets file function description.

That is, the `file_desc` field of GwyFileFuncInfo.

`name` : | File type function name.
Returns : | File function description, as a string owned by module loader.

### gwy_file_func_foreach ()

    void                gwy_file_func_foreach               (GFunc function,
                                                             gpointer user_data);

Calls a function for each file function.

`function` : | Function to run for each file function. It will get function name (constant string owned by module system) as its first argument, `user_data` as the second argument.
`user_data` : | Data to pass to `function`.

### gwy_file_detect ()

    const gchar*        gwy_file_detect                     (const gchar *filename,
                                                             gboolean only_name,
                                                             GwyFileOperationType operations);

Detects the type of a file.

`filename` : | A file name to detect type of.
`only_name` : | Whether to use only file name for a guess, or try to actually access the file.
`operations` : | The file operations the file type must support (it must support all of them to be considered).
Returns : | The type name (i.e., the same name as passed to e.g. `gwy_run_file_load_func()`) of most probable type of `filename`, or `NULL` if there's no probable one.

### gwy_file_detect_with_score ()

    const gchar*        gwy_file_detect_with_score          (const gchar *filename,
                                                             gboolean only_name,
                                                             GwyFileOperationType operations,
                                                             gint *score);

Detects the type of a file and gives the score.

`filename` : | A file name to detect type of.
`only_name` : | Whether to use only file name for a guess, or try to actually
`operations` : | The file operations the file type must support (it must
`score` : | Location to store the maximum score (corresponding to the returned type) to.
Returns : | The type name (i.e., the same name as passed to e.g. `gwy_run_file_load_func()`) of most probable type of `filename`, or `NULL` if there's no probable one.

Since 2.1

### gwy_file_load ()

    GwyContainer*       gwy_file_load                       (const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);

Loads a data file, autodetecting its type.

`filename` : | A file name to load data from, in GLib encoding.
`mode` : | Run mode.
`error` : | Return location for a GError (or `NULL`).
Returns : | A new GwyContainer with data from `filename`, or `NULL`.

### gwy_file_save ()

    GwyFileOperationType gwy_file_save                      (GwyContainer *data,
                                                             const gchar *filename,
                                                             GwyRunType mode,
                                                             GError **error);

Saves a data file, deciding to save as what type from the file name.

It tries to find a module implementing `GWY_FILE_OPERATION_SAVE` first, when it does not succeed, it falls back to `GWY_FILE_OPERATION_EXPORT`.

`data` : | A GwyContainer to save.
`filename` : | A file name to save the data as, in GLib encoding.
`mode` : | Run mode.
`error` : | Return location for a GError (or `NULL`).
Returns : | The save operation that was actually realized on success, zero on failure.

### gwy_file_get_data_info ()

    gboolean            gwy_file_get_data_info              (GwyContainer *data,
                                                             const gchar **name,
                                                             const gchar **filename_sys);

Gets file information about a data.

The information is set on two ocasions: file load and successful file save. File export does not set it.

`data` : | A GwyContainer.
`name` : | Location to store file type (that is file function name) of `data`, or `NULL`. The returned string is owned by module system.
`filename_sys` : | Location to store file name of `data` (in GLib encoding), or `NULL`. The returned string is owned by module system and is valid only until the container is destroyed or saved again.
Returns : | `TRUE` if information about `data` was found and `name` and/or `filename` was filled.

### gwy_module_file_error_quark ()

    GQuark              gwy_module_file_error_quark         (void);

Returns error domain for file module functions.

See and use `GWY_MODULE_FILE_ERROR`.

Returns : | The error domain.