FmFolder

FmFolder — Folder loading and monitoring.

Functions

Signals

void changed Run First
void content-changed Run First
guint error Run Last
void files-added Run First
void files-changed Run First
void files-removed Run First
void finish-loading Run First
void fs-info Run First
void removed Run First
void start-loading Run First
void unmount Run First

Object Hierarchy

    GObject
    ╰── FmFolder

Description

include : libfm/fm.h

The FmFolder object allows to open and monitor items of some directory (either local or remote), i.e. files and directories, to have fast access to their info and to info of the directory itself as well.

Functions

fm_folder_from_path ()

FmFolder *
fm_folder_from_path (FmPath *path);

Retrieves a folder corresponding to path . Returned data may be freshly created or already loaded. Caller should call g_object_unref() on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get.

Parameters

path

path descriptor for the folder

 

Returns

FmFolder corresponding to path .

[transfer full]

Since: 0.1.1


fm_folder_from_gfile ()

FmFolder *
fm_folder_from_gfile (GFile *gf);

Retrieves a folder corresponding to gf . Returned data may be freshly created or already loaded. Caller should call g_object_unref() on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get_for_gfile.

Parameters

gf

GFile file descriptor

 

Returns

FmFolder corresponding to gf .

[transfer full]

Since: 0.1.1


fm_folder_from_path_name ()

FmFolder *
fm_folder_from_path_name (const char *path);

Retrieves a folder corresponding to path . Returned data may be freshly created or already loaded. Caller should call g_object_unref() on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get_for_path_name.

Parameters

path

POSIX path to the folder

 

Returns

FmFolder corresponding to path .

[transfer full]

Since: 0.1.0


fm_folder_from_uri ()

FmFolder *
fm_folder_from_uri (const char *uri);

Retrieves a folder corresponding to uri . Returned data may be freshly created or already loaded. Caller should call g_object_unref() on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get_for_uri.

Parameters

uri

URI for the folder

 

Returns

FmFolder corresponding to uri .

[transfer full]

Since: 0.1.0


fm_folder_find_by_path ()

FmFolder *
fm_folder_find_by_path (FmPath *path);

Checks if folder by path is already in use.

Parameters

path

path descriptor

 

Returns

found folder or NULL.

[transfer full]

Since: 1.2.0


fm_folder_block_updates ()

void
fm_folder_block_updates (FmFolder *folder);

Blocks emitting signals for changes in folder, i.e. if some file was added, changed, or removed in folder after this API, no signal will be sent until next call to fm_folder_unblock_updates().

Parameters

folder

folder to apply

 

Since: 1.2.0


fm_folder_unblock_updates ()

void
fm_folder_unblock_updates (FmFolder *folder);

Unblocks emitting signals for changes in folder. If some changes were in folder after previous call to fm_folder_block_updates() then these changes will be sent after this call.

Parameters

folder

folder to apply

 

Since: 1.2.0


fm_folder_get_info ()

FmFileInfo *
fm_folder_get_info (FmFolder *folder);

Retrieves FmFileInfo data about the folder itself. Returned data is owned by FmFolder and should be not modified or freed by caller.

Parameters

folder

folder to retrieve info

 

Returns

info descriptor of the folder .

[transfer none]

Since: 1.0.0


fm_folder_get_path ()

FmPath *
fm_folder_get_path (FmFolder *folder);

Retrieves path of the folder. Returned data is owned by FmFolder and should be not modified or freed by caller.

Parameters

folder

folder to retrieve path

 

Returns

path of the folder.

[transfer none]

Since: 1.0.0


fm_folder_get_files ()

FmFileInfoList *
fm_folder_get_files (FmFolder *folder);

Retrieves list of currently known files and subdirectories in the folder . Returned list is owned by FmFolder and should be not modified by caller. If caller wants to keep a reference to the returned list it should do fm_file_info_list_ref() on the returned data.

Before 1.0.0 this call had name fm_folder_get.

Parameters

folder

folder to retrieve file list

 

Returns

list of items that folder currently contains.

[transfer none]

Since: 0.1.1


fm_folder_is_empty ()

gboolean
fm_folder_is_empty (FmFolder *folder);

Checks if folder has no files or subdirectories.

Parameters

folder

folder to test

 

Returns

TRUE if folder is empty.

Since: 1.0.0


fm_folder_get_file_by_name ()

FmFileInfo *
fm_folder_get_file_by_name (FmFolder *folder,
                            const char *name);

Tries to find a file with basename name in the folder . Returned data is owned by FmFolder and should be not freed by caller.

Parameters

folder

folder to search

 

name

basename of file in folder

 

Returns

info descriptor of file or NULL if no file was found.

[transfer none]

Since: 0.1.16


fm_folder_is_loaded ()

gboolean
fm_folder_is_loaded (FmFolder *folder);

Checks if all data for folder is completely loaded.

Before 1.0.0 this call had name fm_folder_get_is_loaded.

Parameters

folder

folder to test

 

Returns

TRUE is loading of folder is already completed.

Since: 0.1.16


fm_folder_is_valid ()

gboolean
fm_folder_is_valid (FmFolder *folder);

Checks if directory described by folder exists.

Parameters

folder

folder to test

 

Returns

