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.

GwyFileLoadFunc ()

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

The type of file loading function.

GwyFileSaveFunc ()

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

The type of file saving function.

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.

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.

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.

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.

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.

gwy_file_func_exists ()

gboolean
gwy_file_func_exists (const gchar *name);

Checks whether a file type function exists.

gwy_file_func_get_operations ()

GwyFileOperationType
gwy_file_func_get_operations (const gchar *name);

Returns operations supported by a file type function.

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

gwy_file_func_foreach ()

void
gwy_file_func_foreach (GFunc function,
                       gpointer user_data);

Calls a function for each file function.

gwy_file_func_current ()

const gchar *
gwy_file_func_current (void);

Obtains the name of currently running file type function.

Detection routines are not included, only load, save and export functions.

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

If multiple nested functions are running (which is not usual but technically possible), the innermost function name is returned.

Since: 2.38

gwy_file_detect ()

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

Detects the type of a file.

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.

Since: 2.1

gwy_file_load ()

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

Loads a data file, autodetecting its type.

gwy_file_load_with_func ()

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

Loads a data file, autodetecting its type.

Since: 2.25

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.

gwy_file_save_with_func ()

GwyFileOperationType
gwy_file_save_with_func (GwyContainer *data,
                         const gchar *filename,
                         GwyRunType 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.

Since: 2.25

gwy_file_func_get_is_detectable ()

gboolean
gwy_file_func_get_is_detectable (const gchar *name);

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

Since: 2.18

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.

Since: 2.18

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.

gwy_file_get_filename_sys ()

const gchar *
gwy_file_get_filename_sys (GwyContainer *data);

Gets the file name corresponding to a data container.

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

Since: 2.36

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.

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

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.

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