InfdDirectory

InfdDirectory — Directory of published documents

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfinity/server/infd-directory.h>

                    InfdDirectory;
struct              InfdDirectoryClass;
void                (*InfdDirectoryForeachConnectionFunc)
                                                        (InfXmlConnection *Param1,
                                                         gpointer Param2);
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);
void                infd_directory_set_certificate      (InfdDirectory *directory,
                                                         gnutls_x509_privkey_t key,
                                                         InfCertificateChain *cert);
gboolean            infd_directory_add_plugin           (InfdDirectory *directory,
                                                         const InfdNotePlugin *plugin);
void                infd_directory_remove_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);
void                infd_directory_get_support_mask     (InfdDirectory *directory,
                                                         InfAclMask *mask);
InfAclAccountId     infd_directory_get_acl_account_for_connection
                                                        (InfdDirectory *directory,
                                                         InfXmlConnection *connection);
gboolean            infd_directory_set_acl_account_for_connection
                                                        (InfdDirectory *directory,
                                                         InfXmlConnection *connection,
                                                         InfAclAccountId account_id,
                                                         GError **error);
void                infd_directory_foreach_connection   (InfdDirectory *directory,
                                                         InfdDirectoryForeachConnectionFunc func,
                                                         gpointer user_data);
gboolean            infd_directory_iter_save_session    (InfdDirectory *directory,
                                                         InfBrowserIter *iter,
                                                         GError **error);
void                infd_directory_enable_chat          (InfdDirectory *directory,
                                                         gboolean enable);
InfdSessionProxy *  infd_directory_get_chat_session     (InfdDirectory *directory);
InfAclAccountId     infd_directory_create_acl_account   (InfdDirectory *directory,
                                                         const gchar *account_name,
                                                         gboolean transient,
                                                         gnutls_x509_crt_t *certificates,
                                                         guint n_certificates,
                                                         GError **error);

Object Hierarchy

  GObject
   +----InfdDirectory

Implemented Interfaces

InfdDirectory implements InfCommunicationObject and InfBrowser.

Properties

  "account-storage"          InfdAccountStorage*   : Read / Write / Construct
  "certificate"              InfCertificateChain*  : Read / Write
  "chat-session"             InfdSessionProxy*     : Read
  "communication-manager"    InfCommunicationManager*  : Read / Write / Construct Only
  "io"                       InfIo*                : Read / Write / Construct Only
  "private-key"              gpointer              : Read / Write
  "storage"                  InfdStorage*          : Read / Write / Construct

Signals

  "connection-added"                               : Run Last
  "connection-removed"                             : Run Last

Description

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 they are permanently stored.

Details

InfdDirectory

typedef struct _InfdDirectory InfdDirectory;


struct InfdDirectoryClass

struct InfdDirectoryClass {
  GObjectClass parent_class;

  void (*connection_added)(InfdDirectory* directory,
                           InfXmlConnection* connection);
  void (*connection_removed)(InfdDirectory* directory,
                             InfXmlConnection* connection);
};


InfdDirectoryForeachConnectionFunc ()

void                (*InfdDirectoryForeachConnectionFunc)
                                                        (InfXmlConnection *Param1,
                                                         gpointer Param2);


infd_directory_new ()

InfdDirectory *     infd_directory_new                  (InfIo *io,
                                                         InfdStorage *storage,
                                                         InfCommunicationManager *comm_manager);

Creates a new InfdDirectory. If storage is NULL then the directory keeps all content in memory. This can make sense for ad-hoc sessions where no central document storage is required.

io :

IO object to watch connections and schedule timeouts.

storage :

Storage backend that is used to read/write notes from permanent memory into InfBuffer objects, or NULL.

comm_manager :

A InfCommunicationManager to register added connections to and which forwards incoming data to the directory or running sessions.

Returns :

A new InfdDirectory.

infd_directory_get_io ()

InfIo *             infd_directory_get_io               (InfdDirectory *directory);

Returns the IO object in use by the directory.

directory :

A InfdDirectory.

Returns :

A InfIo.

infd_directory_get_storage ()

InfdStorage *       infd_directory_get_storage          (InfdDirectory *directory);

