InfBrowser: libinfinity-0.7 Reference Manual

## InfBrowser InfBrowser — Browsing of infinote directories |

## Stability Level

Unstable, unless otherwise indicated

## Functions

gboolean | inf_browser_get_root ()
gboolean | inf_browser_get_next ()
gboolean | inf_browser_get_prev ()
gboolean | inf_browser_get_parent ()
gboolean | inf_browser_get_child ()
gboolean | inf_browser_is_ancestor ()
InfRequest * | inf_browser_explore ()
gboolean | inf_browser_get_explored ()
gboolean | inf_browser_is_subdirectory ()
InfRequest * | inf_browser_add_note ()
InfRequest * | inf_browser_add_subdirectory ()
InfRequest * | inf_browser_remove_node ()
const gchar * | inf_browser_get_node_name ()
const gchar * | inf_browser_get_node_type ()
gchar * | inf_browser_get_path ()
InfRequest * | inf_browser_subscribe ()
InfSessionProxy * | inf_browser_get_session ()
GSList * | inf_browser_list_pending_requests ()
gboolean | inf_browser_iter_from_request ()
InfRequest * | inf_browser_get_pending_request ()
const InfAclAccount * | inf_browser_get_acl_default_account ()
const InfAclAccount * | inf_browser_get_acl_local_account ()
InfRequest * | inf_browser_query_acl_account_list ()
InfRequest * | inf_browser_lookup_acl_accounts ()
InfRequest * | inf_browser_lookup_acl_account_by_name ()
InfRequest * | inf_browser_create_acl_account ()
InfRequest * | inf_browser_remove_acl_account ()
InfRequest * | inf_browser_query_acl ()
gboolean | inf_browser_has_acl ()
const InfAclSheetSet * | inf_browser_get_acl ()
InfRequest * | inf_browser_set_acl ()
gboolean | inf_browser_check_acl ()
void | inf_browser_error ()
void | inf_browser_node_added ()
void | inf_browser_node_removed ()
void | inf_browser_subscribe_session ()
void | inf_browser_unsubscribe_session ()
void | inf_browser_begin_request ()
void | inf_browser_acl_account_added ()
void | inf_browser_acl_account_removed ()
void | inf_browser_acl_local_account_changed ()
void | inf_browser_acl_changed ()

## Properties

InfBrowserStatus | status | Read

## Signals

void | acl-account-added | Run Last
void | acl-account-removed | Run Last
void | acl-changed | Run Last
void | acl-local-account-changed | Run Last
void | begin-request | Has Details
void | error | Run Last
void | node-added | Run Last
void | node-removed | Run Last
void | subscribe-session | Run Last
void | unsubscribe-session | Run Last

## Types and Values

| InfBrowser
struct | InfBrowserInterface
enum | InfBrowserStatus

## Object Hierarchy

        GEnum
        ╰── InfBrowserStatus
        GInterface
        ╰── InfBrowser

## Prerequisites

InfBrowser requires GObject.

## Known Implementations

InfBrowser is implemented by InfcBrowser and InfdDirectory.

## Includes

    #include <libinfinity/common/inf-browser.h>

## Description

InfBrowser provides an interface for browsing an infinote directory. It can be used to navigate through the tree, add or remove nodes and subscribe to sessions.

Nodes in a directory can either contain more nodes in which case this is called a subdirectory. Leaf nodes are also called notes. There is only one root node which must be a subdirectory node.

## Functions

### inf_browser_get_root ()

    gboolean
    inf_browser_get_root (InfBrowser *browser,
                          InfBrowserIter *iter);

Sets `iter` to point to the root node of `browser` .

#### Parameters

browser | A InfBrowser. |
iter | An uninitialized InfBrowserIter. | [out]

#### Returns

`TRUE` if `iter` was set or `FALSE` if there is no root node, i.e. the browser is not open.

### inf_browser_get_next ()

    gboolean
    inf_browser_get_next (InfBrowser *browser,
                          InfBrowserIter *iter);

Sets `iter` to point to its next sibling node. If `iter` points already to the last node then `iter` is left untouched and the function returns `FALSE`.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` . | [inout]

#### Returns

`TRUE` if `iter` was moved or `FALSE` otherwise.

### inf_browser_get_prev ()

    gboolean
    inf_browser_get_prev (InfBrowser *browser,
                          InfBrowserIter *iter);

Sets `iter` to point to its previous sibling node. If `iter` points to the first node already then `iter` is left untouched and the function returns `FALSE`.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` . | [inout]

#### Returns

`TRUE` if `iter` was moved or `FALSE` otherwise.

### inf_browser_get_parent ()

    gboolean
    inf_browser_get_parent (InfBrowser *browser,
                            InfBrowserIter *iter);

