## InfcExploreRequest InfcExploreRequest — Watch progess of node exploration |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/client/infc-explore-request.h>

                        InfcExploreRequest;
    struct              InfcExploreRequestClass;
    guint               infc_explore_request_get_node_id    (InfcExploreRequest *request);
    void                infc_explore_request_initiated      (InfcExploreRequest *request,
                                                             guint total);
    gboolean            infc_explore_request_progress       (InfcExploreRequest *request,
                                                             GError **error);
    gboolean            infc_explore_request_finished       (InfcExploreRequest *request,
                                                             GError **error);
    gboolean            infc_explore_request_get_initiated  (InfcExploreRequest *request);
    gboolean            infc_explore_request_get_finished   (InfcExploreRequest *request);

## Object Hierarchy

      GObject
       +----InfcRequest
             +----InfcExploreRequest

## Properties

      "current"                  guint                 : Read / Write
      "finished"                 gboolean              : Read
      "initiated"                gboolean              : Read
      "node-id"                  guint                 : Read / Write / Construct Only
      "total"                    guint                 : Read / Write

## Signals

      "finished"                                       : Run Last
      "initiated"                                      : Run Last
      "progress"                                       : Run Last

## Description

When starting a node exploration using `infc_browser_iter_explore()` then it returns an InfcExploreRequest. This object can be used to get notified when there is progress in exploration (for example to show a progress bar in the GUI) or when the operation finished, that is all child nodes of the explored subdirectory are known to the browser.

When the exploration starts the "initiated" signal is emitted. Then, for each node being explored "progress" is emitted. Eventually, "finished" is emitted when the exploration has finished. Before each step the request can also fail, in which case "failed" is emitted. When this happens then none of the other signals will be emitted anymore.

## Details

### InfcExploreRequest

    typedef struct _InfcExploreRequest InfcExploreRequest;

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

### struct InfcExploreRequestClass

    struct InfcExploreRequestClass {
      /* Signals */
      void (*initiated)(InfcExploreRequest *explore_request,
                        guint total);
      void (*progress)(InfcExploreRequest* explore_request,
                       guint current,
                       guint total);
      void (*finished)(InfcExploreRequest* explore_request);
    };

This structure contains default signal handlers for InfcExploreRequest.

`initiated` () | Default signal handler for the "initiated" signal.
`progress` () | Default signal handler for the "progress" signal.
`finished` () | Default signal handler for the "finished" signal.

### infc_explore_request_get_node_id ()

    guint               infc_explore_request_get_node_id    (InfcExploreRequest *request);

Returns the ID of the node to be explored.

`request` : | An InfcExploreRequest.
Returns : | ID of the node to be explored.

### infc_explore_request_initiated ()

    void                infc_explore_request_initiated      (InfcExploreRequest *request,
                                                             guint total);

Emits the "initiated" signal on `request`. An explore request is considered initiated as soon as the total amount of child nodes is known.

`request` : | An InfcExploreRequest.
`total` : | The total number of children of the node which is being explored.

### infc_explore_request_progress ()

    gboolean            infc_explore_request_progress       (InfcExploreRequest *request,
                                                             GError **error);

Emits the "progress" signal on `request`.

`request` : | A InfcExploreRequest.
`error` : | Location to store error information.
Returns : | `TRUE` when the signal was emitted, `FALSE` on error.

### infc_explore_request_finished ()

    gboolean            infc_explore_request_finished       (InfcExploreRequest *request,
                                                             GError **error);

Emits the "finished" signal on `request`.

`request` : | A InfcExploreRequest.
`error` : | Location to store error information.
Returns : | `TRUE` when the signal was emitted, `FALSE` on error.

### infc_explore_request_get_initiated ()

    gboolean            infc_explore_request_get_initiated  (InfcExploreRequest *request);

Returns whether the exploration process was already initiated, i.e. the total number of nodes to explore is known.

`request` : | A InfcExploreRequest.
Returns : | Whether the exploration was initiated.

### infc_explore_request_get_finished ()

    gboolean            infc_explore_request_get_finished   (InfcExploreRequest *request);

Returns whether the exploration process has finished, i.e. the "finished" signal was emitted.

`request` : | A InfcExploreRequest.
Returns : | Whether the exploration has finished.

## Property Details

### The `"current"` property

      "current"                  guint                 : Read / Write

Node that has just been explored.

Default value: 0

### The `"finished"` property

      "finished"                 gboolean              : Read

Whether the exploration process has finished.

Default value: FALSE

### The `"initiated"` property

      "initiated"                gboolean              : Read

Whether the exploration process was already initiated.

Default value: FALSE

### The `"node-id"` property

      "node-id"                  guint                 : Read / Write / Construct Only

ID of the node to explore.

Default value: 0

### The `"total"` property

      "total"                    guint                 : Read / Write

Total number of nodes that are explored.

Default value: 0

## Signal Details

### The `"finished"` signal

    void                user_function                      (InfcExploreRequest *request,
                                                            gpointer            user_data)      : Run Last

This signal is emitted when the exploration finished successfully and all child nodes of the subdirectory being explored are known.

`request` : | The InfcExploreRequest which finished.
`user_data` : | user data set when the signal handler was connected.

### The `"initiated"` signal

    void                user_function                      (InfcExploreRequest *request,
                                                            guint               total,
                                                            gpointer            user_data)      : Run Last

This signal is emitted once the exploration has been initiated, that is when it is known how many child nodes are going to be explored. The number of nodes is provided in the `total` parameter.

`request` : | The InfcExploreRequest that is being initiated.
`total` : | Total number of the directory's child nodes.
`user_data` : | user data set when the signal handler was connected.

### The `"progress"` signal

    void                user_function                      (InfcExploreRequest *request,
                                                            guint               current,
                                                            guint               total,
                                                            gpointer            user_data)      : Run Last

This signal is emitted for each child node that is added to the subdirectory being explored. This can for example be used to update a progress bar in the GUI.

`request` : | The InfcExploreRequest that made progress.
`current` : | The number of child nodes retrieved so far.
`total` : | The total number of child nodes.
`user_data` : | user data set when the signal handler was connected.