TrackerMinerManager

TrackerMinerManager — External control and monitoring of miners

Functions

GQuark tracker_miner_manager_error_quark ()
TrackerMinerManager * tracker_miner_manager_new ()
TrackerMinerManager * tracker_miner_manager_new_full ()
GSList * tracker_miner_manager_get_running ()
GSList * tracker_miner_manager_get_available ()
gboolean tracker_miner_manager_pause ()
gboolean tracker_miner_manager_pause_for_process ()
gboolean tracker_miner_manager_resume ()
gboolean tracker_miner_manager_is_active ()
gboolean tracker_miner_manager_is_paused ()
gboolean tracker_miner_manager_get_status ()
const gchar * tracker_miner_manager_get_display_name ()
const gchar * tracker_miner_manager_get_description ()
gboolean tracker_miner_manager_reindex_by_mimetype ()
gboolean tracker_miner_manager_index_file ()
void tracker_miner_manager_index_file_async ()
gboolean tracker_miner_manager_index_file_finish ()
gboolean tracker_miner_manager_ignore_next_update ()

Properties

gboolean auto-start Read / Write / Construct Only

Signals

void miner-activated Run Last
void miner-deactivated Run Last
void miner-paused Run Last
void miner-progress Run Last
void miner-resumed Run Last

Types and Values

#define TRACKER_MINER_MANAGER_ERROR
enum TrackerMinerManagerError
struct TrackerMinerManager
  TrackerMinerManagerClass

Object Hierarchy

    GObject
    ╰── TrackerMinerManager

Implemented Interfaces

TrackerMinerManager implements GInitable.

Includes

#include <libtracker-control/tracker-control.h>

Description

TrackerMinerManager keeps track of available miners, their current progress/status, and also allows basic external control on them, such as pausing or resuming data processing.

Functions

tracker_miner_manager_error_quark ()

GQuark
tracker_miner_manager_error_quark (void);

Returns

the GQuark used to identify miner manager errors in GError structures.

Since 0.8

tracker_miner_manager_new ()

TrackerMinerManager *
tracker_miner_manager_new (void);

Creates a new TrackerMinerManager instance.

Note: Auto-starting miners when querying status will be enabled.

Returns

a TrackerMinerManager or NULL if an error happened.

Since 0.8

tracker_miner_manager_new_full ()

TrackerMinerManager *
tracker_miner_manager_new_full (gboolean auto_start,
                                GError **error);

Creates a new TrackerMinerManager.

Parameters

auto_start

Flag to disable auto-starting the miners when querying status

  

error

a GError to report errors.

  

Returns

a TrackerMinerManager. On error, NULL is returned and error is set accordingly.

Since 0.10.5

tracker_miner_manager_get_running ()

GSList *
tracker_miner_manager_get_running (TrackerMinerManager *manager);

Returns a list of references for all active miners. Active miners are miners which are running within a process.

Parameters

manager

a trackerMinerManager

  

Returns

a GSList which must be freed with g_slist_free() and all contained data with g_free(). Otherwise NULL is returned if there are no miners.

[transfer full][element-type utf8][nullable]

Since 0.8

tracker_miner_manager_get_available ()

GSList *
tracker_miner_manager_get_available (TrackerMinerManager *manager);

Returns a list of references for all available miners. Available miners are miners which may or may not be running in a process at the current time.

Parameters

manager

a TrackerMinerManager

  

Returns

a GSList which must be freed with g_slist_free() and all contained data with g_free(). Otherwise NULL is returned if there are no miners.

[transfer full][element-type utf8][nullable]

Since 0.8

tracker_miner_manager_pause ()

gboolean
tracker_miner_manager_pause (TrackerMinerManager *manager,
                             const gchar *miner,
                             const gchar *reason,
                             guint32 *cookie);

Asks miner to pause. a miner could be paused by several reasons, and its activity won't be resumed until all pause requests have been resumed.

Parameters

manager

a TrackerMinerManager.

  

miner

miner reference

  

reason

reason to pause

  

cookie

return location for the pause cookie ID.

[out][allow-none]

Returns

TRUE if the miner was paused successfully, otherwise FALSE.

Since 0.8

tracker_miner_manager_pause_for_process ()

gboolean
tracker_miner_manager_pause_for_process
                               (TrackerMinerManager *manager,
                                const gchar *miner,
                                const gchar *reason,
                                guint32 *cookie);

This function operates exactly the same way as tracker_miner_manager_pause() with the exception that if the calling process dies, the pause is resumed. This API is useful for cases where the calling process has a risk of crashing without resuming the pause.

NOTE: If you call g_object_unref() on the manager before you intend to resume the pause and it finalizes, it will automatically resume.

Parameters

manager

a TrackerMinerManager.

  

miner

miner reference

  

reason

reason to pause

  

cookie

return location for the pause cookie ID.

[out][allow-none]

Returns

TRUE if the miner was paused successfully, otherwise FALSE.