Sets `iter` to point to its parent node. If `iter` is already the root node then `iter` is left untouched and the function returns `FALSE`.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` . | [inout]

#### Returns

`TRUE` if `iter` was moved or `FALSE` otherwise.

### inf_browser_get_child ()

    gboolean
    inf_browser_get_child (InfBrowser *browser,
                           InfBrowserIter *iter);

Sets `iter` to point to the first child of the subdirectory node it currently points to. If the subdirectory does not contain any children or if `iter` does not point to a subdirectory the function returns `FALSE`. This does not necessarily mean that there do not exist any children but it can also be that they have not yet been explored. Nodes can be explored with `inf_browser_explore()` and it can be checked whether a given node has been explored with `inf_browser_get_explored()`.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a subdirectory node inside `browser` . | [inout]

#### Returns

`TRUE` if `iter` was moved or `FALSE` otherwise.

### inf_browser_is_ancestor ()

    gboolean
    inf_browser_is_ancestor (InfBrowser *browser,
                             const InfBrowserIter *ancestor,
                             const InfBrowserIter *iter);

Returns whether `ancestor` is an ancestor of `iter` , i.e. either the two iterators point to the same node or `ancestor` is a parent, grand-parent, grand-grand-parent, etc. of the node `iter` points to.

#### Parameters

browser | A InfBrowser. |
ancestor | An iterator pointing to the ancestor node. |
iter | An iterator pointing to the node to be checked. |

#### Returns

Whether `ancestor` is an ancestor of `iter` .

### inf_browser_explore ()

    InfRequest *
    inf_browser_explore (InfBrowser *browser,
                         const InfBrowserIter *iter,
                         InfRequestFunc func,
                         gpointer user_data);

Requests the node `iter` points to to be explored. Initally, subdirectory nodes are not explored, that is not known what content there is. Nodes can be explored to learn about the children nodes they contain. Since exploring is a potentially lengthy process involing networking or I/O with slow devices this function returns a `InfExploreRequest` which can be used to monitor the progress of the operation and get notified when the exploration finishes. During exploration “node-added” signals are already emitted appropriately for every child explored inside `iter` .

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a subdirectory node inside `browser` . |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest, or `NULL` if `iter` points to a non-subdirectory node.

[transfer none][allow-none]

### inf_browser_get_explored ()

    gboolean
    inf_browser_get_explored (InfBrowser *browser,
                              const InfBrowserIter *iter);

Returns whether the node `iter` points to has already been explored or not.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a subdirectory node inside `browser` . |

#### Returns

`TRUE` if the node `iter` points to has been explored or `FALSE` otherwise.

### inf_browser_is_subdirectory ()

    gboolean
    inf_browser_is_subdirectory (InfBrowser *browser,
                                 const InfBrowserIter *iter);

Returns whether the node `iter` points to is a subdirectory node.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` . |

#### Returns

`TRUE` if the node `iter` points to is a subdirectory node or `FALSE` otherwise.

### inf_browser_add_note ()

    InfRequest *
    inf_browser_add_note (InfBrowser *browser,
                          const InfBrowserIter *iter,
                          const char *name,
                          const char *type,
                          const InfAclSheetSet *acl,
                          InfSession *session,
                          gboolean initial_subscribe,
                          InfRequestFunc func,
                          gpointer user_data);

Adds a new leaf node to the browser. The new node is of type `type` . If session is non-`NULL` it will be used as the initial content of the new node, otherwise the new node will start empty. In the case of non-`NULL` `session` the session must be in status `INF_SESSION_RUNNING`.

The returned request finishes as soon as the creation of the node is acknowledged. It is however not guaranteed that the content of the note has been synchronized yet. In the case of a client connected to an infinote server the content is usually not transmitted when the request finishes. If an error in the process of transmission happens then the node will be removed again.

On the client side, the progress of synchronization to the server after the request has finished can be monitored with the InfSession::synchronization-failed, InfSession::synchronization-complete and InfSession::synchronization-progress signals. Note that a single session might be synchronized to multiple servers at the same time, you will have to check the connection parameter in the signal hander to find out to which server the session is synchronized.

You can safely unref session after having called this function. If the request or the synchronization fails, the session will be discarded in that case. When the returned request finishes, you can use `infc_browser_iter_get_sync_in()` to get the session again.

If `initial_subscribe` is set, then, when the returned request finishes, you might call `inf_browser_get_session()` on the resulting InfBrowserIter. However, that function is not guaranteed to return non-`NULL` in this case since the node might have been created, but the subscription could have failed.

The initial ACL for the new node is given by `acl` . If this parameter is `NULL`, then the default ACL is used, which inherits all permissions from the parent node. In order to apply non-`NULL` ACL to the new node, the `INF_ACL_CAN_SET_ACL` permission must be granted to the local entity for the node `iter` points to.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a subdirectory node inside `browser` . |
name | The name of the node to add. |
type | The type of the node to add. |
acl | A InfAclSheetSet representing the initial ACL for this node, or `NULL`. | [allow-none]
session | A InfSession with a session of type `type` , or `NULL`. | [allow-none]
initial_subscribe | Whether to subscribe to the newly created session. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest which can be used to get notified when the request finishes.

[transfer none][allow-none]

### inf_browser_add_subdirectory ()

    InfRequest *
    inf_browser_add_subdirectory (InfBrowser *browser,
                                  const InfBrowserIter *iter,
                                  const char *name,
                                  const InfAclSheetSet *acl,
                                  InfRequestFunc func,
                                  gpointer user_data);

Adds a new subdirectory node to the browser.

The initial ACL for the new node is given by `acl` . If this parameter is `NULL`, then the default ACL is used, which inherits all permissions from the parent node. In order to apply non-`NULL` ACL to the new node, the `INF_ACL_CAN_SET_ACL` permission must be granted to the local entity for the node `iter` points to.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a subdirectory node inside `browser` . |
name | The name of the node to add. |
acl | A InfAclSheetSet representing the initial ACL for this node, or `NULL`. | [allow-none]
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest which can be used to get notified when the request finishes.

