![]() | ![]() | ![]() | Gwyddion Module Library Reference Manual | ![]() |
---|
gwymodule-file — File loading and saving modules
#define GWY_FILE_DETECT_BUFFER_SIZE struct GwyFileDetectInfo; struct 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);
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.
#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.
struct GwyFileDetectInfo { const gchar *name; const gchar *name_lowercase; gsize file_size; guint buffer_len; const guchar *buffer; };
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. |
struct GwyFileFuncInfo { const gchar *name; const gchar *file_desc; GwyFileDetectFunc detect; GwyFileLoadFunc load; GwyFileSaveFunc save; };
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. |
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). |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
<< gwymoduleloader | gwymodule-process >> |