InfdDirectory: libinfinity-0.7 Reference Manual

## InfdDirectory InfdDirectory — Directory of published documents |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*InfdDirectoryForeachConnectionFunc) ()
InfdDirectory * | infd_directory_new ()
InfIo * | infd_directory_get_io ()
InfdStorage * | infd_directory_get_storage ()
InfCommunicationManager * | infd_directory_get_communication_manager ()
void | infd_directory_set_certificate ()
gboolean | infd_directory_add_plugin ()
void | infd_directory_remove_plugin ()
const InfdNotePlugin * | infd_directory_lookup_plugin ()
gboolean | infd_directory_add_connection ()
void | infd_directory_get_support_mask ()
InfAclAccountId | infd_directory_get_acl_account_for_connection ()
gboolean | infd_directory_set_acl_account_for_connection ()
void | infd_directory_foreach_connection ()
gboolean | infd_directory_iter_save_session ()
void | infd_directory_enable_chat ()
InfdSessionProxy * | infd_directory_get_chat_session ()
InfAclAccountId | infd_directory_create_acl_account ()

## 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

struct | InfdDirectory
struct | InfdDirectoryClass

## 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