Returns the storage backend in use by the directory.

directory :

A InfdDirectory:

Returns :

An InfdStorage.

infd_directory_get_communication_manager ()

InfCommunicationManager * infd_directory_get_communication_manager
                                                        (InfdDirectory *directory);

Returns the connection manager of the directory.

directory :

A InfdDirectory.

Returns :

An InfCommunicationManager.

infd_directory_set_certificate ()

void                infd_directory_set_certificate      (InfdDirectory *directory,
                                                         gnutls_x509_privkey_t key,
                                                         InfCertificateChain *cert);

Sets the private key and certificate chain of the directory. The directory does not use these for certificate authentication with added connections. Connections should already be authenticated, for example with the means of InfXmppConnection.

At the moment, the directory certificate is used to sign incoming certificate requests. Selected clients can request a certificate signed with the server's certificates, see inf_browser_create_acl_account(). If the server certificate is set with this function, the request is handled properly. If no certificate is set with this function, such a request is rejected.

directory :

A InfdDirectory.

key :

The private key of the directory.

cert :

The certificate chain of the directory.

infd_directory_add_plugin ()

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. If the directory's storage is NULL, then the plugin's storage type does not matter, and the plugin's session_read and session_write functions will not be used (and can therefore be NULL).

directory :

A InfdDirectory.

plugin :

A InfdNotePlugin.

Returns :

Whether the plugin was added successfully.

infd_directory_remove_plugin ()

void                infd_directory_remove_plugin        (InfdDirectory *directory,
                                                         const InfdNotePlugin *plugin);

Removes a note plugin from the directory. If there are any sessions running using this plugin, they are unsubscribed from the directory.

directory :

A InfdDirectory.

plugin :

The plugin to remove.

infd_directory_lookup_plugin ()

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.

directory :

A InfdDirectory.

note_type :

A note type for which to lookup the plugin.

Returns :

A InfdNotePlugin, or NULL.

infd_directory_add_connection ()

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.

The connection is removed again automatically if it is closed.

directory :

A InfdDirectory.

connection :

A InfXmlConnection.

Returns :

Whether the connection was added to the directory.

infd_directory_get_support_mask ()

void                infd_directory_get_support_mask     (InfdDirectory *directory,
                                                         InfAclMask *mask);

This function writes all operations supported by directory to mask. If an operation is unsupported by the server, the corresponding field in the mask will not be set.

directory :

A InfdDirectory.

mask :

A pointer to a InfAclMask that will be filled.

infd_directory_get_acl_account_for_connection ()

InfAclAccountId     infd_directory_get_acl_account_for_connection
                                                        (InfdDirectory *directory,
                                                         InfXmlConnection *connection);

This function returns the InfAclAccountId that the given connection is logged into. The connection must have been added to the directory before with infd_directory_add_connection(). If no special login was performed, the default account is returned.

directory :

A InfdDirectory.

connection :

A connection added to directory.

Returns :

A InfAclAccountId.

infd_directory_set_acl_account_for_connection ()

gboolean            infd_directory_set_acl_account_for_connection
                                                        (InfdDirectory *directory,
                                                         InfXmlConnection *connection,
                                                         InfAclAccountId account_id,
                                                         GError **error);

This function changes the account that the given connection is logged into. The connection must have been added to the directory before with infd_directory_add_connection(). In order to remove a login, account_id should be set to the default account.

The function might fail if there is no account that corresponds to account, or if the account storage reports an error when looking up the account.

directory :

A InfdDirectory.

connection :

A connection added to directory.

account_id :

A InfAclAccountId representing a valid account in directory.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

infd_directory_foreach_connection ()

void                infd_directory_foreach_connection   (InfdDirectory *directory,
                                                         InfdDirectoryForeachConnectionFunc func,
                                                         gpointer user_data);

Calls func for each connection in directory that has previously been added to the directory. It is allowed to add and remove connections while this function is being called.

directory :

A InfdDirectory.

func :

The function to call for each connection in directory.

user_data :

Additional data to pass to the callback function.

infd_directory_iter_save_session ()

gboolean            infd_directory_iter_save_session    (InfdDirectory *directory,
                                                         InfBrowserIter *iter,
                                                         GError **error);

