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

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

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