File modules: Gwyddion Application Library Reference Manual

## File modules File modules — File loading and saving modules |

## Functions

gint | (*GwyFileDetectFunc) ()
GwyFile * | (*GwyFileLoadFunc) ()
gboolean | (*GwyFileSaveFunc) ()
gboolean | gwy_file_func_register ()
gint | gwy_file_func_run_detect ()
GwyFile * | gwy_file_func_run_load ()
gboolean | gwy_file_func_run_save ()
gboolean | gwy_file_func_run_export ()
gboolean | gwy_file_func_exists ()
GwyFileOperationType | gwy_file_func_get_operations ()
const gchar * | gwy_file_func_get_description ()
void | gwy_file_func_foreach ()
const gchar * | gwy_file_func_current ()
gboolean | gwy_file_func_get_is_detectable ()
void | gwy_file_func_set_is_detectable ()
gboolean | gwy_file_func_get_is_unfinished ()
void | gwy_file_func_set_is_unfinished ()
const gchar * | gwy_file_detect ()
GwyFile * | gwy_file_load ()
GwyFile * | gwy_file_load_with_func ()
GwyFileOperationType | gwy_file_save ()
GwyFileOperationType | gwy_file_save_with_func ()
GQuark | gwy_module_file_error_quark ()

## Types and Values

#define | GWY_FILE_DETECT_BUFFER_SIZE
#define | GWY_MODULE_FILE_ERROR
enum | GwyFileOperationType
enum | GwyModuleFileError
| GwyFileDetectInfo

## Includes

    #include <libgwyapp/gwyapp.h>

## 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.

## Functions

### GwyFileDetectFunc()

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

The type of file type detection function.

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

A basic scale for the returned values is:

- 0 for not recognised
- 20 for very a basic check or a relatively unique file extension
- 60 to 80 in probable but not clear cut cases when the file may be something else or it is a generic format which may have more specific subformats
- 100 is the standard value for a solid check beyond some 4byte magic header; the modue should pretty sure the file is actually of this type.

#### Parameters

fileinfo | Information about file to detect the filetype of, see GwyFileDetectInfo. |
only_name | Whether the type should be guessed only from file name. |

#### Returns

An integer likelyhood score.

### GwyFileLoadFunc()

    GwyFile *
    (*GwyFileLoadFunc) (const gchar *filename,
                        GwyRunModeFlags mode,
                        GError **error);

The type of file loading function.

The function can create the file as being in construction with `gwy_file_new_in_construction()` to avoid signals being emitted during construction. If the returned object is still marked in construction, it will be finished by the module system.