TRUE if folder describes a valid existing directory.

Since: 1.0.0


fm_folder_is_incremental ()

gboolean
fm_folder_is_incremental (FmFolder *folder);

Checks if a folder is incrementally loaded. After an FmFolder object is obtained from calling fm_folder_from_path(), if it's not yet loaded, it begins loading the content of the folder and emits "start-loading" signal. Most of the time, the info of the files in the folder becomes available only after the folder is fully loaded. That means, after the "finish-loading" signal is emitted. Before the loading is finished, fm_folder_get_files() returns nothing. You can tell if a folder is still being loaded with fm_folder_is_loaded().

However, for some special FmFolder types, such as the ones handling search:// URIs, we want to access the file infos while the folder is still being loaded (the search is still ongoing). The content of the folder grows incrementally and fm_folder_get_files() returns files currently being loaded even when the folder is not fully loaded. This is what we called incremental. fm_folder_is_incremental() tells you if the FmFolder has this feature.

Parameters

folder

folder to test

 

Returns

TRUE if folder is incrementally loaded

Since: 1.0.2


fm_folder_reload ()

void
fm_folder_reload (FmFolder *folder);

Causes to retrieve all data for the folder as if folder was freshly opened.

Parameters

folder

folder to be reloaded

 

Since: 0.1.1


fm_folder_get_filesystem_info ()

gboolean
fm_folder_get_filesystem_info (FmFolder *folder,
                               guint64 *total_size,
                               guint64 *free_size);

Retrieves info about total and free space on the filesystem which contains the folder .

Parameters

folder

folder to retrieve info

 

total_size

pointer to counter of total size of the filesystem

 

free_size

pointer to counter of free space on the filesystem

 

Returns

TRUE if information can be retrieved.

Since: 0.1.16


fm_folder_query_filesystem_info ()

void
fm_folder_query_filesystem_info (FmFolder *folder);

Queries to retrieve info about filesystem which contains the folder if the filesystem supports such query.

Parameters

folder

folder to retrieve info

 

Since: 0.1.16


fm_folder_make_directory ()

gboolean
fm_folder_make_directory (FmFolder *folder,
                          const char *name,
                          GError **error);

Creates new directory in given folder .

Parameters

folder

folder to apply

 

name

display name for new directory

 

error

location to save error.

[allow-none][out]

Returns

TRUE in case of success.

Since: 1.2.0

Signal Details

The “changed” signal

void
user_function (FmFolder *folder,
               gpointer  user_data)

The “changed” signal is emitted when the folder itself was changed.

Parameters

folder

the monitored directory

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.16


The “content-changed” signal

void
user_function (FmFolder *folder,
               gpointer  user_data)

The “content-changed” signal is emitted when content of the folder is changed (some files are added, removed, or changed).

Parameters

folder

the monitored directory

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.16


The “error” signal

guint
user_function (FmFolder *folder,
               GError   *error,
               guint     severity,
               gpointer  user_data)

The “error” signal is emitted when some error happens. A case if more than one handler is connected to this signal is ambiguous.

Parameters

folder

the monitored directory

 

error

error descriptor

 

severity

FmJobErrorSeverity of the error

 

user_data

user data set when the signal handler was connected.

 

Returns

FmJobErrorAction that should be performed on that error.

Flags: Run Last

Since: 0.1.1


The “files-added” signal

void
user_function (FmFolder *folder,
               gpointer  list,
               gpointer  user_data)

The “files-added” signal is emitted when there is some new file created in the directory.

Parameters

folder

the monitored directory

 

list

GList of newly added FmFileInfo

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.0


The “files-changed” signal

void
user_function (FmFolder *folder,
               gpointer  list,
               gpointer  user_data)

The “files-changed” signal is emitted when some file in the directory was changed.

Parameters

folder

the monitored directory

 

list

GList of FmFileInfo that were changed

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.0


The “files-removed” signal

void
user_function (FmFolder *folder,
               gpointer  list,
               gpointer  user_data)

The “files-removed” signal is emitted when some file was deleted from the directory.

Parameters

folder

the monitored directory

 

list

GList of FmFileInfo that were deleted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.0


The “finish-loading” signal

void
user_function (FmFolder *folder,
               gpointer  user_data)

The “finish-loading” signal is emitted when the content of the folder is loaded. This signal may be emitted more than once and can be induced by calling fm_folder_reload().

Parameters

folder

the monitored directory

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 1.0.0


The “fs-info” signal

void
user_function (FmFolder *folder,
               gpointer  user_data)

The “fs-info” signal is emitted when filesystem information is available.

Parameters

folder

the monitored directory

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.16


The “removed” signal

void
user_function (FmFolder *folder,
               gpointer  user_data)

The “removed” signal is emitted when the folder itself was deleted.

Parameters

folder

the monitored directory

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.16


The “start-loading” signal

void
user_function (FmFolder *folder,
               gpointer  user_data)

The “start-loading” signal is emitted when the folder is about to be reloaded.

Parameters

folder

the monitored directory

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 1.0.0


The “unmount” signal

void
user_function (FmFolder *folder,
               gpointer  user_data)

The “unmount” signal is emitted when the folder was unmounted.

Parameters

folder

the monitored directory

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since: 0.1.1