FmPath

FmPath — Path representation for libfm.

Functions

#define FM_PATH()
int fm_path_compare ()
int fm_path_depth ()
char * fm_path_display_basename ()
char * fm_path_display_name ()
gboolean fm_path_equal ()
gboolean fm_path_equal_str ()
FmPath * fm_path_get_apps_menu ()
const char * fm_path_get_basename ()
FmPath * fm_path_get_desktop ()
FmPathFlags fm_path_get_flags ()
FmPath * fm_path_get_home ()
FmPath * fm_path_get_parent ()
FmPath * fm_path_get_root ()
FmPath * fm_path_get_scheme_path ()
FmPath * fm_path_get_trash ()
gboolean fm_path_has_prefix ()
guint fm_path_hash ()
#define fm_path_is_local()
#define fm_path_is_native()
#define fm_path_is_native_or_trash()
#define fm_path_is_trash()
#define fm_path_is_trash_root()
#define fm_path_is_virtual()
#define fm_path_is_xdg_menu()
FmPathList * fm_path_list_new ()
FmPathList * fm_path_list_new_from_file_info_glist ()
FmPathList * fm_path_list_new_from_file_info_gslist ()
FmPathList * fm_path_list_new_from_file_info_list ()
FmPathList * fm_path_list_new_from_uri_list ()
FmPathList * fm_path_list_new_from_uris ()
char * fm_path_list_to_uri_list ()
void fm_path_list_write_uri_list ()
FmPath * fm_path_new_child ()
FmPath * fm_path_new_child_len ()
FmPath * fm_path_new_for_commandline_arg ()
FmPath * fm_path_new_for_display_name ()
FmPath * fm_path_new_for_gfile ()
FmPath * fm_path_new_for_path ()
FmPath * fm_path_new_for_str ()
FmPath * fm_path_new_for_uri ()
FmPath * fm_path_new_relative ()
FmPath * fm_path_ref ()
GFile * fm_path_to_gfile ()
char * fm_path_to_str ()
char * fm_path_to_uri ()
void fm_path_unref ()

Types and Values

Description

include : libfm/fm.h

Functions

FM_PATH()

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

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.

Parameters

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 . If path is a scheme root path (i.e. "/", "sftp://", etc.) then returns basename of path . For other paths displayable basename may be reliable only if there was already FmFileInfo retrieved for the path , otherwise some estimation will be done instead, be careful with this API. Returned data should be freed with g_free() after usage.

See also: fm_file_info_get_disp_name().

Parameters

path

a path

 

Returns

displayable basename of path.

[transfer full]

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 UTF-8 string. The conversion is the most probably unreversible so returned value should be used only for displaying purposes. The displayable path may be reliable only if there was already FmFileInfo retrieved for the path , otherwise some estimation will be returned instead, be careful with this API. The main purpose for this API is to create displayable path for the path entry. Applications are encouraged to use g_file_get_parse_name() instead for any other purposes. Returned data should be freed with g_free() after usage.

See also: fm_path_display_basename(), fm_path_to_str().

Parameters

path

a path

 

human_readable

ignored since 1.2.0

 

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

Parameters

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 .

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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

FmPath *
fm_path_get_scheme_path (FmPath *path);

Retrieves a root path for scheme used by path . If path is a local path then returned data are the same as returned with fm_path_get_root(). Returned data are owned by path and should be not freed by caller.

Parameters

path

a path

 

Returns

path of root of path scheme.

[transfer none]

Since: 1.2.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.

Parameters

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.

Parameters

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_local is deprecated and should not be used in newly-written code.


fm_path_is_native()

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

fm_path_is_native_or_trash()

#define fm_path_is_native_or_trash(path) ((fm_path_get_flags(path)&(FM_PATH_IS_NATIVE|FM_PATH_IS_TRASH))!=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)

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)

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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);

Parameters

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);

The path_name can either be a POSIX path in UTF-8 encoding, or an unescaped URI (can contain non-ASCII characters and spaces). Returned data should be freed with fm_path_unref() when it's no longer needed. Display name may be fully unrelated to it's path name and built path may be inexistant. Use FmJob to check and validate its existance.

Parameters

path_name

an UTF-8 encoded display path name

 

Returns

a newly created FmPath.

Since: 0.1.14


fm_path_new_for_gfile ()

FmPath *
fm_path_new_for_gfile (GFile *gf);

This function converts a GFile object to FmPath.

Parameters

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);

Parameters

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.

Parameters

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.

This function never fail but it may return root path if URI is local and contains illegal characters in path elements such as '/'.

Parameters

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 )

Parameters

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 .

Parameters

path

an existing FmPath

 

Returns

path .


fm_path_to_gfile ()

GFile *
fm_path_to_gfile (FmPath *path);

Creates GFile representation of path . Returned data should be freed with g_object_unref() after usage.

Parameters

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). Returned data should be freed with g_free() after usage.

Parameters

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 . Returned data should be freed with g_free() after usage.

Parameters

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.

Parameters

path

an existing FmPath

 

Types and Values

FmFileInfoList

typedef struct _FmFileInfoList FmFileInfoList;

FmPath

typedef struct _FmPath FmPath;

enum FmPathFlags

Flags of FmPath object.

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

Members

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;