FmFolder

FmFolder — Folder loading and monitoring.

Synopsis

                    FmFolder;
struct              FmFolderClass;
FmFolder *          fm_folder_from_gfile                (GFile *gf);
FmFolder *          fm_folder_from_path                 (FmPath *path);
FmFolder *          fm_folder_from_path_name            (const char *path);
FmFolder *          fm_folder_from_uri                  (const char *uri);
FmFileInfo *        fm_folder_get_file_by_name          (FmFolder *folder,
                                                         const char *name);
FmFileInfoList *    fm_folder_get_files                 (FmFolder *folder);
gboolean            fm_folder_get_filesystem_info       (FmFolder *folder,
                                                         guint64 *total_size,
                                                         guint64 *free_size);
FmFileInfo *        fm_folder_get_info                  (FmFolder *folder);
FmPath *            fm_folder_get_path                  (FmFolder *folder);
gboolean            fm_folder_is_empty                  (FmFolder *folder);
gboolean            fm_folder_is_incremental            (FmFolder *folder);
gboolean            fm_folder_is_loaded                 (FmFolder *folder);
gboolean            fm_folder_is_valid                  (FmFolder *folder);
void                fm_folder_query_filesystem_info     (FmFolder *folder);
void                fm_folder_reload                    (FmFolder *folder);

Object Hierarchy

  GObject
   +----FmFolder

Signals

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

Description

include: libfm/fm-folder.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.

Details

FmFolder

typedef struct _FmFolder FmFolder;

struct FmFolderClass

struct FmFolderClass {
    GObjectClass parent_class;

    void (*files_added)(FmFolder* dir, GSList* files);
    void (*files_removed)(FmFolder* dir, GSList* files);
    void (*files_changed)(FmFolder* dir, GSList* files);
    void (*start_loading)(FmFolder* dir);
    void (*finish_loading)(FmFolder* dir);
    void (*unmount)(FmFolder* dir);
    void (*changed)(FmFolder* dir);
    void (*removed)(FmFolder* dir);
    void (*content_changed)(FmFolder* dir);
    void (*fs_info)(FmFolder* dir);
    guint (*error)(FmFolder* dir, GError* err, guint severity);
};

GObjectClass parent_class;

the parent class

files_added ()

the class closure for "files-added" signal

files_removed ()

the class closure for "files-removed" signal

files_changed ()

the class closure for "files-changed" signal

start_loading ()

the class closure for "start-loading" signal

finish_loading ()

the class closure for "finish-loading" signal

unmount ()

the class closure for "unmount" signal

changed ()

the class closure for "changed" signal

removed ()

the class closure for "removed" signal

content_changed ()

the class closure for "content-changed" signal

fs_info ()

the class closure for "fs-info" signal

error ()

the class closure for "error" signal

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.

gf :

GFile file descriptor

Returns :

FmFolder corresponding to gf. [transfer full]

Since 0.1.1


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.

path :

path descriptor for the folder

Returns :

FmFolder corresponding to path. [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.

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.

uri :

URI for the folder

Returns :

FmFolder corresponding to uri. [transfer full]

Since 0.1.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.

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_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.

folder :

folder to retrieve file list

Returns :

list of items that folder currently contains. [transfer none]

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.

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_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.

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.

folder :

folder to retrieve path

Returns :

path of the folder. [transfer none]

Since 1.0.0


fm_folder_is_empty ()

gboolean            fm_folder_is_empty                  (FmFolder *folder);

Checks if folder has no files or subdirectories.

folder :

folder to test

Returns :

TRUE if folder is empty.

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.

folder :

folder to test

Returns :

TRUE if folder is incrementally loaded

Since 1.0.2


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.

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.

folder :

folder to test

Returns :

TRUE if folder describes a valid existing directory.

Since 1.0.0


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.

folder :

folder to retrieve info

Since 0.1.16


fm_folder_reload ()

void                fm_folder_reload                    (FmFolder *folder);

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

folder :

folder to be reloaded

Since 0.1.1

Signal Details

The "changed" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  user_data)      : Run First

The "changed" signal is emitted when the folder itself was changed.

folder :

the monitored directory

user_data :

user data set when the signal handler was connected.

Since 0.1.16


The "content-changed" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  user_data)      : Run First

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

folder :

the monitored directory

user_data :

user data set when the signal handler was connected.

Since 0.1.16


The "error" signal

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

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

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.

Since 0.1.1


The "files-added" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  list,
                                                        gpointer  user_data)      : Run First

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

folder :

the monitored directory

list :

GList of newly added FmFileInfo

user_data :

user data set when the signal handler was connected.

Since 0.1.0


The "files-changed" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  list,
                                                        gpointer  user_data)      : Run First

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

folder :

the monitored directory

list :

GList of FmFileInfo that were changed

user_data :

user data set when the signal handler was connected.

Since 0.1.0


The "files-removed" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  list,
                                                        gpointer  user_data)      : Run First

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

folder :

the monitored directory

list :

GList of FmFileInfo that were deleted

user_data :

user data set when the signal handler was connected.

Since 0.1.0


The "finish-loading" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  user_data)      : Run First

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().

folder :

the monitored directory

user_data :

user data set when the signal handler was connected.

Since 1.0.0


The "fs-info" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  user_data)      : Run First

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

folder :

the monitored directory

user_data :

user data set when the signal handler was connected.

Since 0.1.16


The "removed" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  user_data)      : Run First

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

folder :

the monitored directory

user_data :

user data set when the signal handler was connected.

Since 0.1.16


The "start-loading" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  user_data)      : Run First

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

folder :

the monitored directory

user_data :

user data set when the signal handler was connected.

Since 1.0.0


The "unmount" signal

void                user_function                      (FmFolder *folder,
                                                        gpointer  user_data)      : Run First

The "unmount" signal is emitted when the folder was unmounted.

folder :

the monitored directory

user_data :

user data set when the signal handler was connected.

Since 0.1.1