[transfer none][allow-none]

### inf_browser_remove_node ()

    InfRequest *
    inf_browser_remove_node (InfBrowser *browser,
                             const InfBrowserIter *iter,
                             InfRequestFunc func,
                             gpointer user_data);

Requests to remove the node `iter` points to. It may point to a subdirectory node in which case all its children are removed recursively as well.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` . |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest which can be used to get notified when the request finishes.

[transfer none][allow-none]

### inf_browser_get_node_name ()

    const gchar *
    inf_browser_get_node_name (InfBrowser *browser,
                               const InfBrowserIter *iter);

Returns the name of the node `iter` points to.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` . |

#### Returns

A string containing the node's name.

### inf_browser_get_node_type ()

    const gchar *
    inf_browser_get_node_type (InfBrowser *browser,
                               const InfBrowserIter *iter);

Returns the type of the node `iter` points to.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a leaf node inside `browser` . |

#### Returns

The node type as a string.

### inf_browser_get_path ()

    gchar *
    inf_browser_get_path (InfBrowser *browser,
                          const InfBrowserIter *iter);

Returns the full path to the node `iter` points to. A path always starts with a '/' and then has the name of the node and all its parents separated by '/', much like a filesystem path on Unix.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` . |

#### Returns

The path as a string. Free with `g_free()` when no longer needed.

[transfer full]

### inf_browser_subscribe ()

    InfRequest *
    inf_browser_subscribe (InfBrowser *browser,
                           const InfBrowserIter *iter,
                           InfRequestFunc func,
                           gpointer user_data);

Attempts to subscribe to the node `iter` points to, i.e. obtain a InfSession representing its content. This also allows to change the content of the node.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a leaf node inside `browser` . |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest which can be used to get notified when the request finishes.

[transfer none][allow-none]

### inf_browser_get_session ()

    InfSessionProxy *
    inf_browser_get_session (InfBrowser *browser,
                             const InfBrowserIter *iter);

Returns the session which has the content of the node `iter` points to. The session needs to be subscribed to, see `inf_browser_subscribe()`. If the session is not subscribed or the subscription request has not yet finished the function returns `NULL`.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a leaf node inside `browser` . |

#### Returns

A `InfSessionProxy` which contains the session. The proxy object can be used to join a user into the session.

[transfer none][allow-none]

### inf_browser_list_pending_requests ()

    GSList *
    inf_browser_list_pending_requests (InfBrowser *browser,
                                       const InfBrowserIter *iter,
                                       const gchar *request_type);

Returns a list of all pending requests for the node `iter` points to which match type `request_type` . A pending request is a request which has been created but has not yet finished. `request_type` can be `NULL` in which case all requests for the given node are returned. If it is non-`NULL` only requests which match the given type are included in the list of returned requests.

If `iter` is `NULL` then the function returns all pending global requests.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` , or `NULL`. | [allow-none]
request_type | The type of request to return pending requests for, or `NULL`. | [allow-none]

#### Returns

A list of InfRequests. Free with `g_slist_free()` when no longer needed.

[transfer container][element-type InfRequest]

### inf_browser_iter_from_request ()

    gboolean
    inf_browser_iter_from_request (InfBrowser *browser,
                                   InfRequest *request,
                                   InfBrowserIter *iter);

Sets `iter` to the node for which `request` was made. If that node does not exist anymore or if `request` has already finished the function returns `FALSE` and `iter` is left untouched.

#### Parameters

browser | A InfBrowser. |
request | A InfRequest which has not yet finished and which was issued by `browser` . |
iter | An uninitialized InfBrowserIter. | [out]

#### Returns

`TRUE` if `iter` was moved or `FALSE` otherwise.

### inf_browser_get_pending_request ()

    InfRequest *
    inf_browser_get_pending_request (InfBrowser *browser,
                                     const InfBrowserIter *iter,
                                     const gchar *request_type);

Returns a pending request for the node `iter` points to which matches type `request_type` . If there is no such request the function returns `NULL`. This function is a shortcut for calling `inf_browser_list_pending_requests()` and retrieving the first item from the list.

If `iter` is `NULL` the function returns a global request.

For many request types, such as "subscribe-session", "subscribe-chat", "explore-node", "query-user-list" or "query-acl" there can only be one request at a time, and therefore this function is more convenient to use than `inf_browser_list_pending_requests()`.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node inside `browser` , or `NULL`. | [allow-none]
request_type | The type of request. | [allow-none]

#### Returns

A InfRequest, or `NULL`.

[allow-none][transfer none]

### inf_browser_get_acl_default_account ()

    const InfAclAccount *
    inf_browser_get_acl_default_account (InfBrowser *browser);

Returns the default InfAclAccount representing unauthenticated users, and which is used to look up permissions if no permissions are explicitly specified in the ACL of a particular node for a particular account.

#### Parameters

browser | A InfBrowser. |

#### Returns

A InfAclAccount. The returned value is owned by the browser and must not be freed.

[transfer none]

### inf_browser_get_acl_local_account ()

    const InfAclAccount *
    inf_browser_get_acl_local_account (InfBrowser *browser);