Since 0.10.15

tracker_miner_manager_resume ()

gboolean
tracker_miner_manager_resume (TrackerMinerManager *manager,
                              const gchar *miner,
                              guint32 cookie);

Tells miner to resume activity. The miner won't actually resume operations until all pause requests have been resumed.

Parameters

manager

a TrackerMinerManager

  

miner

miner reference

  

cookie

pause cookie

  

Returns

TRUE if the miner was successfully resumed, otherwise FALSE.

Since 0.8

tracker_miner_manager_is_active ()

gboolean
tracker_miner_manager_is_active (TrackerMinerManager *manager,
                                 const gchar *miner);

Returns the miner's current activity.

Parameters

manager

a TrackerMinerManager

  

miner

miner reference

  

Returns

TRUE if the miner is active, otherwise FALSE.

Since 0.8

tracker_miner_manager_is_paused ()

gboolean
tracker_miner_manager_is_paused (TrackerMinerManager *manager,
                                 const gchar *miner,
                                 GStrv *applications,
                                 GStrv *reasons);

This function either returns FALSE if the miner is not paused, or returns TRUE and fills in applications and reasons with the pause reasons and the applications that asked for it. Both arrays will have the same lengh, and will be sorted so the application/pause reason pairs have the same index.

Parameters

manager

a TrackerMinerManager

  

miner

miner reference

  

applications

return location for application names.

[out callee-allocates][allow-none][transfer full]

reasons

return location for pause reasons.

[out callee-allocates][allow-none][transfer full]

Returns

TRUE if miner is paused, otherwise FALSE.

Since 0.8

tracker_miner_manager_get_status ()

gboolean
tracker_miner_manager_get_status (TrackerMinerManager *manager,
                                  const gchar *miner,
                                  gchar **status,
                                  gdouble *progress,
                                  gint *remaining_time);

Returns the current status, progress and remaining time for miner . remaining_time will be 0 if not possible to compute it yet, and less than zero if it is not applicable.

Parameters

manager

a TrackerMinerManager

  

miner

miner reference

  

status

return location for status.

[out][allow-none]

progress

return location for progress.

[out][allow-none]

remaining_time

return location for remaining time.

[out][allow-none]

Returns

TRUE if the status could be retrieved successfully, otherwise FALSE

Since 0.12

tracker_miner_manager_get_display_name ()

const gchar *
tracker_miner_manager_get_display_name
                               (TrackerMinerManager *manager,
                                const gchar *miner);

Returns a translated display name for miner .

Parameters

manager

a TrackerMinerManager

  

miner

miner reference

  

Returns

A string which should not be freed or NULL.

[transfer none]

Since 0.8

tracker_miner_manager_get_description ()

const gchar *
tracker_miner_manager_get_description (TrackerMinerManager *manager,
                                       const gchar *miner);

Returns the description for the given miner .

Parameters

manager

a TrackerMinerManager

  

miner

miner reference

  

Returns

A string which should not be freed or NULL if none is specified.

[transfer none]

Since 0.8

tracker_miner_manager_reindex_by_mimetype ()

gboolean
tracker_miner_manager_reindex_by_mimetype
                               (TrackerMinerManager *manager,
                                const GStrv mimetypes,
                                GError **error);

Tells the filesystem miner to reindex any file with a mimetype in the mimetypes list.

On failure error will be set.

Parameters

manager

a TrackerMinerManager

  

mimetypes

an array of mimetypes (E.G. "text/plain"). All items with a mimetype in that list will be reindexed.

[in]

error

return location for errors.

[out callee-allocates][transfer full][allow-none]

Returns

TRUE on success, otherwise FALSE.

Since 0.10

tracker_miner_manager_index_file ()

gboolean
tracker_miner_manager_index_file (TrackerMinerManager *manager,
                                  GFile *file,
                                  GError **error);

Tells the filesystem miner to index the file .

On failure error will be set.

Parameters

manager

a TrackerMinerManager

  

file

a URL valid in GIO of a file to give to the miner for processing

  

error

return location for errors.

[out callee-allocates][transfer full][allow-none]

Returns

TRUE on success, otherwise FALSE.

Since 0.10

tracker_miner_manager_index_file_async ()