Attempts to store the session the node iter points to represents into the background storage.

directory :

A InfdDirectory.

iter :

A InfBrowserIter pointing to a note in directory.

error :

Location to store error information.

Returns :

TRUE if the operation succeeded, FALSE otherwise.

infd_directory_enable_chat ()

void                infd_directory_enable_chat          (InfdDirectory *directory,
                                                         gboolean enable);

If enable is TRUE, this enables the chat on the server. This allows clients subscribing to the chat via infc_browser_subscribe_chat(). If enable is FALSE the chat is disabled which means closing an existing chat session if any and no longer allowing subscription to the chat. The chat is initially disabled.

directory :

A InfdDirectory.

enable :

Whether to enable or disable the chat.

infd_directory_get_chat_session ()

InfdSessionProxy *  infd_directory_get_chat_session     (InfdDirectory *directory);

Returns a InfdSessionProxy for the chat session, if any. If the chat is enabled (see infd_directory_enable_chat()) this returns a InfdSessionProxy that can be used to join local users to the chat, or to get chat contents (by getting the InfChatBuffer from the proxy's InfChatSession). If the chat is disabled the function returns NULL.

directory :

A InfdDirectory.

Returns :

A InfdSessionProxy, or NULL if the chat is disabled.

infd_directory_create_acl_account ()

InfAclAccountId     infd_directory_create_acl_account   (InfdDirectory *directory,
                                                         const gchar *account_name,
                                                         gboolean transient,
                                                         gnutls_x509_crt_t *certificates,
                                                         guint n_certificates,
                                                         GError **error);

Creates a new account on the directory with the given account_name. If the certificates array is not empty and a clients connects with one of the certificates, the client will automatically be logged into the account.

If the transient parameter is TRUE then the account is made transient, i.e. it will not be stored to permanent storage. When the server is re-started, the account will no longer exist. If the parameter is FALSE, then the account is persistent.

This function is similar to inf_browser_create_acl_account(), but it allows more options.

directory :

A InfdDirectory.

account_name :

The name of the new account.

transient :

Whether the account should be transient or not.

certificates :

An array of certificates to be associated to the account, or NULL.

n_certificates :

The number of certificates.

error :

Location to store error information, if any, or NULL.

Returns :

The account ID of the created account, or NULL in case of error.

Property Details

The "account-storage" property

  "account-storage"          InfdAccountStorage*   : Read / Write / Construct

The account storage backend, to read available user accounts from.


The "certificate" property

  "certificate"              InfCertificateChain*  : Read / Write

The certificate chain of the server.


The "chat-session" property

  "chat-session"             InfdSessionProxy*     : Read

The server's chat session.


The "communication-manager" property

  "communication-manager"    InfCommunicationManager*  : Read / Write / Construct Only

The communication manager for the directory.


The "io" property

  "io"                       InfIo*                : Read / Write / Construct Only

IO object to watch sockets and schedule timeouts.


The "private-key" property

  "private-key"              gpointer              : Read / Write

The private key of the server with which belongs to its certificate.


The "storage" property

  "storage"                  InfdStorage*          : Read / Write / Construct

The storage backend to use.

Signal Details

The "connection-added" signal

void                user_function                      (InfdDirectory    *directory,
                                                        InfXmlConnection *connection,
                                                        gpointer          user_data)       : Run Last

This signal is emitted when a connection that is served by the InfdDirectory was added. The only way this can happen is by a call to infd_directory_add_connection(). This can be done automatically by an InfdServerPool instance, however.

directory :

The InfdDirectory emitting the signal.

connection :

The InfXmlConnection that was added.

user_data :

user data set when the signal handler was connected.

The "connection-removed" signal

void                user_function                      (InfdDirectory    *directory,
                                                        InfXmlConnection *connection,
                                                        gpointer          user_data)       : Run Last

This signal is emitted when a connection stopes being served by directory. Usually this happens only when the connection is closed.

directory :

The InfdDirectory emitting the signal.

connection :

The InfXmlConnection that was removed.

user_data :

user data set when the signal handler was connected.

See Also

InfcBrowser, InfdStorage