Returns the InfAclAccount representing the local host. This can be used to check whether the local account is allowed to perform certain operations in the browser. The function can also return `NULL`, in which case all operations are allowed, because the browser represents a local infinote directory.

#### Parameters

browser | A InfBrowser. |

#### Returns

A InfAclAccount, or `NULL`. The returned value is owned by the browser and must not be freed.

[transfer none][allow-none]

### inf_browser_query_acl_account_list ()

    InfRequest *
    inf_browser_query_acl_account_list (InfBrowser *browser,
                                        InfRequestFunc func,
                                        gpointer user_data);

Queries the list of accounts in `browser` . When this call has finished, a list of accounts is available, and also a flag whether the browser supports notification of accounts. If it does, then the “acl-account-added” and “acl-account-removed” signals are emitted when the account list changes, and the next time this function is called, it might be available to serve the account list from the cache without blocking.

It can also be that the browser does not support listing of accounts at all. In this case, the request will fail with an error code of `INF_DIRECTORY_ERROR_OPERATION_UNSUPPORTED`.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest that can be used to be notified when the request finishes, or `NULL`.

[transfer none][allow-none]

### inf_browser_lookup_acl_accounts ()

    InfRequest *
    inf_browser_lookup_acl_accounts (InfBrowser *browser,
                                     const InfAclAccountId *ids,
                                     guint n_ids,
                                     InfRequestFunc func,
                                     gpointer user_data);

Looks up the accounts with the given IDs. If the account list has been queried with `inf_browser_query_acl_account_list()` before, then it is likely that this function returns instantly, otherwise an asynchronous operation might be started.

The request result contains an array of InfAclAccount objects for the given account IDs, which contain the account names as well. If one account ID does not belong to an actual account, the InfAclAccount.name field will be `NULL`.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
ids | An array of account IDs to look up. | [array length=n_ids]
n_ids | The number of elements in the array. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest that can be used to be notified when the request finishes, or `NULL`.

[transfer none][allow-none]

### inf_browser_lookup_acl_account_by_name ()

    InfRequest *
    inf_browser_lookup_acl_account_by_name
                                   (InfBrowser *browser,
                                    const gchar *name,
                                    InfRequestFunc func,
                                    gpointer user_data);

Looks up the account(s) with the given name. While in principal, there can be many accounts with the same name, in practise user names are often unique.

The request result contains an array of InfAclAccount objects, all with the same name. If there is only one entry with ID set to 0, there are no accounts with the given name.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
name | The name of the user account to look up. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest that can be used to be notified when the request finishes, or `NULL`.

[allow-none][transfer none]

### inf_browser_create_acl_account ()

    InfRequest *
    inf_browser_create_acl_account (InfBrowser *browser,
                                    gnutls_x509_crq_t crq,
                                    InfRequestFunc func,
                                    gpointer user_data);

Requests creation of a new account. If the request succeeds, `crq` will be used by the server to create a certificate which is sent back to the client and is associated to the newly created account.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
crq | A certificate request. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest that can be used to get notified when the request finishes or fails.

[transfer none][allow-none]

### inf_browser_remove_acl_account ()

    InfRequest *
    inf_browser_remove_acl_account (InfBrowser *browser,
                                    InfAclAccountId account,
                                    InfRequestFunc func,
                                    gpointer user_data);

Requests deletion of the given account.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
account | The ID of the account to remove. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest that can be used to get notified when the request finishes or fails.

[transfer none][allow-none]

### inf_browser_query_acl ()

    InfRequest *
    inf_browser_query_acl (InfBrowser *browser,
                           const InfBrowserIter *iter,
                           InfRequestFunc func,
                           gpointer user_data);

Queries the ACLs for all users of the node `iter` points to. When the request has finished, `inf_browser_get_acl()` can be used to retrieve the ACLs.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
iter | An iterator pointing to a node for which to query the ACLs. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest which can be used to be notified when the request finishes.

[transfer none][allow-none]

### inf_browser_has_acl ()

    gboolean
    inf_browser_has_acl (InfBrowser *browser,
                         const InfBrowserIter *iter,
                         InfAclAccountId account);

This function returns whether the ACL sheet for the given account is available or not. If the function returns `FALSE` then `inf_browser_query_acl()` can be called in order to retrieve the full ACL. If `account` is 0, the function checks whether the full ACL is available, i.e. the ACL sheets for all accounts. Usually the ACL sheets for the default account and the local account are always available.

#### Parameters

browser | A InfBrowser. |
iter | An iterator pointing to a node for which to check full ACL availability. |
account | The account to check ACL availability for, or 0. |

#### Returns

`TRUE` when the ACL sheet for `account` is available or `FALSE` otherwise.

### inf_browser_get_acl ()

    const InfAclSheetSet *
    inf_browser_get_acl (InfBrowser *browser,
                         const InfBrowserIter *iter);

Retrieves the ACL for the node `iter` points to. This function can also be called if the ACL has not been queried before using `inf_browser_query_acl()`. In that case, the returned sheet set will only contain sheets for the default user and the local user. The function can return `NULL` which is equivalent to an empty sheet set, i.e. no ACL.

When the full ACL has been successfully queried with `inf_browser_query_acl()`, the full ACL is returned by this function. The function `inf_browser_has_acl()` can be used to check whether this function will return the full ACL or only the sheets for the default and local users.

