Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

gwymodule-file (HEAD)

gwymodule-file — File loading and saving modules

Functions

gint (*GwyFileDetectFunc) ()
GwyContainer * (*GwyFileLoadFunc) ()
gboolean (*GwyFileSaveFunc) ()
gboolean gwy_file_func_register ()
gint gwy_file_func_run_detect ()
GwyContainer * 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 ()
const gchar * gwy_file_detect ()
const gchar * gwy_file_detect_with_score ()
GwyContainer * gwy_file_load ()
GwyContainer * gwy_file_load_with_func ()
GwyFileOperationType gwy_file_save ()
GwyFileOperationType gwy_file_save_with_func ()
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 ()
gboolean gwy_file_get_data_info ()
const gchar * gwy_file_get_filename_sys ()
GQuark gwy_module_file_error_quark ()

Types and Values

#define GWY_FILE_DETECT_BUFFER_SIZE
#define GWY_MODULE_FILE_ERROR
enum GwyModuleFileError
  GwyFileDetectInfo

Includes

#include <libgwymodule/gwymodule.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,
                      const gchar *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:

Parameters

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 likelyhood score.

GwyFileLoadFunc ()

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

The type of file loading function.

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

 

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.

Parameters

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_);

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

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.

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

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

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.

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

Parameters

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.

Parameters

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.

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

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.

Returns

The name of currently running file type function or NULL.

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.

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

 

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

Parameters

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

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

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.

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

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.

Parameters

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

Parameters

data

A GwyContainer 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.

Since: 2.25

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.

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.

Parameters

name

File type function name.

 

is_detectable

TRUE to define format as detectable, FALSE as non-detectable.

 

Since: 2.18

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.

Since: 2.65

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.

 

Since: 2.65

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.

Parameters

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

Parameters

data

A GwyContainer.

 

Returns

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.

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.

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

 

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 .

 
© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS