FmPath

FmPath — Path representation for libfm.

Synopsis

#define             FM_PATH                             (path)
                    FmFileInfoList;
                    FmPath;
enum                FmPathFlags;
                    FmPathList;
int                 fm_path_compare                     (FmPath *p1,
                                                         FmPath *p2);
int                 fm_path_depth                       (FmPath *path);
char *              fm_path_display_basename            (FmPath *path);
char *              fm_path_display_name                (FmPath *path,
                                                         gboolean human_readable);
gboolean            fm_path_equal                       (FmPath *p1,
                                                         FmPath *p2);
gboolean            fm_path_equal_str                   (FmPath *path,
                                                         const gchar *str,
                                                         int n);
FmPath *            fm_path_get_apps_menu               (void);
const char *        fm_path_get_basename                (FmPath *path);
FmPath *            fm_path_get_desktop                 (void);
FmPathFlags         fm_path_get_flags                   (FmPath *path);
FmPath *            fm_path_get_home                    (void);
FmPath *            fm_path_get_parent                  (FmPath *path);
FmPath *            fm_path_get_root                    (void);
FmPath *            fm_path_get_trash                   (void);
gboolean            fm_path_has_prefix                  (FmPath *path,
                                                         FmPath *prefix);
guint               fm_path_hash                        (FmPath *path);
#define             fm_path_is_local                    (path)
#define             fm_path_is_native                   (path)
#define             fm_path_is_trash                    (path)
#define             fm_path_is_trash_root               (path)
#define             fm_path_is_virtual                  (path)
#define             fm_path_is_xdg_menu                 (path)
FmPathList *        fm_path_list_new                    (void);
FmPathList *        fm_path_list_new_from_file_info_glist
                                                        (GList *fis);
FmPathList *        fm_path_list_new_from_file_info_gslist
                                                        (GSList *fis);
FmPathList *        fm_path_list_new_from_file_info_list
                                                        (FmFileInfoList *fis);
FmPathList *        fm_path_list_new_from_uri_list      (const char *uri_list);
FmPathList *        fm_path_list_new_from_uris          (char * const*uris);
char *              fm_path_list_to_uri_list            (FmPathList *pl);
void                fm_path_list_write_uri_list         (FmPathList *pl,
                                                         GString *buf);
FmPath *            fm_path_new_child                   (FmPath *parent,
                                                         const char *basename);
FmPath *            fm_path_new_child_len               (FmPath *parent,
                                                         const char *basename,
                                                         int name_len);
FmPath *            fm_path_new_for_commandline_arg     (const char *arg);
FmPath *            fm_path_new_for_display_name        (const char *path_name);
FmPath *            fm_path_new_for_gfile               (GFile *gf);
FmPath *            fm_path_new_for_path                (const char *path_name);
FmPath *            fm_path_new_for_str                 (const char *path_str);
FmPath *            fm_path_new_for_uri                 (const char *uri);
FmPath *            fm_path_new_relative                (FmPath *parent,
                                                         const char *rel);
FmPath *            fm_path_ref                         (FmPath *path);
GFile *             fm_path_to_gfile                    (FmPath *path);
char *              fm_path_to_str                      (FmPath *path);
char *              fm_path_to_uri                      (FmPath *path);
void                fm_path_unref                       (FmPath *path);

Description

include: libfm/fm-path.h

Details

FM_PATH()

#define FM_PATH(path)   ((FmPath*)path)

FmFileInfoList

typedef struct _FmFileInfoList FmFileInfoList;

FmPath

typedef struct _FmPath FmPath;

enum FmPathFlags

typedef enum {
    FM_PATH_NONE = 0,
    FM_PATH_IS_NATIVE = 1<<0,
    FM_PATH_IS_LOCAL = 1<<1,
    FM_PATH_IS_VIRTUAL = 1<<2,
    FM_PATH_IS_TRASH = 1<<3,
    FM_PATH_IS_XDG_MENU = 1<<4,
} FmPathFlags;

Flags of FmPath object.

FM_PATH_IS_VIRTUAL and FM_PATH_IS_XDG_MENU are deprecated since 1.0.2 and should not be used in newly written code.

FM_PATH_NONE

-

FM_PATH_IS_NATIVE