#### Parameters

browser | A InfBrowser. |
iter | An iterator pointing to a node for which to retrieve ACLs. |

#### Returns

A InfAclSheetSet containing the requested ACL, or `NULL`. The returned value is owned by the InfBrowser and should not be freed.

### inf_browser_set_acl ()

    InfRequest *
    inf_browser_set_acl (InfBrowser *browser,
                         const InfBrowserIter *iter,
                         const InfAclSheetSet *sheet_set,
                         InfRequestFunc func,
                         gpointer user_data);

Changes the ACLs for the node `iter` points to. Existing sheets that are not in `sheet_set` are left untouched. This operation is only allowed when the ACL for the node `iter` points to has been retrieved already with `inf_browser_query_acl()`. Use `inf_browser_has_acl()` to check whether this function can be called or whether the ACL needs to be queried first.

The request might either finish during the call to this function, in which case `func` will be called and `NULL` being returned. If the request does not finish within the function call, a InfRequest object is returned, where `func` has been installed for the “finished” signal, so that it is called as soon as the request finishes.

#### Parameters

browser | A InfBrowser. |
iter | An iterator pointing to the node for which to change ACLs. |
sheet_set | An InfAclSheetSet with the sheets to update. |
func | The function to be called when the request finishes, or `NULL`. | [scope async]
user_data | Additional data to pass to `func` . |

#### Returns

A InfRequest which can be used to be notified when the request finishes.

[transfer none][allow-none]

### inf_browser_check_acl ()

    gboolean
    inf_browser_check_acl (InfBrowser *browser,
                           const InfBrowserIter *iter,
                           InfAclAccountId account,
                           const InfAclMask *check_mask,
                           InfAclMask *out_mask);

Checks whether the given account has permissions to perform the operations specified by `mask` on the node `iter` points to. The `mask` parameter should have all permissions enabled that are to be checked. The function will then write those permissions that are actually granted to the mask specified by the `out_mask` parameter.

The function returns `TRUE` if all permissions asked for are granted, i.e. when *`out_mask` equals *`mask` after the function call. The `out_mask` parameter is allowed to be `NULL` which is useful if only the return value is of interest.

In order for this function to work, the ACL sheet for `account` has to be available for the node `iter` points to and all of its parent nodes. If `account` is not the default or the local account, these need to be queried before using `inf_browser_query_acl()`.

If account is 0, it is assumed that local access to the directory is available and the function always returns `TRUE`.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to a node in a browser. |
account | The ID of the account whose permission to check, or `NULL`. |
check_mask | A bitmask of InfAclSettings with permissions to check. |
out_mask | Output parameter with the granted permissions, or `NULL`. | [out]

#### Returns

`TRUE` if all checked permissions are granted, or `FALSE` otherwise.

### inf_browser_error ()

    void
    inf_browser_error (InfBrowser *browser,
                       const GError *error);

This function emits the “error” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
error | A GError explaining what went wronig. |

### inf_browser_node_added ()

    void
    inf_browser_node_added (InfBrowser *browser,
                            const InfBrowserIter *iter,
                            InfRequest *request);

This function emits the “node-added” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to the newly added node. |
request | The InfRequest that was used to add or explore the node, or `NULL`. |

### inf_browser_node_removed ()

    void
    inf_browser_node_removed (InfBrowser *browser,
                              const InfBrowserIter *iter,
                              InfRequest *request);

This function emits the “node-removed” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to the node to be removed. |
request | The InfRequest that was used to delete the node, or `NULL`. |

### inf_browser_subscribe_session ()

    void
    inf_browser_subscribe_session (InfBrowser *browser,
                                   const InfBrowserIter *iter,
                                   InfSessionProxy *proxy,
                                   InfRequest *request);

This function emits the “subscribe-session” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to the node to whose session a subscription was made, or `NULL`. |
proxy | A session proxy for the newly subscribed session. |
request | The InfRequest that was used to initiate the subscription, or `NULL`. |

### inf_browser_unsubscribe_session ()

    void
    inf_browser_unsubscribe_session (InfBrowser *browser,
                                     const InfBrowserIter *iter,
                                     InfSessionProxy *proxy,
                                     InfRequest *request);

This function emits the “unsubscribe-session” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
iter | A InfBrowserIter pointing to the node to whose session the subscription was removed, or `NULL`. |
proxy | A session proxy for the unsubscribed session. |
request | The InfRequest due to which the session was unsubscribed, or `NULL`. |

### inf_browser_begin_request ()

    void
    inf_browser_begin_request (InfBrowser *browser,
                               const InfBrowserIter *iter,
                               InfRequest *request);

This function emits the “begin_request” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
iter | A infBrowserIter pointing to the node for which a request was made, or `NULL`. |
request | The request which was made. |

### inf_browser_acl_account_added ()

    void
    inf_browser_acl_account_added (InfBrowser *browser,
                                   const InfAclAccount *account,
                                   InfRequest *request);

This function emits the “acl-account-added” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
account | The new InfAclAccount. |
request | The InfRequest that was used to add the account, or `NULL`. |

### inf_browser_acl_account_removed ()

    void
    inf_browser_acl_account_removed (InfBrowser *browser,
                                     const InfAclAccount *account,
                                     InfRequest *request);

This function emits the “acl-account-removed” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
account | The removed InfAclAccount. |
request | The InfRequest that was used to remove the account, or `NULL`. |

### inf_browser_acl_local_account_changed ()

    void
    inf_browser_acl_local_account_changed (InfBrowser *browser,
                                           const InfAclAccount *account,
                                           InfRequest *request);

This function emits the “acl-local-account-changed” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
account | The new local InfAclAccount. |
request | The InfRequest that triggered the account change, or `NULL`. |

### inf_browser_acl_changed ()

    void
    inf_browser_acl_changed (InfBrowser *browser,
                             const InfBrowserIter *iter,
                             const InfAclSheetSet *sheet_set,
                             InfRequest *request);

This function emits the “acl-changed” signal on `browser` . It is meant to be used by interface implementations only.

#### Parameters

browser | A InfBrowser. |
iter | An iterator pointing to the node for which the ACL has changed. |
sheet_set | A InfAclSheetSet containing the changed ACL sheets. |
request | The InfRequest that was used to change the ACL, or `NULL`. |

## Types and Values

### InfBrowser

    typedef struct _InfBrowser InfBrowser;

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

### struct InfBrowserInterface

    struct InfBrowserInterface {
      void (*error)(InfBrowser* browser,
                    const GError* error);

      void (*node_added)(InfBrowser* browser,
                         const InfBrowserIter* iter,
                         InfRequest* request);

      void (*node_removed)(InfBrowser* browser,
                           const InfBrowserIter* iter,
                           InfRequest* request);

      void (*subscribe_session)(InfBrowser* browser,
                                const InfBrowserIter* iter,
                                InfSessionProxy* proxy,
                                InfRequest* request);

      void (*unsubscribe_session)(InfBrowser* browser,
                                  const InfBrowserIter* iter,
                                  InfSessionProxy* proxy,
                                  InfRequest* request);

      void (*begin_request)(InfBrowser* browser,
                            const InfBrowserIter* iter,
                            InfRequest* request);

      void (*acl_account_added)(InfBrowser* browser,
                                const InfAclAccount* account,
                                InfRequest* request);

      void (*acl_account_removed)(InfBrowser* browser,
                                  const InfAclAccount* account,
                                  InfRequest* request);

      void (*acl_local_account_changed)(InfBrowser* browser,
                                        const InfAclAccount* account,
                                        InfRequest* request);

      void (*acl_changed)(InfBrowser* browser,
                          const InfBrowserIter* iter,
                          const InfAclSheetSet* sheet_set,
                          InfRequest* request);

      /* Virtual functions */

      gboolean (*get_root)(InfBrowser* browser,
                           InfBrowserIter* iter);
      gboolean (*get_next)(InfBrowser* browser,
                           InfBrowserIter* iter);
      gboolean (*get_prev)(InfBrowser* browser,
                           InfBrowserIter* iter);
      gboolean (*get_parent)(InfBrowser* browser,
                             InfBrowserIter* iter);
      gboolean (*get_child)(InfBrowser* browser,
                            InfBrowserIter* iter);
      InfRequest* (*explore)(InfBrowser* browser,
                             const InfBrowserIter* iter,
                             InfRequestFunc func,
                             gpointer user_data);
      gboolean (*get_explored)(InfBrowser* browser,
                               const InfBrowserIter* iter);
      gboolean (*is_subdirectory)(InfBrowser* browser,
                                  const InfBrowserIter* iter);

      InfRequest* (*add_note)(InfBrowser* browser,
                              const InfBrowserIter* iter,
                              const char* name,
                              const char* type,
                              const InfAclSheetSet* acl,
                              InfSession* session,
                              gboolean initial_subscribe,
                              InfRequestFunc func,
                              gpointer user_data);
      InfRequest* (*add_subdirectory)(InfBrowser* browser,
                                      const InfBrowserIter* iter,
                                      const char* name,
                                      const InfAclSheetSet* acl,
                                      InfRequestFunc func,
                                      gpointer user_data);
      InfRequest* (*remove_node)(InfBrowser* browser,
                                 const InfBrowserIter* iter,
                                 InfRequestFunc func,
                                 gpointer user_data);
      const gchar* (*get_node_name)(InfBrowser* browser,
                                    const InfBrowserIter* iter);
      const gchar* (*get_node_type)(InfBrowser* browser,
                                    const InfBrowserIter* iter);

      InfRequest* (*subscribe)(InfBrowser* browser,
                               const InfBrowserIter* iter,
                               InfRequestFunc func,
                               gpointer user_data);
      InfSessionProxy* (*get_session)(InfBrowser* browser,
                                      const InfBrowserIter* iter);

      GSList* (*list_pending_requests)(InfBrowser* browser,
                                       const InfBrowserIter* iter,
                                       const gchar* request_type);
      gboolean (*iter_from_request)(InfBrowser* browser,
                                    InfRequest* request,
                                    InfBrowserIter* iter);

      const InfAclAccount* (*get_acl_default_account)(InfBrowser* browser);

      const InfAclAccount* (*get_acl_local_account)(InfBrowser* browser);

      InfRequest* (*query_acl_account_list)(InfBrowser* browser,
                                            InfRequestFunc func,
                                            gpointer user_data);

      InfRequest* (*lookup_acl_accounts)(InfBrowser* browser,
                                         const InfAclAccountId* ids,
                                         guint n_ids,
                                         InfRequestFunc func,
                                         gpointer user_data);

      InfRequest* (*lookup_acl_account_by_name)(InfBrowser* browser,
                                                const gchar* name,
                                                InfRequestFunc func,
                                                gpointer user_data);

      InfRequest* (*create_acl_account)(InfBrowser* browser,
                                        gnutls_x509_crq_t crq,
                                        InfRequestFunc func,
                                        gpointer user_data);

      InfRequest* (*remove_acl_account)(InfBrowser* browser,
                                        InfAclAccountId account,
                                        InfRequestFunc func,
                                        gpointer user_data);

      InfRequest* (*query_acl)(InfBrowser* browser,
                               const InfBrowserIter* iter,
                               InfRequestFunc func,
                               gpointer user_data);

      gboolean (*has_acl)(InfBrowser* browser,
                          const InfBrowserIter* iter,
                          InfAclAccountId account);

      const InfAclSheetSet* (*get_acl)(InfBrowser* browser,
                                       const InfBrowserIter* iter);

      InfRequest* (*set_acl)(InfBrowser* browser,
                             const InfBrowserIter* iter,
                             const InfAclSheetSet* sheet_set,
                             InfRequestFunc func,
                             gpointer user_data);
    };

Signals and virtual functions for the InfBrowser interface.

#### Members

`error` () | Default signal handler for the “error” signal. |
`node_added` () | Default signal handler for the “node-added” signal. |
`node_removed` () | Default signal handler for the “node-removed” signal. |
`subscribe_session` () | Default signal handler for the “subscribe-session” signal. |
`unsubscribe_session` () | Default signal handler for the “unsubscribe-session” signal. |
`begin_request` () | Default signal handler for the “begin-request” signal. |
`acl_account_added` () | Default signal handler for the “acl-account-added” signal. |
`acl_account_removed` () | Default signal handler for the “acl-account-removed” signal. |
`acl_local_account_changed` () | Default signal handler for the “acl-local-account-changed” signal. |
`acl_changed` () | Default signal handler for the “acl-changed” signal. |
`get_root` () | Virtual function to return the root node of the browser. |
`get_next` () | Virtual function to return the next sibling in a browser. |
`get_prev` () | Virtual function to return the previous sibling in a browser. |
`get_parent` () | Virtual function to return the parent node in a browser. |
`get_child` () | Virtual function to return the first child node in a browser. |
`explore` () | Virtual function to start exploring a node. |
`get_explored` () | Virtual function to query whether a node is explored already. |
`is_subdirectory` () | Virtual function to find out whether a node is a subdirectory node. |
`add_note` () | Virtual function to add a new leaf node to the directory. |
`add_subdirectory` () | Virtual function to a new subdirectory node to the directory. |
`remove_node` () | Virtual function to remove a node from the directory. |
`get_node_name` () | Virtual function to return the name of a node in a browser. |
`get_node_type` () | Virtual function to return the type of a node in a browser. |
`subscribe` () | Virtual function to subscribe to a session of a node in a browser. |
`get_session` () | Virtual function to return a session for a node in a browser. |
`list_pending_requests` () | Virtual function to return a list of all pending requests for a node in a browser. |
`iter_from_request` () | Virtual function to return an iterator pointing to the node a given request was made for. |
`get_acl_default_account` () | Virtual function to return the "default" ACL account. |
`get_acl_local_account` () | Virtual function to return the ACL account of the local host. |
`query_acl_account_list` () | Virtual function for querying the list of accounts. |
`lookup_acl_accounts` () | Virtual function to find accounts by their ID. |
`lookup_acl_account_by_name` () | Virtual function to find an account by its name. |
`create_acl_account` () | Virtual function to create a new account. |
`remove_acl_account` () | Virtual function to remove an account. |
`query_acl` () | Virtual function for querying the ACL for a node for all other users. |
`has_acl` () | Virtual function for checking whether the ACL has been queried or is otherwise available. |
`get_acl` () | Virtual function for obtaining the full ACL for a node. |
`set_acl` () | Virtual function for changing the ACL for one node. |

### enum InfBrowserStatus

This enumeration contains possible status values for InfBrowser. Several operations, such as exploring a node or subscribing to a session can only be performed when the browser is open (for example, connected to a remote infinote server).

#### Members

INF_BROWSER_CLOSED | The browser is closed and cannot be used currently. |
INF_BROWSER_OPENING | The browser is currently being opened but cannot be used yet. |
INF_BROWSER_OPEN | The browser is open and can be used to browse the directory. |

## Property Details

### The `“status”` property

      “status”                   InfBrowserStatus

The connectivity status of the browser.

Owner: InfBrowser

Flags: Read

Default value: INF_BROWSER_CLOSED

## Signal Details

### The `“acl-account-added”` signal

    void
    user_function (InfBrowser    *browser,
                   InfAclAccount *account,
                   InfRequest    *request,
                   gpointer       user_data)

This signal is emitted whenever a new account is added to the browser, and the browser supports account list notification.

#### Parameters

