![]() |
![]() |
![]() |
libinfinity-0.3 Reference Manual | ![]() |
---|---|---|---|---|
#include <libinfinity/server/infd-directory.h> InfdDirectoryIter; InfdDirectory; InfdDirectoryClass; InfdDirectoryIter* infd_directory_iter_copy (InfdDirectoryIter *iter); void infd_directory_iter_free (InfdDirectoryIter *iter); InfdDirectory* infd_directory_new (InfIo *io, InfdStorage *storage, InfCommunicationManager *comm_manager); InfIo* infd_directory_get_io (InfdDirectory *directory); InfdStorage* infd_directory_get_storage (InfdDirectory *directory); InfCommunicationManager* infd_directory_get_communication_manager (InfdDirectory *directory); gboolean infd_directory_add_plugin (InfdDirectory *directory, const InfdNotePlugin *plugin); const InfdNotePlugin* infd_directory_lookup_plugin (InfdDirectory *directory, const gchar *note_type); gboolean infd_directory_add_connection (InfdDirectory *directory, InfXmlConnection *connection); const gchar* infd_directory_iter_get_name (InfdDirectory *directory, InfdDirectoryIter *iter); gchar* infd_directory_iter_get_path (InfdDirectory *directory, InfdDirectoryIter *iter); void infd_directory_iter_get_root (InfdDirectory *directory, InfdDirectoryIter *iter); gboolean infd_directory_iter_get_next (InfdDirectory *directory, InfdDirectoryIter *iter); gboolean infd_directory_iter_get_prev (InfdDirectory *directory, InfdDirectoryIter *iter); gboolean infd_directory_iter_get_parent (InfdDirectory *directory, InfdDirectoryIter *iter); gboolean infd_directory_iter_get_child (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error); gboolean infd_directory_iter_get_explored (InfdDirectory *directory, InfdDirectoryIter *iter); gboolean infd_directory_add_subdirectory (InfdDirectory *directory, InfdDirectoryIter *parent, const gchar *name, InfdDirectoryIter *iter, GError **error); gboolean infd_directory_add_note (InfdDirectory *directory, InfdDirectoryIter *parent, const gchar *name, const InfdNotePlugin *plugin, InfdDirectoryIter *iter, GError **error); gboolean infd_directory_remove_node (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error); InfdStorageNodeType infd_directory_iter_get_node_type (InfdDirectory *directory, InfdDirectoryIter *iter); const InfdNotePlugin* infd_directory_iter_get_plugin (InfdDirectory *directory, InfdDirectoryIter *iter); InfdSessionProxy* infd_directory_iter_get_session (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error); InfdSessionProxy* infd_directory_iter_peek_session (InfdDirectory *directory, InfdDirectoryIter *iter); gboolean infd_directory_iter_save_session (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error);
"communication-manager" InfCommunicationManager* : Read / Write / Construct Only "io" InfIo* : Read / Write / Construct Only "storage" InfdStorage* : Read / Write / Construct Only
"add-session" : Run Last "node-added" : Run Last "node-removed" : Run Last "remove-session" : Run Last
The InfdDirectory manages a directory of documents. An item in the directory is also called "node". A node may either be a subdirectory or a document (also called "note"). Notes may be of different type - there may be plain text notes, rich text notes, graphics notes, etc.
InfdStorage defines where the directory structure and the notes are read from and how there are permanently stored.
typedef struct { GObjectClass parent_class; /* Signals */ void (*node_added)(InfdDirectory* directory, InfdDirectoryIter* iter); void (*node_removed)(InfdDirectory* directory, InfdDirectoryIter* iter); void (*add_session)(InfdDirectory* directory, InfdDirectoryIter* iter, InfdSessionProxy* session); void (*remove_session)(InfdDirectory* directory, InfdDirectoryIter* iter, InfdSessionProxy* session); } InfdDirectoryClass;
InfdDirectoryIter* infd_directory_iter_copy (InfdDirectoryIter *iter);
Makes a dynamically-allocated copy of iter
. This should not be used by
applications because you can copy the structs by value.
|
A InfdDirectoryIter. |
Returns : |
A newly-allocated copy of iter .
|
void infd_directory_iter_free (InfdDirectoryIter *iter);
Frees a InfdDirectoryIter allocated with infd_directory_iter_copy()
.
|
A InfdDirectoryIter. |
InfdDirectory* infd_directory_new (InfIo *io, InfdStorage *storage, InfCommunicationManager *comm_manager);
Creates a new InfdDirectory.
|
IO object to watch connections and schedule timeouts. |
|
Storage backend that is used to read/write notes from permanent memory into InfBuffer objects. |
|
A InfCommunicationManager to register added connections to and which forwards incoming data to the directory or running sessions. |
Returns : |
A new InfdDirectory. |
InfIo* infd_directory_get_io (InfdDirectory *directory);
Returns the IO object in use by the directory.
|
A InfdDirectory. |
Returns : |
A InfIo. |
InfdStorage* infd_directory_get_storage (InfdDirectory *directory);
Returns the storage backend in use by the directory.
|
A "" |
Returns : |
An InfdDirectoryStorage. |
InfCommunicationManager* infd_directory_get_communication_manager (InfdDirectory *directory);
Returns the connection manager of the directory.
|
A InfdDirectory. |
Returns : |
An InfCommunicationManager. |
gboolean infd_directory_add_plugin (InfdDirectory *directory, const InfdNotePlugin *plugin);
Adds plugin
to directory
. This allows the directory to create sessions
of the plugin's type. Only one plugin of each type can be added to the
directory. The plugin's storage_type must match the storage of directory
.
|
A InfdDirectory. |
|
A InfdNotePlugin. |
Returns : |
Whether the plugin was added successfully. |
const InfdNotePlugin* infd_directory_lookup_plugin (InfdDirectory *directory, const gchar *note_type);
Returns the InfdNotePlugin that handles the given note type, or NULL
in case no corresponding plugin was added.
|
A InfdDirectory. |
|
A note type for which to lookup the plugin. |
Returns : |
A InfdNotePlugin, or NULL .
|
gboolean infd_directory_add_connection (InfdDirectory *directory, InfXmlConnection *connection);
Adds connection
to the connections of directory
. The directory will then
receive requests from connection
. If the directory's method manager does
not contain a "central" method for connection's network, then the
connection will not be added and the function returns FALSE
.
|
A InfdDirectory. |
|
A InfConnection. |
Returns : |
Whether the connection was added to the directory. |
const gchar* infd_directory_iter_get_name (InfdDirectory *directory, InfdDirectoryIter *iter);
Returns the name of the node iter
points to.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a node in directory .
|
Returns : |
The node's name. The returned string must not be freed. |
gchar* infd_directory_iter_get_path (InfdDirectory *directory, InfdDirectoryIter *iter);
Returns the complete path to the node iter
points to. The path to a node
is the name of the node and the name of all parent nodes separated by '/',
as a filesystem path on Unix.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a node in directory .
|
Returns : |
The node's path. Free with g_free() when no longer in use.
|
void infd_directory_iter_get_root (InfdDirectory *directory, InfdDirectoryIter *iter);
Sets iter
to point to the root node of the directory.
|
A InfdDirectory
iter An uninitalized InfdDirectoryIter.
|
|
gboolean infd_directory_iter_get_next (InfdDirectory *directory, InfdDirectoryIter *iter);
Sets iter
to point to the next node within the same subdirectory. If there
is no next node, iter
is left untouched and the function returns FALSE
.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to some node in directory .
|
Returns : |
TRUE , if iter was set.
|
gboolean infd_directory_iter_get_prev (InfdDirectory *directory, InfdDirectoryIter *iter);
Sets iter
to point to the previous node within the same subdirectory. If
there is no such node, iter
is left untouched and the function returns
FALSE
.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to some node in directory .
|
Returns : |
TRUE , if iter was set.
|
gboolean infd_directory_iter_get_parent (InfdDirectory *directory, InfdDirectoryIter *iter);
Sets iter
to point to the parent node of iter
. This node is guaranteed
to be a subdirectory node. If there is no such node (i.e. iter
points
to the root node), iter
is left untouched and the function returns FALSE
.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to some node in directory .
|
Returns : |
TRUE , if iter was set.
|
gboolean infd_directory_iter_get_child (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error);
Sets iter
to point to first child node of iter
. This requires that iter
points to a subdirectory node. If the subdirectory iter
points to has
no children, the function returns FALSE
and iter
is left untouched.
The function might fail if this node's children have not yet been read
from the background storage and an error occurs while reading them. In
this case, FALSE
is returned and error
is set.
The function guarantees not to set error
if the node is already explored,
i.e. infd_directory_iter_get_explored()
returns TRUE
for directory
and
iter
.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a subdirectory node in directory .
|
|
Location to store error information. |
Returns : |
TRUE , if iter was set.
|
gboolean infd_directory_iter_get_explored (InfdDirectory *directory, InfdDirectoryIter *iter);
Returns whether the subdirectory node pointed to by iter
has already
been read from the background storage. If not, then no connections can
be subscribed to any child nodes.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a subdirectory node in directory .
|
Returns : |
Whether the node iter points to has been explored.
|
gboolean infd_directory_add_subdirectory (InfdDirectory *directory, InfdDirectoryIter *parent, const gchar *name, InfdDirectoryIter *iter, GError **error);
Adds a subdirectory to the directory tree. The new subdirectory will be
a child the subdirectory parent
points to. iter
is modified to point to
the new subdirectory. If creation fails, the function returns FALSE and
error
is set.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a subdirectory node
in directory .
|
|
The name of the new node. |
|
An uninitalized InfdDirectoryIter. |
|
Location to store error information. |
Returns : |
TRUE if the subdirectory was created successfully.
|
gboolean infd_directory_add_note (InfdDirectory *directory, InfdDirectoryIter *parent, const gchar *name, const InfdNotePlugin *plugin, InfdDirectoryIter *iter, GError **error);
Creates a new note in directory
. It will be child of the subdirectory
node parent
points to. iter
is set to point to the new node. If an
error occurs, the function returns FALSE
and error
is set.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a subdirectory node
in directory .
|
|
The name of the new node. |
|
The plugin to use for the node. Must have been added with
infd_directory_add_plugin() .
|
|
An uninitialized InfdDirectoryIter. |
|
Location to store error information. |
Returns : |
TRUE on success.
|
gboolean infd_directory_remove_node (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error);
Removes the node iter
points to. If it is a subdirectory node, every
node it contains will also be removed. If the function fails, FALSE
is
returned and error
is set.
|
A InfdDirectory |
|
A InfdDirectoryIter pointing to some node in directory .
|
|
Location to store error information. |
Returns : |
TRUE on success.
|
InfdStorageNodeType infd_directory_iter_get_node_type (InfdDirectory *directory, InfdDirectoryIter *iter);
Returns the type of the node iter
points to.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to some node in directory .
|
Returns : |
A InfdDirectoryStorageNodeType. |
const InfdNotePlugin* infd_directory_iter_get_plugin (InfdDirectory *directory, InfdDirectoryIter *iter);
Returns the plugin that is used to create a session for the note iter
points to.
|
A InfdDirectory. |
|
a InfdDirectoryIter pointing to a note in directory .
|
Returns : |
The plugin for the note iter points to.
|
InfdSessionProxy* infd_directory_iter_get_session (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error);
Returns the running session in which the note iter
points to is currently
edited. If the session does not exist, it is created. However, this might
fail if the loading from the background storage fails. In this case, NULL
is returned and error
is set.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a note in directory .
|
|
Location to store error information. |
Returns : |
A InfdSessionProxy for the note iter points to.
|
InfdSessionProxy* infd_directory_iter_peek_session (InfdDirectory *directory, InfdDirectoryIter *iter);
Returns the running session in which the note iter
points to is currently
edited. If the session does not exist because nobody is editing it at the
moment, the function returns NULL
.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a note in directory .
|
Returns : |
A InfdSessionProxy for the note iter points to, or NULL .
|
gboolean infd_directory_iter_save_session (InfdDirectory *directory, InfdDirectoryIter *iter, GError **error);
Attempts to store the session the node iter
points to represents into the
background storage.
|
A InfdDirectory. |
|
A InfdDirectoryIter pointing to a note in directory .
|
|
Location to store error information. |
Returns : |
TRUE if the operation succeeded, FALSE otherwise.
|
"communication-manager"
property"communication-manager" InfCommunicationManager* : Read / Write / Construct Only
The communication manager for the directory.
"io"
property"io" InfIo* : Read / Write / Construct Only
IO object to watch sockets and schedule timeouts.
"storage"
property"storage" InfdStorage* : Read / Write / Construct Only
The storage backend to use.
"add-session"
signalvoid user_function (InfdDirectory *directory, InfdDirectoryIter *iter, InfdSessionProxy *session, gpointer user_data) : Run Last
This signal is emitted, when a session has been associated with a node.
This happens when infd_directory_iter_get_session()
is called on a node,
when a remote client subscribes to a session or a new node was created.
When a session has been created for a node, the session is kept until it is idle for some time. Then, it is removed again after having been stored into the background storage.
|
The InfdDirectory emitting the signal. |
|
A InfdDirectoryIter pointing to the affected node. |
|
The InfdSessionProxy proxying the added session. |
|
user data set when the signal handler was connected. |
"node-added"
signalvoid user_function (InfdDirectory *directory, InfdDirectoryIter *iter, gpointer user_data) : Run Last
This signal is emitted when a new node has been created. It can either
be created by API calls such as infd_directory_add_note()
and
infd_directory_add_subdirectory()
or by a client making a corresponding
request.
|
The InfdDirectory emitting the signal. |
|
A InfdDirectoryIter pointing to the added node. |
|
user data set when the signal handler was connected. |
"node-removed"
signalvoid user_function (InfdDirectory *directory, InfdDirectoryIter *iter, gpointer user_data) : Run Last
This signal is emitted when a node has been removed. If a subdirectory
node is removed, all contained nodes are removed as well. Node removal
can either happen through a call to infd_directory_remove_node()
, or by
a client making a corresponding request.
|
The InfdDirectory emitting the signal. |
|
A InfdDirectoryIter pointing to the removed node. |
|
user data set when the signal handler was connected. |
"remove-session"
signalvoid user_function (InfdDirectory *directory, InfdDirectoryIter *iter, InfdSessionProxy *session, gpointer user_data) : Run Last
This signal is emitted when a previously added session was removed. This happens when a session is idle for some time, or when the corresponding node has been removed.
|
The InfdDirectory emitting the signal. |
|
A InfdDirectoryIter pointing to the affected node. |
|
The InfdSessionProxy proxying the removed session. |
|
user data set when the signal handler was connected. |