## InfdFilesystemStorage

InfdFilesystemStorage

## Functions

InfdFilesystemStorage * | infd_filesystem_storage_new ()
gchar * | infd_filesystem_storage_get_path ()
FILE * | infd_filesystem_storage_open ()
xmlDocPtr | infd_filesystem_storage_read_xml_file ()
gboolean | infd_filesystem_storage_write_xml_file ()
int | infd_filesystem_storage_stream_close ()
gsize | infd_filesystem_storage_stream_read ()
gsize | infd_filesystem_storage_stream_write ()

## Properties

gchar * | root-directory | Read / Write / Construct Only

## Types and Values

enum | InfdFilesystemStorageError
struct | InfdFilesystemStorage
struct | InfdFilesystemStorageClass

## Object Hierarchy

        GObject
        ╰── InfdFilesystemStorage

## Implemented Interfaces

InfdFilesystemStorage implements InfdStorage.

## Description

## Functions

### infd_filesystem_storage_new ()

    InfdFilesystemStorage *
    infd_filesystem_storage_new (const gchar *root_directory);

Creates a new InfdFilesystemStorage that stores its nodes in the given directory on the file system. The directory is created if it does not exist.

[constructor]

#### Parameters

root_directory | A directory name in UTF-8. |

#### Returns

A new InfdFilesystemStorage.

[transfer full]

### infd_filesystem_storage_get_path ()

    gchar *
    infd_filesystem_storage_get_path (InfdFilesystemStorage *storage,
                                      const gchar *identifier,
                                      const gchar *path,
                                      GError **error);

Returns the full file name to the given path within the storage's root directory. The function might fail if `path` contains invalid characters. If the function fails, `NULL` is returned and `error` is set.

Only if `identifier` starts with "Inf", the file will show up in the directory listing of `infd_storage_read_subdirectory()`. Other identifiers can be used to store custom data in the filesystem, linked to this InfdFilesystemStorage object.

#### Parameters

storage | A InfdFilesystemStorage. |
identifier | The type of node to open. |
path | The path to open, in UTF-8. |
error | Location to store error information, if any, or `NULL`. |

#### Returns

An absolute filename path to be freed with `g_free()`, or `NULL`.

[type filename][allow-none][transfer full]

### infd_filesystem_storage_open ()

    FILE *
    infd_filesystem_storage_open (InfdFilesystemStorage *storage,
                                  const gchar *identifier,
                                  const gchar *path,
                                  const gchar *mode,
                                  gchar **full_path,
                                  GError **error);

Opens a file in the given path within the storage's root directory. If the file exists already, and `mode` is set to "w", the file is overwritten.

If `full_path` is not `NULL`, then it will be set to a newly allocated string which contains the full name of the opened file, in the Glib file name encoding. Note that `full_path` will also be set if the function fails.

Only if `identifier` starts with "Inf", the file will show up in the directory listing of `infd_storage_read_subdirectory()`. Other identifiers can be used to store custom data in the filesystem, linked to this InfdFilesystemStorage object.

#### Parameters

storage | A InfdFilesystemStorage. |
identifier | The type of node to open. |
path | The path to open, in UTF-8. |
mode | Either "r" for reading or "w" for writing. |
full_path | Return location of the full filename, or `NULL`. | [out][type filename][transfer full]
error | Location to store error information, if any. |

#### Returns

A stream for the open file. Close with `infd_filesystem_storage_stream_close()`.

[transfer full]

### infd_filesystem_storage_read_xml_file ()

    xmlDocPtr
    infd_filesystem_storage_read_xml_file (InfdFilesystemStorage *storage,
                                           const gchar *identifier,
                                           const gchar *path,
                                           const gchar *toplevel_tag,
                                           GError **error);

Opens a file in the given path, and parses its XML content. See `infd_filesystem_storage_open()` for how `identifier` and `path` should be interpreted.

If `toplevel_tag` is non-`NULL`, then this function generates an error if the XML document read has a toplevel tag with a different name.

#### Parameters

storage | A InfdFilesystemStorage. |
identifier | The type of node to open. |
path | The path to open, in UTF-8. |
toplevel_tag | The expected toplevel XML tag name, or `NULL`. |
error | Location to store error information, if any. |

#### Returns

A new XML document, or `NULL` on error. Free with `xmlDocFree()`.

[transfer full][allow-none]

### infd_filesystem_storage_write_xml_file ()

    gboolean
    infd_filesystem_storage_write_xml_file
                                   (InfdFilesystemStorage *storage,
                                    const gchar *identifier,
                                    const gchar *path,
                                    xmlDocPtr doc,
                                    GError **error);

Writes the XML doument in `doc` into a file in the filesystem indicated by `identifier` and `path` . See `infd_filesystem_storage_open()` for how `identifier` and `path` should be interpreted.

#### Parameters

storage | A InfdFilesystemStorage. |
identifier | The type of node to write. |
path | The path to write to, in UTF-8. |
doc | The XML document to write. |
error | Location to store error information, if any. |

#### Returns

`TRUE` on success or `FALSE` on error.

### infd_filesystem_storage_stream_close ()

    int
    infd_filesystem_storage_stream_close (FILE *file);

This is a thin wrapper around `fclose()`. Use this function instead of `fclose()` if you have opened the file with `infd_filesystem_storage_open()`, to make sure that the same C runtime is closing the file that has opened it.

#### Parameters

file | A FILE opened with `infd_filesystem_storage_open()`. |

#### Returns

The return value of `fclose()`.

### infd_filesystem_storage_stream_read ()

    gsize
    infd_filesystem_storage_stream_read (FILE *file,
                                         gpointer buffer,
                                         gsize len);

This is a thin wrapper around `fread()`. Use this function instead of `fread()` if you have opened the file with `infd_filesystem_storage_open()`, to make sure that the same C runtime is closing the file that has opened it.

#### Parameters

file | A FILE opened with `infd_filesystem_storage_open()`. |
buffer | A buffer into which to read data. | [type guint8*][array length=len][out]
len | Maximum number of bytes to read. |

#### Returns

The return value of `fread()`.

### infd_filesystem_storage_stream_write ()

    gsize
    infd_filesystem_storage_stream_write (FILE *file,
                                          gconstpointer buffer,
                                          gsize len);

This is a thin wrapper around `fwrite()`. Use this function instead of `fwrite()` if you have opened the file with `infd_filesystem_storage_open()`, to make sure that the same C runtime is closing the file that has opened it.

#### Parameters

file | A FILE opened with `infd_filesystem_storage_open()`. |
buffer | The data to write. |
len | Maximum number of bytes to write. |

#### Returns

The return value of `fwrite()`.

## Types and Values

### enum InfdFilesystemStorageError

#### Members

INFD_FILESYSTEM_STORAGE_ERROR_INVALID_PATH |  |
INFD_FILESYSTEM_STORAGE_ERROR_REMOVE_FILES |  |
INFD_FILESYSTEM_STORAGE_ERROR_INVALID_FORMAT |  |
INFD_FILESYSTEM_STORAGE_ERROR_FAILED |  |

### struct InfdFilesystemStorage

    struct InfdFilesystemStorage;

### struct InfdFilesystemStorageClass

    struct InfdFilesystemStorageClass {
      GObjectClass parent_class;
    };

## Property Details

### The `“root-directory”` property

      “root-directory”           gchar *

The directory in which the storage stores its content.

Owner: InfdFilesystemStorage

Flags: Read / Write / Construct Only

Default value: NULL