InfdDirectory

InfdDirectory — Directory of published documents

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

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

Signals

void connection-added Run Last
void connection-removed Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── InfdDirectory

Implemented Interfaces

InfdDirectory implements InfCommunicationObject and InfBrowser.

Includes

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

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.

Functions

InfdDirectoryForeachConnectionFunc ()

void
(*InfdDirectoryForeachConnectionFunc) (InfXmlConnection *conn,
                                       gpointer user_data);

This is the signature of the callback function passed to infd_directory_foreach_connection().

Parameters

conn

The connection corresponding to the current iteration.

 

user_data

Additional data passed to the call to infd_directory_foreach_connection().

 

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.

[constructor]

Parameters

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.

[transfer full]


infd_directory_get_io ()

InfIo *
infd_directory_get_io (InfdDirectory *directory);

Returns the IO object in use by the directory.

Parameters

directory

A InfdDirectory.

 

Returns

A InfIo.

[transfer none]


infd_directory_get_storage ()

InfdStorage *
infd_directory_get_storage (InfdDirectory *directory);

Returns the storage backend in use by the directory.

Parameters

directory

A InfdDirectory:

 

Returns

An InfdStorage.

[transfer none][allow-none]


infd_directory_get_communication_manager ()

InfCommunicationManager *
infd_directory_get_communication_manager
                               (InfdDirectory *directory);

Returns the connection manager of the directory.

Parameters

directory

A InfdDirectory.

 

Returns

An InfCommunicationManager.

[transfer none]


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.

Parameters

directory

A InfdDirectory.

 

key

The private key of the directory.

 

cert

The certificate chain of the directory.

[transfer none]

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).

Parameters

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.

Parameters

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.

Parameters

directory

A InfdDirectory.

 

note_type

A note type for which to lookup the plugin.

 

Returns

A InfdNotePlugin, or NULL.

[transfer none][allow-none]


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.

Parameters

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.

Parameters

directory

A InfdDirectory.

 

mask

A pointer to a InfAclMask that will be filled.

[out]

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.

Parameters

directory

A InfdDirectory.

 

connection

A connection added to directory .

 

Returns

A InfAclAccountId.

[transfer full]


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.

Parameters

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.

Parameters

directory

A InfdDirectory.

 

func

The function to call for each connection in directory .

[scope call]

user_data

Additional data to pass to the callback function.

 

infd_directory_iter_save_session ()

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

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

Parameters

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.

Parameters

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.

Parameters

directory

A InfdDirectory.

 

Returns

A InfdSessionProxy, or NULL if the chat is disabled.

[transfer none][allow-none]


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.

Parameters

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.

[array length=n_certificates][allow-none]

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 0 in case of error.

[transfer full]

Types and Values

struct InfdDirectory

struct InfdDirectory;

InfdDirectory is an opaque data type. You should only access it via the public API functions.


struct InfdDirectoryClass

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

Default signal handlers for InfdDirectory.

Members

connection_added ()

Default signal handler for the “connection-added” signal.

 

connection_removed ()

Default signal handler for the “connection-removed” signal.

 

Property Details

The “account-storage” property

  “account-storage”          InfdAccountStorage *

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

Owner: InfdDirectory

Flags: Read / Write / Construct


The “certificate” property

  “certificate”              InfCertificateChain *

The certificate chain of the server.

Owner: InfdDirectory

Flags: Read / Write


The “chat-session” property

  “chat-session”             InfdSessionProxy *

The server's chat session.

Owner: InfdDirectory

Flags: Read


The “communication-manager” property

  “communication-manager”    InfCommunicationManager *

The communication manager for the directory.

Owner: InfdDirectory

Flags: Read / Write / Construct Only


The “io” property

  “io”                       InfIo *

IO object to watch sockets and schedule timeouts.

Owner: InfdDirectory

Flags: Read / Write / Construct Only


The “private-key” property

  “private-key”              gpointer

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

Owner: InfdDirectory

Flags: Read / Write


The “storage” property

  “storage”                  InfdStorage *

The storage backend to use.

Owner: InfdDirectory

Flags: Read / Write / Construct

Signal Details

The “connection-added” signal

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

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.

Parameters

directory

The InfdDirectory emitting the signal.

 

connection

The InfXmlConnection that was added.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “connection-removed” signal

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

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

Parameters

directory

The InfdDirectory emitting the signal.

 

connection

The InfXmlConnection that was removed.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

InfcBrowser, InfdStorage