## InfcBrowser InfcBrowser — Browse remote directories |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/client/infc-browser.h>

    enum                InfcBrowserStatus;
                        InfcBrowser;
    struct              InfcBrowserClass;
    InfcBrowser *       infc_browser_new                    (InfIo *io,
                                                             InfCommunicationManager *comm_manager,
                                                             InfXmlConnection *connection);
    InfCommunicationManager * infc_browser_get_communication_manager
                                                            (InfcBrowser *browser);
    InfXmlConnection *  infc_browser_get_connection         (InfcBrowser *browser);
    InfcBrowserStatus   infc_browser_get_status             (InfcBrowser *browser);
    gboolean            infc_browser_add_plugin             (InfcBrowser *browser,
                                                             const InfcNotePlugin *plugin);
    const InfcNotePlugin * infc_browser_lookup_plugin       (InfcBrowser *browser,
                                                             const gchar *note_type);
    void                infc_browser_iter_get_root          (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);
    gboolean            infc_browser_iter_get_next          (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);
    gboolean            infc_browser_iter_get_prev          (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);
    gboolean            infc_browser_iter_get_parent        (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);
    gboolean            infc_browser_iter_get_explored      (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    gboolean            infc_browser_iter_get_child         (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);
    InfcExploreRequest * infc_browser_iter_explore          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    const gchar *       infc_browser_iter_get_name          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    gchar *             infc_browser_iter_get_path          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    gboolean            infc_browser_iter_is_subdirectory   (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcNodeRequest *   infc_browser_add_subdirectory       (InfcBrowser *browser,
                                                             const InfcBrowserIter *parent,
                                                             const gchar *name);
    InfcNodeRequest *   infc_browser_add_note               (InfcBrowser *browser,
                                                             const InfcBrowserIter *parent,
                                                             const gchar *name,
                                                             const InfcNotePlugin *plugin,
                                                             gboolean initial_subscribe);
    InfcNodeRequest *   infc_browser_add_note_with_content  (InfcBrowser *browser,
                                                             const InfcBrowserIter *parent,
                                                             const gchar *name,
                                                             const InfcNotePlugin *plugin,
                                                             InfSession *session,
                                                             gboolean initial_subscribe);
    InfcNodeRequest *   infc_browser_remove_node            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    const gchar *       infc_browser_iter_get_note_type     (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    const InfcNotePlugin * infc_browser_iter_get_plugin     (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcNodeRequest *   infc_browser_iter_subscribe_session (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcNodeRequest *   infc_browser_iter_save_session      (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcSessionProxy *  infc_browser_iter_get_session       (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcSessionProxy *  infc_browser_iter_get_sync_in       (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcNodeRequest *   infc_browser_iter_get_subscribe_request
                                                            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcExploreRequest * infc_browser_iter_get_explore_request
                                                            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    GSList *            infc_browser_iter_get_sync_in_requests
                                                            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    gboolean            infc_browser_iter_from_node_request (InfcBrowser *browser,
                                                             InfcNodeRequest *request,
                                                             InfcBrowserIter *iter);
    gboolean            infc_browser_iter_from_explore_request
                                                            (InfcBrowser *browser,
                                                             InfcExploreRequest *request,
                                                             InfcBrowserIter *iter);
    gboolean            infc_browser_iter_is_valid          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);
    InfcNodeRequest *   infc_browser_subscribe_chat         (InfcBrowser *browser);
    InfcNodeRequest *   infc_browser_get_subscribe_chat_request
                                                            (InfcBrowser *browser);
    InfcSessionProxy *  infc_browser_get_chat_session       (InfcBrowser *browser);

## Object Hierarchy

      GEnum
       +----InfcBrowserStatus

      GObject
       +----InfcBrowser

## Implemented Interfaces

InfcBrowser implements InfCommunicationObject.

## Properties

      "chat-session"             InfcSessionProxy*     : Read
      "communication-manager"    InfCommunicationManager*  : Read / Write / Construct Only
      "connection"               InfXmlConnection*     : Read / Write / Construct Only
      "io"                       InfIo*                : Read / Write / Construct Only
      "status"                   InfcBrowserStatus     : Read

## Signals

      "begin-explore"                                  : Run Last
      "begin-subscribe"                                : Run Last
      "error"                                          : Run Last
      "node-added"                                     : Run Last
      "node-removed"                                   : Run Last
      "subscribe-session"                              : Run Last

## Description

The InfcBrowser is used to browse a remote directory and can be used to subscribe to sessions.

## Details

### enum InfcBrowserStatus

    typedef enum {
      INFC_BROWSER_DISCONNECTED,
      INFC_BROWSER_CONNECTING,
      INFC_BROWSER_CONNECTED
    } InfcBrowserStatus;

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

`INFC_BROWSER_DISCONNECTED` | The browser is currently not connected to a server.
`INFC_BROWSER_CONNECTING` | The browser is currently establishing a connection to a remote server, but the connection is not yet fully established.
`INFC_BROWSER_CONNECTED` | The browser is connected to a remote server.

### InfcBrowser

    typedef struct _InfcBrowser InfcBrowser;

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

### struct InfcBrowserClass

    struct InfcBrowserClass {
      void (*error)(InfcBrowser* browser,
                    const GError* error);

      void (*node_added)(InfcBrowser* browser,
                         InfcBrowserIter* iter);

      void (*node_removed)(InfcBrowser* browser,
                           InfcBrowserIter* iter);

      void (*subscribe_session)(InfcBrowser* browser,
                                InfcBrowserIter* iter,
                                InfcSessionProxy* proxy);

      void (*begin_explore)(InfcBrowser* browser,
                            InfcBrowserIter* iter,
                            InfcExploreRequest* request);

      void (*begin_subscribe)(InfcBrowser* browser,
                              InfcBrowserIter* iter,
                              InfcNodeRequest* request);
    };

Signals for the InfcBrowser class.

`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.
`begin_explore` () | Default signal handler for the "begin_explore" signal.
`begin_subscribe` () | Default signal handler for the "begin_subscribe" signal.

### infc_browser_new ()

    InfcBrowser *       infc_browser_new                    (InfIo *io,
                                                             InfCommunicationManager *comm_manager,
                                                             InfXmlConnection *connection);

Creates a new InfcBrowser.

`io` : | A InfIo object used to schedule timeouts.
`comm_manager` : | A InfCommunicationManager to register the server connection and which forwards incoming data to the browser or running sessions.
`connection` : | Connection to the server.
Returns : | A new InfcBrowser.

### infc_browser_get_communication_manager ()

    InfCommunicationManager * infc_browser_get_communication_manager
                                                            (InfcBrowser *browser);

Returns the communication manager of this browser.

`browser` : | A InfcBrowser.
Returns : | A InfCommunicationManager.

### infc_browser_get_connection ()

    InfXmlConnection *  infc_browser_get_connection         (InfcBrowser *browser);

Returns the connection to the server.

`browser` : | A InfcBrowser.
Returns : | A InfXmlConnection.

### infc_browser_get_status ()

    InfcBrowserStatus   infc_browser_get_status             (InfcBrowser *browser);

Returns the browser's status. Note that the browser status can be `INFC_BROWSER_DISCONNECTED` even if browser's connection is still open. This can happen if a fatal error on the browser layer happens, for example when it does not understand the server's messages.

`browser` : | A InfcBrowser.
Returns : | The browser's status.

### infc_browser_add_plugin ()

    gboolean            infc_browser_add_plugin             (InfcBrowser *browser,
                                                             const InfcNotePlugin *plugin);

Adds `plugin` to `browser`. This allows the browser to create sessions of the plugin's type. Only one plugin of each type can be added to the directory.

`browser` : | A InfcBrowser.
`plugin` : | A InfcNotePlugin.
Returns : | Whether the plugin was added successfully.

### infc_browser_lookup_plugin ()

    const InfcNotePlugin * infc_browser_lookup_plugin       (InfcBrowser *browser,
                                                             const gchar *note_type);

Returns a previously registered plugin (see `infc_browser_add_plugin()`) for the given note type, or `NULL` if there is no such plugin.

`browser` : | A InfcBrowser.
`note_type` : | A note type, such as "InfText".
Returns : | A InfcNotePlugin, or `NULL`.

### infc_browser_iter_get_root ()

    void                infc_browser_iter_get_root          (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);

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

`browser` : | A InfcBrowser.
`iter` : | An uninitialized InfcBrowserIter.

### infc_browser_iter_get_next ()

    gboolean            infc_browser_iter_get_next          (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);

Sets `iter` to point to the next node within the same subdirectory. If `iter` already points to the last node, `iter` is left untouched and `FALSE` is returned.

`browser` : | A InfcBrowser
`iter` : | A InfcBrowserIter pointing to a node in `browser`.
Returns : | `TRUE` if iter was set, `FALSE` otherwise.

### infc_browser_iter_get_prev ()

    gboolean            infc_browser_iter_get_prev          (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);

Sets `iter` to point to the provious node within the same subdirectory. If `iter` already points to the first node, `iter` is left untouched and `FALSE` is returned.

`browser` : | A InfcBrowser
`iter` : | A InfcBrowserIter pointing to a node in `browser`.
Returns : | `TRUE` if iter was set, `FALSE` otherwise.

### infc_browser_iter_get_parent ()

    gboolean            infc_browser_iter_get_parent        (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);

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

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a node in `browser`.
Returns : | `TRUE` if iter was set, `FALSE` otherwise.

### infc_browser_iter_get_explored ()

    gboolean            infc_browser_iter_get_explored      (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns whether the subdirectory node `iter` points to has been explored.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a subdirectory node in `browser`.
Returns : | `TRUE` if the subdirectory has been explored and `FALSE` otherwise.

### infc_browser_iter_get_child ()

    gboolean            infc_browser_iter_get_child         (InfcBrowser *browser,
                                                             InfcBrowserIter *iter);

Sets `iter` to point to the first child of the subdirectory it is currently pointing to. The subdirectory must already have been explored. If the subdirectory has no children, `iter` is left untouched and `FALSE` is returned.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a subdirectory node in `brwoser` that has already been explored.
Returns : | `TRUE` if `iter` was set, `FALSE` otherwise.

### infc_browser_iter_explore ()

    InfcExploreRequest * infc_browser_iter_explore          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Explores the given subdirectory node. The returned request may be used to get informed about exploration progress and completion. When the exploration has been initiated, `infc_browser_iter_get_child()` may be called to get the content that has been explored so far. When the request has finished, all content is available.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a subdirectory node in `browser` that has not yet been explored.
Returns : | A InfcExploreRequest to watch the exploration process.

### infc_browser_iter_get_name ()

    const gchar *       infc_browser_iter_get_name          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

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

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a node in `browser`.
Returns : | The node's name. The returned string must not be freed.

### infc_browser_iter_get_path ()

    gchar *             infc_browser_iter_get_path          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns the complete path to the node `iter` points to. The path to a node is the name of the node and the name of all parent nodes separated by '/', as a filesystem path on Unix.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a node in `browser`.
Returns : | The node's path. Free with `g_free()` when no longer in use.

### infc_browser_iter_is_subdirectory ()

    gboolean            infc_browser_iter_is_subdirectory   (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns whether `iter` points to a subdirectory node or not.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a node in `browser`.
Returns : | Whether the node `iter` points to is a subdirectory node.

### infc_browser_add_subdirectory ()

    InfcNodeRequest *   infc_browser_add_subdirectory       (InfcBrowser *browser,
                                                             const InfcBrowserIter *parent,
                                                             const gchar *name);

Creates a new request that asks the server to create a new subdirectory. Note that the parent subdirectory must already have been explored.

`browser` : | A InfcBrowser.
`parent` : | A InfcBrowserIter pointing to an explored subdirectory in which to create the new subdirectory.
`name` : | The name for the new subdirectory.
Returns : | A InfcNodeRequest to be notified when the request finishes or fails.

### infc_browser_add_note ()

    InfcNodeRequest *   infc_browser_add_note               (InfcBrowser *browser,
                                                             const InfcBrowserIter *parent,
                                                             const gchar *name,
                                                             const InfcNotePlugin *plugin,
                                                             gboolean initial_subscribe);

Asks the server to create a new note with the given type. The returned request may be used to be notified when the request finishes or fails.

If `initial_subscribe` is set, then, when the returned request finishes, you might call `infc_browser_iter_get_session()` on the resulting InfcBrowserIter. 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.

`browser` : | A InfcBrowser.
`parent` : | A InfcBrowserIter pointing to an explored subdirectory.
`name` : | Name for the new node.
`plugin` : | Type of the new node.
`initial_subscribe` : | Whether to automatically subscribe to the newly created node.
Returns : | A InfcNodeRequest.

### infc_browser_add_note_with_content ()

    InfcNodeRequest *   infc_browser_add_note_with_content  (InfcBrowser *browser,
                                                             const InfcBrowserIter *parent,
                                                             const gchar *name,
                                                             const InfcNotePlugin *plugin,
                                                             InfSession *session,
                                                             gboolean initial_subscribe);

Asks the server to create a new note with the given type. The returned request may be used to be notified when the request finishes or fails.

The returned request finishes as soon as the server acknowledges the creation of the node, which is before the content is transmitted. If, during transmission, an error occurs, then the node is removed again. To get notified when the transmission fails, finishes or changes in progress, you can connect to 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 `infc_browser_iter_get_session()` on the resulting InfcBrowserIter. 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.

`browser` : | A InfcBrowser.
`parent` : | A InfcBrowserIter pointing to an explored subdirectory.
`name` : | Name for the new node.
`plugin` : | Type of the new node.
`session` : | A session that is copied to the server and used as initial content for the new node.
`initial_subscribe` : | Whether to automatically subscribe to the newly created node.
Returns : | A InfcNodeRequest.

### infc_browser_remove_node ()

    InfcNodeRequest *   infc_browser_remove_node            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Asks the server to remove the node `iter` points to.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a node in `browser`.
Returns : | A InfcNodeRequest that may be used to get notified when the request finishes or fails.

### infc_browser_iter_get_note_type ()

    const gchar *       infc_browser_iter_get_note_type     (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns the type of the note `iter` points to. This must not be a subdirectory node.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a note inside `browser`.
Returns : | The note's type.

### infc_browser_iter_get_plugin ()

    const InfcNotePlugin * infc_browser_iter_get_plugin     (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns the InfcNotePlugin that is used for subscriptions to the note `iter` points to, or `NULL` if no plugin for the note's type has been registered.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a note inside `browser`.
Returns : | A InfcNotePlugin, or `NULL`.

### infc_browser_iter_subscribe_session ()

    InfcNodeRequest *   infc_browser_iter_subscribe_session (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Subscribes to the given note. When the request has finished (which does not mean that the subscription has finished, but the server is ready to perform the subscription), `infc_browser_iter_get_session()` can be used to access the InfcSessionProxy object representing the subscription.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a note inside `browser`.
Returns : | A InfcNodeRequest that may be used to get notified when the request finishes or fails.

### infc_browser_iter_save_session ()

    InfcNodeRequest *   infc_browser_iter_save_session      (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Requests that the server saves the note pointed to by `iter` into its background storage. Normally, the server only does this when it is either shut down or when the there are no more subscriptions to the note. Note that this is merely a request and the server might decide not to save the session for whatever reason.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a note in `browser`.
Returns : | A InfcNodeRequest that may be used to get notified when the request finishes or fails.

### infc_browser_iter_get_session ()

    InfcSessionProxy *  infc_browser_iter_get_session       (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns the InfcSessionProxy representing the subscription to the given note, if the client is subscribed, and `NULL` otherwise.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a note in `browser`.
Returns : | A InfcSessionProxy, or `NULL` if not subscribed.

### infc_browser_iter_get_sync_in ()

    InfcSessionProxy *  infc_browser_iter_get_sync_in       (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns the InfcSessionProxy that is used to synchronize the note `iter` points to to the server. Such a node is created by `infc_browser_add_note_with_content()`. If the client is subscribed to this note, then this returns the same session as `infc_browser_iter_get_session()`. However, it is possible that we synchronize this node to the server without being subscribed to it. In this case, this function returns the session that does the synchronization, while `infc_browser_iter_get_session()` would return `NULL`.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a note in `browser`.
Returns : | A InfcSessionProxy, or `NULL` if we are currently not synchronizing this node to the server.

### infc_browser_iter_get_subscribe_request ()

    InfcNodeRequest *   infc_browser_iter_get_subscribe_request
                                                            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns the InfcNodeRequest that represents the subscription request sent for the note `iter` points to. Returns `NULL` if we are already subscribed to that node, or no subscription request has been sent. In the former case `infc_browser_iter_get_session()` will return the InfcSessionProxy for the subscription.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a note in `browser`.
Returns : | A InfcNodeRequest, or `NULL`.

### infc_browser_iter_get_explore_request ()

    InfcExploreRequest * infc_browser_iter_get_explore_request
                                                            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns the InfcExploreRequest with which the node `iter` points to is currenty explored. Returns `NULL` if that node is already explored or is not currently explored.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a subdirectory node in `browser`.
Returns : | A InfcExploreRequest, or `NULL`.

### infc_browser_iter_get_sync_in_requests ()

    GSList *            infc_browser_iter_get_sync_in_requests
                                                            (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns a list of all InfcNodeRequest created with `infc_browser_add_note_with_content()` with the node `iter` points to as parent. Such requests begin a synchronization to the server when they have finished.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter pointing to a subdirectory node in `browser`.
Returns : | A list of InfcNodeRequests. Free with `g_slist_free()` when done.

### infc_browser_iter_from_node_request ()

    gboolean            infc_browser_iter_from_node_request (InfcBrowser *browser,
                                                             InfcNodeRequest *request,
                                                             InfcBrowserIter *iter);

Sets `iter` to point to the node `request` is related to. If there is no such node (someone could have deleted it while the request is still running), the function returns `FALSE` and `iter` is unchanged.

`browser` : | A InfcBrowser.
`request` : | A InfcNodeRequest issued by `browser`.
`iter` : | A InfcBrowserIter.
Returns : | `TRUE` if `iter` was set, `FALSE` otherwise.

### infc_browser_iter_from_explore_request ()

    gboolean            infc_browser_iter_from_explore_request
                                                            (InfcBrowser *browser,
                                                             InfcExploreRequest *request,
                                                             InfcBrowserIter *iter);

Sets `iter` to the node `request` is currently exploring. If there is no such node (someone could have deleted it while exploring), the function returns `FALSE` and lets `iter` untouched.

`browser` : | A InfcBrowser.
`request` : | A InfcExploreRequest exploring a node in `browser`.
`iter` : | A InfcBrowserIter.
Returns : | `TRUE` if `iter` was set, `FALSE` otherwise.

### infc_browser_iter_is_valid ()

    gboolean            infc_browser_iter_is_valid          (InfcBrowser *browser,
                                                             const InfcBrowserIter *iter);

Returns whether `iter` points to a valid node in `browser`. This is generally the case for any InfcBrowserIter returned by one of the InfcBrowser functions, it gets invalid however as soon as the node it points to is removed.

`browser` : | A InfcBrowser.
`iter` : | A InfcBrowserIter.
Returns : | Whether `iter` points to a node in `browser`.

### infc_browser_subscribe_chat ()

    InfcNodeRequest *   infc_browser_subscribe_chat         (InfcBrowser *browser);

Attempts to subscribe to the server's chat. When the operation finishes `infc_browser_get_chat_session()` will return a InfcSessionProxy representing the chat session. It can be used to read the chat's content. The request can fail in case the server chat is disabled.

`browser` : | A InfcBrowser.
Returns : | A InfcNodeRequest that may be used to get notified when the request finishes or fails.

### infc_browser_get_subscribe_chat_request ()

    InfcNodeRequest *   infc_browser_get_subscribe_chat_request
                                                            (InfcBrowser *browser);

Returns the InfcNodeRequest that represests the request sent to the server which attempts to subscribe to its chat. If there is no such request running, then the function returns `NULL`. After such a request finishes, call `infc_browser_get_chat_session()` to get the InfcSessionProxy for the chat session. To initiate the request, call `infc_browser_subscribe_chat()`.

`browser` : | A InfcBrowser.
Returns : | A InfcNodeRequest, or `NULL`.

### infc_browser_get_chat_session ()

    InfcSessionProxy *  infc_browser_get_chat_session       (InfcBrowser *browser);

Returns the InfcSessionProxy representing the running chat session if the local client is subscribed to it, or `NULL` otherwise.

`browser` : | A InfcBrowser.
Returns : | A InfcSessionProxy for the chat, or `NULL`.

## Property Details

### The `"chat-session"` property

      "chat-session"             InfcSessionProxy*     : Read

Active chat session.

### The `"communication-manager"` property

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

The communication manager for the browser.

### The `"connection"` property

      "connection"               InfXmlConnection*     : Read / Write / Construct Only

Connection to the server exposing the directory to browse.

### The `"io"` property

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

The InfIo to schedule timeouts.

### The `"status"` property

      "status"                   InfcBrowserStatus     : Read

The current connectivity status of the browser.

Default value: INFC_BROWSER_DISCONNECTED

## Signal Details

### The `"begin-explore"` signal

    void                user_function                      (InfcBrowser        *browser,
                                                            InfcBrowserIter    *iter,
                                                            InfcExploreRequest *request,
                                                            gpointer            user_data)      : Run Last

This signal is emitted when a subdirectory is started to be explored. `request` can be used to get notified when the exploration was finished.

`browser` : | The InfcBrowser emitting the siganl.
`iter` : | A InfcBrowserIter pointing to the node being explored.
`request` : | A InfcExploreRequest for the operation.
`user_data` : | user data set when the signal handler was connected.

### The `"begin-subscribe"` signal

    void                user_function                      (InfcBrowser     *browser,
                                                            InfcBrowserIter *iter,
                                                            InfcNodeRequest *request,
                                                            gpointer         user_data)      : Run Last

This signal is emitted whenever a subscription request for a (non-subdirectory) node is made. Note that the subscription may still fail (connect to "finished" and "failed" to be notified).

If `iter` is `NULL` the signal refers to the chat session, otherwise it points to the node to whose session the client requested a subscription.

`browser` : | The InfcBrowser emitting the signal.
`iter` : | A InfcBrowserIter pointing to the node to which the subscription starts, or `NULL`.
`request` : | A InfcNodeRequest for the operation.
`user_data` : | user data set when the signal handler was connected.

### The `"error"` signal

    void                user_function                      (InfcBrowser *browser,
                                                            gpointer     error,
                                                            gpointer     user_data)      : Run Last

This signal is emitted whenever an error occured. If the browser's underlying InfXmlConnection produces emits "error", then this signal will be emitted with the corresponding error as well. Also, if another error occurs on the browser level this signal is emitted. It may or may not be fatal. If it is fatal then the browser's status will change to `INFC_BROWSER_DISCONNECTED`.

`browser` : | The InfcBrowser emitting the signal.
`error` : | A `GError`* saying what's wrong.
`user_data` : | user data set when the signal handler was connected.

### The `"node-added"` signal

    void                user_function                      (InfcBrowser     *browser,
                                                            InfcBrowserIter *iter,
                                                            gpointer         user_data)      : Run Last

Emitted when a new node was added in the browser. This can happen either while exploring a subdirectory, or when a new node was added on the server. In the latter case the signal is only emitted when the parent directory of the newly created node is already explored.

`browser` : | The InfcBrowser emitting the siganl.
`iter` : | A InfcBrowserIter pointing to the created node.
`user_data` : | user data set when the signal handler was connected.

### The `"node-removed"` signal

    void                user_function                      (InfcBrowser     *browser,
                                                            InfcBrowserIter *iter,
                                                            gpointer         user_data)      : Run Last

This signal is emitted every time a node is removed from the browser. This happens when the corresponding node is removed at the server. The signal is emitted only when the parent directory of the removed node is already explored. The signal can also be emitted on non-empty subdirectory nodes in which case all children are also removed.

`browser` : | The InfcBrowser emitting the siganl.
`iter` : | A InfcBrowserIter pointing to the removed node.
`user_data` : | user data set when the signal handler was connected.

### The `"subscribe-session"` signal

    void                user_function                      (InfcBrowser      *browser,
                                                            InfcBrowserIter  *iter,
                                                            InfcSessionProxy *proxy,
                                                            gpointer          user_data)      : Run Last

Emitted when subscribed to a session. The subscription was successful, but the synchronization (the server sending the initial session state) might still fail. Use "synchronization-complete" and "synchronization-failed" to be notified.

If `iter` is `NULL` this is a subscription to the chat. This guarantees `proxy`'s session to be a InfChatSession. If `iter` is non-`NULL` this is a subscription to the session of the node pointed to by `iter`.

`browser` : | The InfcBrowser emitting the siganl.
`iter` : | A InfcBrowserIter pointing to the subscribed node, or `NULL`.
`proxy` : | A InfcSessionProxy for the subscribed session.
`user_data` : | user data set when the signal handler was connected.

## See Also

InfdDirectory