This is a native path to UNIX, like /home

FM_PATH_IS_LOCAL

This path refers to a file on local filesystem

FM_PATH_IS_VIRTUAL

This path is virtual and it doesn't exist on real filesystem

FM_PATH_IS_TRASH

This path is under trash:///

FM_PATH_IS_XDG_MENU

This path is under menu:///

FmPathList

typedef struct _FmPathList FmPathList;

fm_path_compare ()

int                 fm_path_compare                     (FmPath *p1,
                                                         FmPath *p2);

fm_path_depth ()

int                 fm_path_depth                       (FmPath *path);

Calculates how many elements are in this path.

path :

a path

Returns :

TRUE if paths are equal.

Since 1.0.0


fm_path_display_basename ()

char *              fm_path_display_basename            (FmPath *path);

Creates displayable basename of path.

path :

a path

Returns :

displayable basename of path.

Since 0.1.0


fm_path_display_name ()

char *              fm_path_display_name                (FmPath *path,
                                                         gboolean human_readable);

Creates string representation of path as displayable name. The conversion is the most probably unreversible so returned value should be used only for displaying purposes.

path :

a path

human_readable :

TRUE to generate simple text

Returns :

path string. [transfer full]

Since 0.1.0


fm_path_equal ()

gboolean            fm_path_equal                       (FmPath *p1,
                                                         FmPath *p2);

Compares two paths and returns TRUE if they are equal.

Note that this function is primarily meant as a hash table comparison function.

See also: fm_path_compare().

p1 :

first path

p2 :

second path

Returns :

TRUE if paths are equal.

Since 0.1.0


fm_path_equal_str ()

gboolean            fm_path_equal_str                   (FmPath *path,
                                                         const gchar *str,
                                                         int n);

Compares path string representation with string.

path :

a path

str :

a string

n :

length of string

Returns :

TRUE if path and string are equal.

Since 0.1.0


fm_path_get_apps_menu ()

FmPath *            fm_path_get_apps_menu               (void);

Retrieves FmPath for menu:// virtual directory. Returned data are owned by path and should be not freed by caller.

Returns :

a path.

Since 0.1.0


fm_path_get_basename ()

const char *        fm_path_get_basename                (FmPath *path);

Retrieves basename of path. Returned data are owned by path and should be not freed by caller.

path :

a path

Returns :

basename of path.

Since 0.1.0


fm_path_get_desktop ()

FmPath *            fm_path_get_desktop                 (void);

Retrieves FmPath for desktop directory. Returned data are owned by path and should be not freed by caller.

Returns :

a path.

Since 0.1.0


fm_path_get_flags ()

FmPathFlags         fm_path_get_flags                   (FmPath *path);

Retrieves attributes of path.

path :

a path

Returns :

attributes of path.

Since 0.1.0


fm_path_get_home ()

FmPath *            fm_path_get_home                    (void);

Retrieves FmPath for home directory. Returned data are owned by path and should be not freed by caller.

Returns :

a path.

Since 0.1.0


fm_path_get_parent ()

FmPath *            fm_path_get_parent                  (FmPath *path);

Retrieves path of directory containing path. Returned data are owned by path and should be not freed by caller.

path :

a path

Returns :

path of parent directory or NULL if path is root path. [transfer none]

Since 0.1.0


fm_path_get_root ()

FmPath *            fm_path_get_root                    (void);

Retrieves FmPath for root directory. Returned data are owned by path and should be not freed by caller.

Returns :

a path.

Since 0.1.0


fm_path_get_trash ()

FmPath *            fm_path_get_trash                   (void);

Retrieves FmPath for Trash can. Returned data are owned by path and should be not freed by caller.

Returns :

a path.

Since 0.1.0


fm_path_has_prefix ()

gboolean            fm_path_has_prefix                  (FmPath *path,
                                                         FmPath *prefix);

Check if prefix is a prefix of path. For example: /usr/share is the prefix of /usr/share/docs/libfm but /etc is not.

path :

a sub path

prefix :

a prefix

Returns :

TRUE if prefix is the prefix of path.

fm_path_hash ()

guint               fm_path_hash                        (FmPath *path);

Converts a path to a hash value.

path :

a path key

Returns :

a hash value corresponding to the key.

Since 0.1.0


fm_path_is_local()

#define fm_path_is_local(path) ((fm_path_get_flags(path)&FM_PATH_IS_LOCAL)!=0)

fm_path_is_native()

#define fm_path_is_native(path) ((fm_path_get_flags(path)&FM_PATH_IS_NATIVE)!=0)

fm_path_is_trash()

#define fm_path_is_trash(path) ((fm_path_get_flags(path)&FM_PATH_IS_TRASH)!=0)

fm_path_is_trash_root()

#define fm_path_is_trash_root(path) (path == fm_path_get_trash())

fm_path_is_virtual()

#define fm_path_is_virtual(path) ((fm_path_get_flags(path)&FM_PATH_IS_VIRTUAL)!=0)

Warning

fm_path_is_virtual is deprecated and should not be used in newly-written code.


fm_path_is_xdg_menu()

#define fm_path_is_xdg_menu(path) ((fm_path_get_flags(path)&FM_PATH_IS_XDG_MENU)!=0)

Warning

fm_path_is_xdg_menu is deprecated and should not be used in newly-written code.


fm_path_list_new ()

FmPathList *        fm_path_list_new                    (void);

fm_path_list_new_from_file_info_glist ()

FmPathList *        fm_path_list_new_from_file_info_glist
                                                        (GList *fis);

Creates a FmPathList from fis.

fis :

list of file infos. [element-type FmFileInfo]

Returns :

new FmPathList. [transfer full]

Since 0.1.0


fm_path_list_new_from_file_info_gslist ()

FmPathList *        fm_path_list_new_from_file_info_gslist
                                                        (GSList *fis);

Creates a FmPathList from fis.

fis :

list of file infos. [element-type FmFileInfo]

Returns :

new FmPathList. [transfer full]

Since 0.1.0


fm_path_list_new_from_file_info_list ()

FmPathList *        fm_path_list_new_from_file_info_list
                                                        (FmFileInfoList *fis);

Creates a FmPathList from fis.

fis :

a file info list

Returns :

new FmPathList. [transfer full]

Since 0.1.0


fm_path_list_new_from_uri_list ()

FmPathList *        fm_path_list_new_from_uri_list      (const char *uri_list);

Creates a FmPathList from uri_list.

uri_list :

list of URIs separated by newline characters

Returns :

new FmPathList. [transfer full]

Since 0.1.0


fm_path_list_new_from_uris ()

FmPathList *        fm_path_list_new_from_uris          (char * const*uris);

Creates a FmPathList from uris.

uris :

NULL-terminated list of URIs

Returns :

new FmPathList. [transfer full]

Since 0.1.0


fm_path_list_to_uri_list ()

char *              fm_path_list_to_uri_list            (FmPathList *pl);

Creates newline-separated list from pl. Returned data should be freed with g_free() after usage.

pl :

a path list

Returns :

string representation of pl. [transfer full]

Since 0.1.0


fm_path_list_write_uri_list ()

void                fm_path_list_write_uri_list         (FmPathList *pl,
                                                         GString *buf);

Creates newline-separated list of URIs from pl.

pl :

a path list

buf :

a storage for resulting list. [out]

Since 0.1.0


fm_path_new_child ()

FmPath *            fm_path_new_child                   (FmPath *parent,
                                                         const char *basename);

Creates new FmPath for child of parent directory which have name basename. basename is in glib filename encoding (can be non-UTF-8) of target filesystem.

parent :

a parent path. [allow-none]

basename :

basename of a direct child of parent directory. [allow-none]

Returns :

a new FmPath for the path. You have to call fm_path_unref() when it's no longer needed. [transfer full]

fm_path_new_child_len ()

FmPath *            fm_path_new_child_len               (FmPath *parent,
                                                         const char *basename,
                                                         int name_len);

Creates new FmPath for child of parent directory which have name basename. The string length of basename is name_len. basename is in glib filename encoding (can be non-UTF-8) of target filesystem. If parent is NULL then basename assumed to be root of some file system.

parent :

a parent path. [allow-none]

basename :

basename of a direct child of parent directory. [allow-none]

name_len :

length of basename

Returns :

a new FmPath for the path. You have to call fm_path_unref() when it's no longer needed. [transfer full]