browser | The InfBrowser object emitting the signal. |
account | The new InfAclAccount. |
request | The request which lead to the newly added account, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“acl-account-removed”` signal

    void
    user_function (InfBrowser    *browser,
                   InfAclAccount *account,
                   InfRequest    *request,
                   gpointer       user_data)

This signal is emitted whenever an account is removed from the browser, and the browser supports account list notification.

#### Parameters

browser | The InfBrowser object emitting the signal. |
account | The removed InfAclAccount. |
request | The request which lead to the removal of the account, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“acl-changed”` signal

    void
    user_function (InfBrowser     *browser,
                   InfBrowserIter *iter,
                   InfAclSheetSet *sheet_set,
                   InfRequest     *request,
                   gpointer        user_data)

This signal is emitted whenever an ACL for the node `iter` points to are changed. This signal is emitted whenever the ACL change for the local user, the default user, or for a node that all ACLs have been queried with `inf_browser_query_acl()`.

The `sheet_set` parameter contains only the ACL sheets that have changed. In order to get the new full sheet set, call `inf_browser_get_acl()`.

#### Parameters

browser | The InfBrowser object emitting the signal. |
iter | An iterator pointing to the node for which the ACL has changed. |
sheet_set | A InfAclSheetSet containing the changed ACL sheets. |
request | The request which lead to the ACL being changed, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“acl-local-account-changed”` signal

    void
    user_function (InfBrowser    *browser,
                   InfAclAccount *account,
                   InfRequest    *request,
                   gpointer       user_data)

This signal is emitted whenever the account into which the local host is logged into changes. This can happen for example on a delayed login, or when the current account is deleted from the server in which case the host is demoted to the default account.

#### Parameters

browser | The InfBrowser object emitting the signal. |
account | The new local InfAclAccount. |
request | The request which triggered the account change, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“begin-request”` signal

    void
    user_function (InfBrowser     *browser,
                   InfBrowserIter *iter,
                   InfRequest     *request,
                   gpointer        user_data)

This signal is emitted whenever a request is made with the browser. The signal is detailed with the request type, so that it is possible to connect to e.g. "begin-request::add-subdirectory" to only get notified about subdirectory creation requests.

If `iter` is `NULL` the request is a global request and not attached to a particular node.

#### Parameters

browser | The InfBrowser object emitting the signal. |
iter | An iterator pointing to the node for which a request is made, or `NULL`. |
request | The request being made. |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

### The `“error”` signal

    void
    user_function (InfBrowser *browser,
                   GError     *error,
                   gpointer    user_data)

This signal is emitted whenever there was an asynchronous error with the browser itself which was not the result of a particular user request. The error may or may not be fatal. If it is fatal the browser will also be closed which can be checked with the status property.

#### Parameters

browser | The InfBrowser object emitting the signal. |
error | A GError describing what went wrong. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“node-added”` signal

    void
    user_function (InfBrowser     *browser,
                   InfBrowserIter *iter,
                   InfRequest     *request,
                   gpointer        user_data)

This signal is emitted when a node is added to the browser.

#### Parameters

browser | The InfBrowser object emitting the signal. |
iter | An iterator pointing to the newly added node. |
request | The request that lead to the node being added, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“node-removed”` signal

    void
    user_function (InfBrowser     *browser,
                   InfBrowserIter *iter,
                   InfRequest     *request,
                   gpointer        user_data)

This signal is emitted just before a node is being removed from the browser. The iterator is still valid and can be used to access the node which will be removed.

#### Parameters

browser | The InfBrowser object emitting the signal. |
iter | An iterator pointing to the node being removed. |
request | The request that lead to the node being removed, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“subscribe-session”` signal

    void
    user_function (InfBrowser      *browser,
                   InfBrowserIter  *iter,
                   InfSessionProxy *session,
                   InfRequest      *request,
                   gpointer         user_data)

This signal is emitted whenever the browser is subscribed to a session. This can happen as a result of a `inf_browser_subscribe()` or `inf_browser_add_note()` call, but it is also possible that a subscription is initiated without user interaction.

If `iter` is `NULL` the session was a global session and not attached to a particular node.

#### Parameters

browser | The InfBrowser object emitting the signal. |
iter | An iterator pointing to the node to which a subscription. was made, or `NULL`. |
session | The subscribed session. |
request | The request that lead to the subscription, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“unsubscribe-session”` signal

    void
    user_function (InfBrowser      *browser,
                   InfBrowserIter  *iter,
                   InfSessionProxy *session,
                   InfRequest      *request,
                   gpointer         user_data)

This signal is emitted whenever a session is detached from a browser node. This can happen when a subscribed session is closed, or, in the case of a server, if the session is idle for a long time it is stored on disk and removed from memory.

Note that this signal does not mean that the corresponding session can no longer be used. It only means that it is no longer associated to a browser node, for example also when the browser node is deleted. The session might still be intact, though, and can continue even when it is detached from the browser.

In order to find out whether the local host was unsubscribed from a session and the connection to the other session participants has been lost, the “subscription-group” property should be monitored, and if that property changes and `inf_session_get_subscription_group()` returns `NULL` afterwards, it means the session is no longer connected.

If `iter` is `NULL` the session was a global session and not attached to a particular node.

#### Parameters

browser | The InfBrowser object emitting the signal. |
iter | An iterator pointing to the node from which a subscription. was removed, or `NULL`. |
session | The session to which the subscription was removed. |
request | The request that lead to the unsubscription, or `NULL`. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

InfBrowserIter