gwymodule-file

gwymodule-file — File loading and saving modules

Synopsis




#define     GWY_FILE_DETECT_BUFFER_SIZE
            GwyFileDetectInfo;
            GwyFileFuncInfo;
gint        (*GwyFileDetectFunc)            (const GwyFileDetectInfo *fileinfo,
                                             gboolean only_name,
                                             const gchar *name);
GwyContainer* (*GwyFileLoadFunc)            (const gchar *filename,
                                             const gchar *name);
gboolean    (*GwyFileSaveFunc)              (GwyContainer *data,
                                             const gchar *filename,
                                             const gchar *name);
gboolean    gwy_file_func_register          (const gchar *modname,
                                             GwyFileFuncInfo *func_info);
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);
gboolean    gwy_file_func_run_save          (const gchar *name,
                                             GwyContainer *data,
                                             const gchar *filename);
GwyFileOperation gwy_file_func_get_operations
                                            (const gchar *name);
const gchar* gwy_file_func_get_description  (const gchar *name);
gchar*      gwy_file_detect                 (const gchar *filename,
                                             gboolean only_name,
                                             GwyFileOperation operations);
GwyContainer* gwy_file_load                 (const gchar *filename);
gboolean    gwy_file_save                   (GwyContainer *data,
                                             const gchar *filename);
GtkObject*  gwy_file_func_build_menu        (GtkObject *item_factory,
                                             const gchar *prefix,
                                             GCallback item_callback,
                                             GwyFileOperation type);

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.


GwyFileDetectInfo

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

File detection data.

It contains common information file type detection routines need to obtain. It is shared between file detection functions and they must not modify its contents.

const gchar *name; File name.
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 buffer in bytes. Normally it's GWY_FILE_DETECT_BUFFER_SIZE except when file is shorter than that. Undefined if only_name.
const guchar *buffer; Initial part of file. Undefined if only_name.

GwyFileFuncInfo

typedef struct {
    const gchar *name;
    const gchar *file_desc;
    GwyFileDetectFunc detect;
    GwyFileLoadFunc load;
    GwyFileSaveFunc save;
} GwyFileFuncInfo;

Information about set of functions for one file type.

const gchar *name; File type function name (used for all detect/save/load functions).
const gchar *file_desc; Brief file type description. This will appear in the menu so it should not contain slashes, and the preferred form is "Foobar data (.foo)".
GwyFileDetectFunc detect; The file type detecting function.
GwyFileLoadFunc load; The file loading function.
GwyFileSaveFunc save; The file saving function.

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 GwyFileFuncInfo (most 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,
                                             const gchar *name);

The type of file loading function.

filename : A file name to load data from.
name : Function name from GwyFileFuncInfo (most modules can safely ignore this argument)
Returns : A newly created data container or NULL.

GwyFileSaveFunc ()

gboolean    (*GwyFileSaveFunc)              (GwyContainer *data,
                                             const gchar *filename,
                                             const gchar *name);

The type of file saving function.

data : A GwyContainer to save.
filename : A file name to save data as.
name : Function name from GwyFileFuncInfo (most 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 *modname,
                                             GwyFileFuncInfo *func_info);

Registeres a file type function.

To keep compatibility with old versions func_info should not be an automatic variable. However, since 1.6 it keeps a copy of func_info.

modname : Module identifier (name).
func_info : File type function info.
Returns : TRUE on success, 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);

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

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.
Returns : TRUE if file save succeeded, FALSE otherwise.

gwy_file_func_get_operations ()

GwyFileOperation gwy_file_func_get_operations
                                            (const gchar *name);

Returns possible operations for a file type function identified by name.

This function is the prefered one for testing whether a file function exists, as function with no operations cannot be registered.

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

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

Detects file type of file filename.

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 (all of them) the file type should support.
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_load ()

GwyContainer* gwy_file_load                 (const gchar *filename);

Loads a data file, autodetecting its type.

filename : A file name to load data from.
Returns : A new GwyContainer with data from filename, or NULL.

gwy_file_save ()

gboolean    gwy_file_save                   (GwyContainer *data,
                                             const gchar *filename);

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

data : A GwyContainer to save.
filename : A file name to save the data as.
Returns : TRUE if file save succeeded, FALSE otherwise.

gwy_file_func_build_menu ()

GtkObject*  gwy_file_func_build_menu        (GtkObject *item_factory,
                                             const gchar *prefix,
                                             GCallback item_callback,
                                             GwyFileOperation type);

Creates GtkItemFactory for a file type menu with all registered file type functions.

item_factory : A GtkItemFactory to add items to.
prefix : Where to add the menu items to the factory.
item_callback : A GtkItemFactoryCallback1 called when an item from the menu is selected.
type : Only function providing this file operation are included in the menu.
Returns : The menu item factory as a GtkObject.