#### Parameters

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`). |

#### Returns

A newly created file data container, or `NULL` on failure.

[transfer full]

### GwyFileSaveFunc()

    gboolean
    (*GwyFileSaveFunc) (GwyFile *file,
                        const gchar *filename,
                        GwyRunModeFlags mode,
                        GError **error);

The type of file saving function.

#### Parameters

file | A GwyFile to save. |
filename | A file name to save `file` as. |
mode | Run mode, this is either `GWY_RUN_NONINTERACTIVE` or `GWY_RUN_INTERACTIVE` . |
error | Return location for a GError (or `NULL`). |

#### 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_file,
                            GwyFileSaveFunc save_file,
                            GwyFileSaveFunc export_file);

Registers a file format and defines which file operations it supports.

At least one of `load_file` , `save_file` , and `export_file` 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.

It is possible to register the same routines such as `load_file` for multiple file types (as distinguished by `name` ). In such case they must use `gwy_file_func_current()` to see under which name they are called. It may be easier to register different routines which then call the same function within the module with some distinguishing argument.

#### Parameters

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 | File load/import function. |
save_file | File save function. |
export_file | 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.

#### Parameters

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 likelyhood of the file being loadable as this type. See GwyFileDetectFunc for more details.

### gwy_file_func_run_load()

    GwyFile *
    gwy_file_func_run_load (const gchar *name,
                            const gchar *filename,
                            GwyRunModeFlags 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.

The returned object is never marked as in construction; it is always already finished.

#### Parameters

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 GwyFile with data from `filename` , or `NULL`.

### gwy_file_func_run_save()

    gboolean
    gwy_file_func_run_save (const gchar *name,
                            GwyFile *file,
                            const gchar *filename,
                            GwyRunModeFlags 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.

#### Parameters

name | A file save function name. |
file | A GwyFile to save. |
filename | A file name to save `file` 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,
                              GwyFile *file,
                              const gchar *filename,
                              GwyRunModeFlags 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.

#### Parameters

name | A file save function name. |
file | A GwyFile to save. |
filename | A file name to save `file` 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.

#### Parameters

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.

#### Parameters

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 `description` argument of `gwy_file_func_register()` .

#### Parameters

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 (GwyNameFunc function,
                           gpointer user_data);

Calls a function for each file function.

#### Parameters

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_func_current()

    const gchar *
    gwy_file_func_current (void);

Obtains the name of currently running file type function.

All file functions are taken into account: detect, load, save and export.

If no file type function is currently running, `NULL` is returned.

If multiple nested file functions are running (which is not usual but technically possible), the innermost function name is returned. If nested function of different types are running (which is not usual but technically possible) the other types do not affect the returned value; only file functions are taken into account.

#### Returns

The name of the currently running file type function or `NULL`.

### gwy_file_func_get_is_detectable()

    gboolean
    gwy_file_func_get_is_detectable (const gchar *name);

Reports if the file format is reasonably detectable.

This is `TRUE` for all file types that define a detection method unless they explicitly call `gwy_file_func_set_is_detectable()` to set the file format non-detectable in spite of providing a detection method.

If files that can be actually loaded as a given type form a subset of files that are detected as this format, which is normaly the case, it makes no sense to let the user explicitly choose between these formats. Hence, detectable formats normally are not explicitly offered.

#### Parameters

name | File type function name. |

#### Returns

If the file format is detectable.

### gwy_file_func_set_is_detectable()

    void
    gwy_file_func_set_is_detectable (const gchar *name,
                                     gboolean is_detectable);

Sets the detectability status of a file format.

See `gwy_file_func_get_is_detectable()` for details. The only rare case when it makes sense to call this function is when a detection function is provided for some reason, however, this function is not really able to detect the format. For instance, the fallback detection method of the Gwyddion rawfile module.

#### Parameters

name | File type function name. |
is_detectable | `TRUE` to define format as detectable, `FALSE` as non-detectable. |

### gwy_file_func_get_is_unfinished()

    gboolean
    gwy_file_func_get_is_unfinished (const gchar *name);

Reports if the file format implementation is unfinished.

#### Parameters

name | File type function name. |

#### Returns

`TRUE` if the file format is considered unfinished.

### gwy_file_func_set_is_unfinished()

    void
    gwy_file_func_set_is_unfinished (const gchar *name,
                                     gboolean is_unfinished);

Sets the unfinished status of a file format.

Marking a file format as unfinished is informative.

It should be done under two conditions. The file module can actually read the files and create some images (or other data); if it cannot it should not register the file loading function. But the data it creates are wrong and possibly misleading. For example it is known the conversion from raw to physical values just does not work. It should not be marked when the support for some features is simply missing or the import mostly works fine, but it might not in some specific cases due to the file format complexity.

Gwyddion can then warn when users are opening such files.

#### Parameters

name | File type function name. |
is_unfinished | `TRUE` if the file format implementation should be considered unfinished. |

### gwy_file_detect()

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

Detects the type of a file and gives the score.

The score is normally between 0 and 100. When an I/O error occurs or the file simply does not exist, the score is set to a negative value.

#### Parameters

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). |
score | Location to store the maximum score (corresponding to the returned type) to, or `NULL`. | [out][nullable]

#### Returns

The type name (i.e., the same name as passed to e.g. `gwy_file_func_run_load()`) of most probable type of `filename` , or `NULL` if there's no probable one.

### gwy_file_load()

    GwyFile *
    gwy_file_load (const gchar *filename,
                   GwyRunModeFlags mode,
                   GError **error);

Loads a data file, autodetecting its type.

The returned object is never marked as in construction; it is always already finished.

#### Parameters

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 GwyFile with data from `filename` , or `NULL`.

### gwy_file_load_with_func()

    GwyFile *
    gwy_file_load_with_func (const gchar *filename,
                             GwyRunModeFlags mode,
                             const gchar **name,
                             GError **error);

Loads a data file, autodetecting its type.

The returned object is never marked as in construction; it is always already finished.

#### Parameters

filename | A file name to load data from, in GLib encoding. |
mode | Run mode. |
name | Location to store the name of file load function used to load the file, or `NULL`. If an error occurs outside the module, e.g. failure to recognise the file type, `NULL` is stored to `name` . |
error | Return location for a GError (or `NULL`). |

#### Returns

A new GwyFile with data from `filename` , or `NULL`.

### gwy_file_save()

    GwyFileOperationType
    gwy_file_save (GwyFile *file,
                   const gchar *filename,
                   GwyRunModeFlags 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`.

#### Parameters

file | A GwyFile 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_save_with_func()

    GwyFileOperationType
    gwy_file_save_with_func (GwyFile *file,
                             const gchar *filename,
                             GwyRunModeFlags mode,
                             const gchar **name,
                             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`.

#### Parameters

file | A GwyFile to save. |
filename | A file name to save the data as, in GLib encoding. |
mode | Run mode. |
name | Location to store the name of file load function used to save the file, or `NULL`. If an error occurs outside the module, e.g. failure to recognise the file type, `NULL` is stored to `name` . |
error | Return location for a GError (or `NULL`). |

#### Returns

The save operation that was actually realized on success, zero on failure.

### 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.

## Types and Values

### 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.

This is the maximum size. If the file is tiny the buffer contains less data. Always use `buffer_len` in the info structure for the actual size.

### 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 GwyFileOperationType

File type function file operations (capabilities).

The difference between save and export is that save is supposed to create a file containing fairly complete representation of the container, while export is the possibility to write some information to given file type. Generally only native file format module implements `GWY_FILE_OPERATION_SAVE`, all others implement `GWY_FILE_OPERATION_EXPORT`.

#### Members

GWY_FILE_OPERATION_DETECT | Posibility to detect files are of this file type, |
GWY_FILE_OPERATION_LOAD | Posibility to load files of this type. |
GWY_FILE_OPERATION_SAVE | Posibility to save files of this type. |
GWY_FILE_OPERATION_EXPORT | Posibility to export files of this type. |
GWY_FILE_OPERATION_MASK | The mask for all the flags. |

### enum 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.

#### Members

GWY_MODULE_FILE_ERROR_CANCELED | Interactive operation was cancelled by user. |
GWY_MODULE_FILE_ERROR_CANCELLED | Alias for `GWY_MODULE_FILE_ERROR_CANCELED`. |
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 | Specific module errors that do not fall into any other category (such as the failure to initialize a library used to read the data). Seldom 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).

#### Members

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` . |