void
tracker_miner_manager_index_file_async
                               (TrackerMinerManager *manager,
                                GFile *file,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Tells the filesystem miner to index the file . When the operation is called, callback will be called. You can then call tracker_miner_manager_index_file_finish() to get the result of the operation.

Parameters

manager

a TrackerMinerManager

  

file

a URL valid in GIO of a file to give to the miner for processing

  

cancellable

a GCancellable, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when the request is satisfied.

[scope async]

user_data

the data to pass to the callback function

  

Since 0.16

tracker_miner_manager_index_file_finish ()

gboolean
tracker_miner_manager_index_file_finish
                               (TrackerMinerManager *manager,
                                GAsyncResult *result,
                                GError **error);

Finishes a request to index a file. See tracker_miner_manager_index_file_async()

On failure error will be set.

Parameters

manager

a TrackerMinerManager

  

result

a GAsyncResult

  

error

return location for errors.

[out callee-allocates][transfer full][allow-none]

Returns

TRUE on success, otherwise FALSE.

Since 0.16

tracker_miner_manager_ignore_next_update ()

gboolean
tracker_miner_manager_ignore_next_update
                               (TrackerMinerManager *manager,
                                const gchar *miner,
                                const gchar **urls);

tracker_miner_manager_ignore_next_update has been deprecated since version 0.12 and should not be used in newly-written code.

Tells the miner to ignore any events for the next urls . This is used for cases where a file is updated by Tracker by the tracker-writeback service. This API is used to avoid signalling up the stack the changes to urls .

Parameters

manager

a TrackerMinerManager

  

miner

miner reference

  

urls

the subjects to ignore the next updates of.

[in]

Returns

TRUE on success, otherwise FALSE.

Since 0.8

Types and Values

TRACKER_MINER_MANAGER_ERROR

#define TRACKER_MINER_MANAGER_ERROR tracker_miner_manager_error_quark ()

enum TrackerMinerManagerError

Enumeration values used in errors returned by the TrackerMinerManager API.

Members

TRACKER_MINER_MANAGER_ERROR_NOT_AVAILABLE

The miner in question is not active and can so can not be used.

  

TRACKER_MINER_MANAGER_ERROR_NOENT

The resource that the miner is handling (for example a file or URI) does not exist.

  

Since 0.8

struct TrackerMinerManager

struct TrackerMinerManager;

Object to query and control miners.

TrackerMinerManagerClass

typedef struct {
	GObjectClass parent_class;

	void (* miner_progress)    (TrackerMinerManager *manager,
	                            const gchar         *miner_name,
	                            const gchar         *status,
	                            gdouble              progress);
	void (* miner_paused)      (TrackerMinerManager *manager,
	                            const gchar         *miner_name);
	void (* miner_resumed)     (TrackerMinerManager *manager,
	                            const gchar         *miner_name);
	void (* miner_activated)   (TrackerMinerManager *manager,
	                            const gchar         *miner_name);
	void (* miner_deactivated) (TrackerMinerManager *manager,
	                            const gchar         *miner_name);
} TrackerMinerManagerClass;

Members

GObjectClass parent_class;

    

miner_progress ()

The progress signal for all miners including name, status and progress as a percentage between 0 and 1.

  

miner_paused ()

The paused signal for all miners known about.

  

miner_resumed ()

The resumed signal for all miners known about.

  

miner_activated ()

The activated signal for all miners which indicates the miner is available on d-bus.

  

miner_deactivated ()

The deactivate for all miners which indicates the miner is no longer available on d-bus.

  

Property Details

The “auto-start” property

  “auto-start”               gboolean

If set, auto starts miners when querying their status.

Flags: Read / Write / Construct Only

Default value: TRUE

Signal Details

The “miner-activated” signal

void
user_function (TrackerMinerManager *manager,
               gchar               *miner,
               gpointer             user_data)

The ::miner-activated signal will be emitted whenever a miner (referenced by miner ) is activated (technically, this means the miner has appeared in the session bus).

Parameters

manager

the TrackerMinerManager

  

miner

miner reference

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since 0.8

The “miner-deactivated” signal

void
user_function (TrackerMinerManager *manager,
               gchar               *miner,
               gpointer             user_data)

The ::miner-deactivated signal will be emitted whenever a miner (referenced by miner ) is deactivated (technically, this means the miner has disappeared from the session bus).

Parameters

manager

the TrackerMinerManager

  

miner

miner reference

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since 0.8

The “miner-paused” signal

void
user_function (TrackerMinerManager *manager,
               gchar               *miner,
               gpointer             user_data)

The ::miner-paused signal will be emitted whenever a miner (referenced by miner ) is paused.

Parameters

manager

the TrackerMinerManager

  

miner

miner reference

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since 0.8

The “miner-progress” signal

void
user_function (TrackerMinerManager *manager,
               gchar               *miner,
               gchar               *status,
               gdouble              progress,
               gint                 remaining_time,
               gpointer             user_data)

The ::miner-progress signal is meant to report status/progress changes in any tracked miner.

Parameters

manager

the TrackerMinerManager

  

miner

miner reference

  

status

miner status

  

progress

miner progress, from 0 to 1

  

remaining_time

remaining processing time

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since 0.12

The “miner-resumed” signal

void
user_function (TrackerMinerManager *manager,
               gchar               *miner,
               gpointer             user_data)

The ::miner-resumed signal will be emitted whenever a miner (referenced by miner ) is resumed.

Parameters

manager

the TrackerMinerManager

  

miner

miner reference

  

user_data

user data set when the signal handler was connected.

  

Flags: Run Last

Since 0.8

Generated by GTK-Doc V1.21