## infd-storage infd-storage |

## Synopsis

                        InfdStorage;
    struct              InfdStorageIface;
    enum                InfdStorageNodeType;
    struct              InfdStorageNode;
    InfdStorageNode *   infd_storage_node_new_subdirectory  (const gchar *path);
    InfdStorageNode *   infd_storage_node_new_note          (const gchar *path,
                                                             const gchar *identifier);
    InfdStorageNode *   infd_storage_node_copy              (InfdStorageNode *node);
    void                infd_storage_node_free              (InfdStorageNode *node);
    void                infd_storage_node_list_free         (GSList *node_list);
    GSList *            infd_storage_read_subdirectory      (InfdStorage *storage,
                                                             const gchar *path,
                                                             GError **error);
    gboolean            infd_storage_create_subdirectory    (InfdStorage *storage,
                                                             const gchar *path,
                                                             GError **error);
    gboolean            infd_storage_remove_node            (InfdStorage *storage,
                                                             const gchar *identifier,
                                                             const gchar *path,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----InfdStorage

      GEnum
       +----InfdStorageNodeType

      GBoxed
       +----InfdStorageNode

## Prerequisites

InfdStorage requires GObject.

## Known Implementations

InfdStorage is implemented by InfdFilesystemStorage.

## Description

## Details

### InfdStorage

    typedef struct _InfdStorage InfdStorage;

### struct InfdStorageIface

    struct InfdStorageIface {
      GTypeInterface parent;

      /* All these calls are supposed to be synchronous, e.g. completly perform
       * the required task. Some day, we could implement asynchronous
       * behaviour in InfdDirectory (e.g. it caches operations and executes
       * them via the storage in the background). */

      /* Virtual Table */
      GSList* (*read_subdirectory)(InfdStorage* storage,
                                   const gchar* path,
                                   GError** error);

      gboolean (*create_subdirectory)(InfdStorage* storage,
                                      const gchar* path,
                                      GError** error);

      gboolean (*remove_node)(InfdStorage* storage,
                              const gchar* identifier,
                              const gchar* path,
                              GError** error);

      /* TODO: Add further methods to copy, move and expunge nodes */
      /* TODO: Notification? */
    };

### enum InfdStorageNodeType

    typedef enum {
      INFD_STORAGE_NODE_SUBDIRECTORY,
      INFD_STORAGE_NODE_NOTE
    } InfdStorageNodeType;

### struct InfdStorageNode

    struct InfdStorageNode {
      InfdStorageNodeType type;
      gchar* name;

      gchar* identifier; /* Only set when type == INFD_STORAGE_NODE_NOTE */
    };

### infd_storage_node_new_subdirectory ()

    InfdStorageNode *   infd_storage_node_new_subdirectory  (const gchar *path);

Creates a new InfdStorageNode with type `INFD_STORAGE_NODE_SUBDIRECTORY` and the given path. This is most likely only going to be used by InfdStorage implementations.

`path` : | Path to the node.
Returns : | A new InfdStorageNode.

### infd_storage_node_new_note ()

    InfdStorageNode *   infd_storage_node_new_note          (const gchar *path,
                                                             const gchar *identifier);

Creates a new InfdStorageNode with type `INFD_STORAGE_NODE_NOTE` and the given path and identifier. This is most likely only going to be used by InfdStorage implementations.

`path` : | Path to the node.
`identifier` : | Identifier of the note type, for example 'InfText' for text notes.
Returns : | A new InfdStorageNode.

### infd_storage_node_copy ()

    InfdStorageNode *   infd_storage_node_copy              (InfdStorageNode *node);

Creates a copy of a InfdStorageNode object.

`node` : | Node from which to make a copy.
Returns : | A copy of `node`.

### infd_storage_node_free ()

    void                infd_storage_node_free              (InfdStorageNode *node);

Frees a InfdStorageNode allocated with `infd_storage_node_new_subdirectory()`, `infd_storage_node_new_node()` or `infd_storage_node_copy()`.

`node` : | A InfdStorageNode.

### infd_storage_node_list_free ()

    void                infd_storage_node_list_free         (GSList *node_list);

Frees a singly-linked list of InfdStorageNode as returned by `infd_storage_read_subdirectory()`.

`node_list` : | A list of InfdStorageNode objects.

### infd_storage_read_subdirectory ()

    GSList *            infd_storage_read_subdirectory      (InfdStorage *storage,
                                                             const gchar *path,
                                                             GError **error);

### infd_storage_create_subdirectory ()

    gboolean            infd_storage_create_subdirectory    (InfdStorage *storage,
                                                             const gchar *path,
                                                             GError **error);

Creates a new subdirectory at the given path that is initially empty.

`storage` : | A InfdStorage.
`path` : | A path pointing to non-existing node.
`error` : | Location to store error information.
Returns : | `TRUE` on success.

### infd_storage_remove_node ()

    gboolean            infd_storage_remove_node            (InfdStorage *storage,
                                                             const gchar *identifier,
                                                             const gchar *path,
                                                             GError **error);

Removes the node at path from storage. If it is a subdirectory node, all containing nodes and subdirectory nodes are removed recursively.

`storage` : | A InfdStorage
`identifier` : | The type of the node to remove, or `NULL` to remove a subdirectory (TODO: This shouldn't be necessary).
`path` : | A path pointing to an existing node.
`error` : | Location to store error information.
Returns : | `TRUE` on success.