fm_path_new_for_commandline_arg ()

FmPath *            fm_path_new_for_commandline_arg     (const char *arg);

arg :

a file path passed in command line argv to the program. The arg can be a POSIX path in glib filename encoding (can be non-UTTF-8) and can be a URI with non-ASCII characters escaped, like http://wiki.lxde.org/zh/%E9%A6%96%E9%A0%81.

Returns :

a newly created FmPath for the path. You have to call fm_path_unref() when it's no longer needed.

fm_path_new_for_display_name ()

FmPath *            fm_path_new_for_display_name        (const char *path_name);

Warning

fm_path_new_for_display_name is deprecated and should not be used in newly-written code.

You can call fm_path_display_name() to convert a FmPath to a UTF-8 encoded name ready for being displayed in the GUI.

path_name :

a UTF-8 encoded display name for the path It can either be a POSIX path in UTF-8 encoding, or an unescaped URI (can contain non-ASCII characters and spaces)

Returns :

a newly created FmPath for the path. You have to call fm_path_unref() when it's no longer needed.

fm_path_new_for_gfile ()

FmPath *            fm_path_new_for_gfile               (GFile *gf);

This function converts a GFile object to FmPath.

gf :

a GFile object

Returns :

a newly created FmPath for the path. You have to call fm_path_unref() when it's no longer needed.

fm_path_new_for_path ()

FmPath *            fm_path_new_for_path                (const char *path_name);

path_name :

a POSIX path. [allow-none]

Returns :

a newly created FmPath for the path. You have to call fm_path_unref() when it's no longer needed.

fm_path_new_for_str ()

FmPath *            fm_path_new_for_str                 (const char *path_str);

You can call fm_path_to_str() to convert a FmPath back to its string presentation.

path_str :

a string representing the file path in its native encoding (can be non-UTF-8). It can either be a native path or an unescaped URI (can contain non-ASCII characters and spaces). The function will try to figure out what to do. [allow-none]

Returns :

a newly created FmPath for the path. You have to call fm_path_unref() when it's no longer needed.

fm_path_new_for_uri ()

FmPath *            fm_path_new_for_uri                 (const char *uri);

Creates new FmPath by given uri. You have to call fm_path_unref() when it's no longer needed.

You can call fm_path_to_uri() to convert a FmPath to a escaped URI string.

uri :

a URI with special characters escaped. [allow-none]

Returns :

a new FmPath for the uri. [transfer full]

fm_path_new_relative ()

FmPath *            fm_path_new_relative                (FmPath *parent,
                                                         const char *rel);

Creates new FmPath which is relative to parent directory by the relative path string rel. rel is in glib filename encoding (can be non-UTF-8) if parent is native and should be escaped URI subpath otherwise. For example, if parent is "http://wiki.lxde.org/" and rel is "zh/%E9%A6%96%E9%A0%81", the resulting path will be "http://wiki.lxde.org/zh/%E9%A6%96%E9%A0%81".

If parent is NULL, this works the same as fm_path_new_for_str(rel)

parent :

a parent path. [allow-none]

rel :

a path relative to parent. [allow-none]

Returns :

a new FmPath for the path. You have to call fm_path_unref() when it's no longer needed. [transfer full]

fm_path_ref ()

FmPath *            fm_path_ref                         (FmPath *path);

Increases reference count on path.

path :

an existing FmPath

Returns :

path.

fm_path_to_gfile ()

GFile *             fm_path_to_gfile                    (FmPath *path);

Creates GFile representation of path.

path :

a path

Returns :

a GFile object. [transfer full]

Since 0.1.0


fm_path_to_str ()

char *              fm_path_to_str                      (FmPath *path);

Creates string representation of path. It can be either file path in local encoding or URI with non-ASCII characters escaped (RFC 3986).

path :

a path

Returns :

path string. [transfer full]

Since 0.1.0


fm_path_to_uri ()

char *              fm_path_to_uri                      (FmPath *path);

Creates URI representation of path.

path :

a path

Returns :

path URI.

Since 0.1.0


fm_path_unref ()

void                fm_path_unref                       (FmPath *path);

Decreases reference count on path. When reference count becomes 0 the path will be destroyed.

path :

an existing FmPath