## ThunarVfsPath

ThunarVfsPath

## Synopsis

    #include <thunar-vfs/thunar-vfs.h>

    enum                ThunarVfsPathScheme;
                        ThunarVfsPath;
    #define             THUNAR_VFS_TYPE_PATH
    #define             THUNAR_VFS_TYPE_PATH_LIST
    ThunarVfsPath *     thunar_vfs_path_new                 (const gchar *identifier,
                                                             GError **error);
    ThunarVfsPath *     thunar_vfs_path_get_for_home        (void);
    ThunarVfsPath *     thunar_vfs_path_get_for_root        (void);
    ThunarVfsPath *     thunar_vfs_path_ref                 (ThunarVfsPath *path);
    void                thunar_vfs_path_unref               (ThunarVfsPath *path);
    guint               thunar_vfs_path_hash                (gconstpointer path_ptr);
    gboolean            thunar_vfs_path_equal               (gconstpointer path_ptr_a,
                                                             gconstpointer path_ptr_b);
    gboolean            thunar_vfs_path_is_ancestor         (const ThunarVfsPath *path,
                                                             const ThunarVfsPath *ancestor);
    gboolean            thunar_vfs_path_is_home             (const ThunarVfsPath *path);
    gboolean            thunar_vfs_path_is_root             (const ThunarVfsPath *path);
    ThunarVfsPath *     thunar_vfs_path_relative            (ThunarVfsPath *parent,
                                                             const gchar *name);
    const gchar *       thunar_vfs_path_get_name            (const ThunarVfsPath *path);
    ThunarVfsPath *     thunar_vfs_path_get_parent          (const ThunarVfsPath *path);
    ThunarVfsPathScheme  thunar_vfs_path_get_scheme         (const ThunarVfsPath *path);
    gchar *             thunar_vfs_path_dup_string          (const ThunarVfsPath *path);
    gssize              thunar_vfs_path_to_string           (const ThunarVfsPath *path,
                                                             gchar *buffer,
                                                             gsize bufsize,
                                                             GError **error);
    gchar *             thunar_vfs_path_dup_uri             (const ThunarVfsPath *path);
    gssize              thunar_vfs_path_to_uri              (const ThunarVfsPath *path,
                                                             gchar *buffer,
                                                             gsize bufsize,
                                                             GError **error);
    GList *             thunar_vfs_path_list_from_string    (const gchar *uri_string,
                                                             GError **error);
    gchar *             thunar_vfs_path_list_to_string      (GList *path_list);
    GList *             thunar_vfs_path_list_append         (GList *path_list,
                                                             ThunarVfsPath *path);
    GList *             thunar_vfs_path_list_prepend        (GList *path_list,
                                                             ThunarVfsPath *path);
    GList *             thunar_vfs_path_list_copy           (GList *path_list);
    void                thunar_vfs_path_list_free           (GList *path_list);

## Description

## Details

### enum ThunarVfsPathScheme

    typedef enum /*< skip >*/
    {
      THUNAR_VFS_PATH_SCHEME_FILE   = 0x00000000,
      THUNAR_VFS_PATH_SCHEME_TRASH  = 0x40000000,
      THUNAR_VFS_PATH_SCHEME_MASK   = 0x40000000,
    } ThunarVfsPathScheme;

The scheme, or the type, of resource a ThunarVfsPath refers to. This currently includes local files which are accessible via standard Unix paths, and trashed files, which are accessible via trash:-URIs.

`THUNAR_VFS_PATH_SCHEME_FILE` | path to local files.
`THUNAR_VFS_PATH_SCHEME_TRASH` | path to files in the trash can.
`THUNAR_VFS_PATH_SCHEME_MASK` | bit mask for path scheme, an implementation detail, should not be used outside ThunarVFS.

Since 0.3.3

### ThunarVfsPath

    typedef struct {
    } ThunarVfsPath;

### THUNAR_VFS_TYPE_PATH

    #define THUNAR_VFS_TYPE_PATH (thunar_vfs_path_get_type ())

Returns : | the type id of the ThunarVfsPath type, which is a boxed type.

### THUNAR_VFS_TYPE_PATH_LIST

    #define THUNAR_VFS_TYPE_PATH_LIST (thunar_vfs_path_list_get_type ())

Returns : | the type id for GLists of ThunarVfsPaths, which is a boxed type.

Since 0.3.3

### thunar_vfs_path_new ()

    ThunarVfsPath *     thunar_vfs_path_new                 (const gchar *identifier,
                                                             GError **error);

Returns a ThunarVfsPath that represents the given `identifier` or `NULL` on error. In the latter case `error` will be set to point to an GError describing the problem.

The caller is responsible to free the returned object using `thunar_vfs_path_unref()` when no longer needed.

`identifier` : | an URI identifier or an absolute path.
`error` : | return location for errors or `NULL`.
Returns : | the ThunarVfsPath for `identifier` or `NULL` on error.

### thunar_vfs_path_get_for_home ()

    ThunarVfsPath *     thunar_vfs_path_get_for_home        (void);

Returns the ThunarVfsPath that represents the current users home directory.

The caller is responsible to free the returned object using `thunar_vfs_path_unref()` when no longer needed.

Returns : | the ThunarVfsPath for the current users home directory.

### thunar_vfs_path_get_for_root ()

    ThunarVfsPath *     thunar_vfs_path_get_for_root        (void);

Returns the ThunarVfsPath that represents the file systems root folder.

The caller is responsible to free the returned object using `thunar_vfs_path_unref()` when no longer needed.

Returns : | the ThunarVfsPath for the file systems root directory.

### thunar_vfs_path_ref ()

    ThunarVfsPath *     thunar_vfs_path_ref                 (ThunarVfsPath *path);

Increments the reference count on `path` and returns a reference to `path`.

`path` : | a ThunarVfsPath.
Returns : | a reference to `path`.

### thunar_vfs_path_unref ()

    void                thunar_vfs_path_unref               (ThunarVfsPath *path);

Decreases the reference count on `path` and frees the resources allocated for `path` once the reference count drops to zero.

`path` : | a ThunarVfsPath.

### thunar_vfs_path_hash ()

    guint               thunar_vfs_path_hash                (gconstpointer path_ptr);

Generates a hash value for the given `path_ptr`.

`path_ptr` : | a ThunarVfsPath.
Returns : | the hash value for `path_ptr`.

### thunar_vfs_path_equal ()

    gboolean            thunar_vfs_path_equal               (gconstpointer path_ptr_a,
                                                             gconstpointer path_ptr_b);

Checks whether `path_ptr_a` and `path_ptr_b` refer to the same local path.

`path_ptr_a` : | first ThunarVfsPath.
`path_ptr_b` : | second ThunarVfsPath.
Returns : | `TRUE` if `path_ptr_a` and `path_ptr_b` are equal.

### thunar_vfs_path_is_ancestor ()

    gboolean            thunar_vfs_path_is_ancestor         (const ThunarVfsPath *path,
                                                             const ThunarVfsPath *ancestor);

Determines whether `path` is somewhere below `ancestor`, possible with intermediate folders.

`path` : | a ThunarVfsPath.
`ancestor` : | another ThunarVfsPath.
Returns : | `TRUE` if `ancestor` contains `path` as a child, grandchild, great grandchild, etc.

### thunar_vfs_path_is_home ()

    gboolean            thunar_vfs_path_is_home             (const ThunarVfsPath *path);

Checks whether `path` refers to the users home directory.

`path` : | a ThunarVfsPath.
Returns : | `TRUE` if `path` refers to the users home directory.

### thunar_vfs_path_is_root ()

    gboolean            thunar_vfs_path_is_root             (const ThunarVfsPath *path);

Checks whether path refers to the root directory.

`path` : | a ThunarVfsPath.
Returns : | `TRUE` if `path` refers to the root directory.

### thunar_vfs_path_relative ()

    ThunarVfsPath *     thunar_vfs_path_relative            (ThunarVfsPath *parent,
                                                             const gchar *name);

Returns a ThunarVfsPath for the file `name` relative to `parent`. `name` must be a valid filename in the local file system encoding and it may not contain any slashes.

The caller is responsible to free the returned object using `thunar_vfs_path_unref()` when no longer needed.

`parent` : | a ThunarVfsPath.
`name` : | a valid filename in the local file system encoding.
Returns : | the path to `name` relative to `parent`.

### thunar_vfs_path_get_name ()

    const gchar *       thunar_vfs_path_get_name            (const ThunarVfsPath *path);

Returns the base name of the `path` in the local file system encoding.

`path` : | a ThunarVfsPath.
Returns : | the base name of `path`.

### thunar_vfs_path_get_parent ()

    ThunarVfsPath *     thunar_vfs_path_get_parent          (const ThunarVfsPath *path);

Returns the ThunarVfsPath that refers to the parent directory of `path` or `NULL` if `path` refers to the root file system node.

No additional reference is taken on the parent, so you'll need to call `thunar_vfs_path_ref()` yourself if you need to keep a reference.

`path` : | a ThunarVfsPath.
Returns : | the parent of `path` or `NULL`.

### thunar_vfs_path_get_scheme ()

    ThunarVfsPathScheme  thunar_vfs_path_get_scheme         (const ThunarVfsPath *path);

Returns the ThunarVfsPathScheme of the specified `path`.

`path` : | a ThunarVfsPath.
Returns : | the scheme of the `path`.

Since 0.3.3

### thunar_vfs_path_dup_string ()

    gchar *             thunar_vfs_path_dup_string          (const ThunarVfsPath *path);

Like `thunar_vfs_path_to_string()`, this function transform the `path` to its string representation, but unlike `thunar_vfs_path_to_string()`, this function automatically allocates the required amount of memory from the heap. The returned string must be freed by the caller when no longer needed.

`path` : | a ThunarVfsPath.
Returns : | the string representation of `path`.

### thunar_vfs_path_to_string ()

    gssize              thunar_vfs_path_to_string           (const ThunarVfsPath *path,
                                                             gchar *buffer,
                                                             gsize bufsize,
                                                             GError **error);

Stores the `path` into the string pointed to by `buffer`, so it can be used for system path operations. Returns the number of bytes stored to `buffer` or a negative value if `bufsize` is too small to store the whole `path`. In the latter case `error` will be set to point to an error describing the problem.

If `buffer` is allocated on the stack, it is suggested to use THUNAR_VFS_PATH_MAXSTRLEN for the buffer size in most cases. The stack should never be used in recursive functions; use `thunar_vfs_path_dup_string()` instead there.

`path` : | a ThunarVfsPath.
`buffer` : | the buffer to store the path string to.
`bufsize` : | the size of `buffer` in bytes.
`error` : | return location for errors or `NULL`.
Returns : | the number of bytes (including the null byte) stored to `buffer` or a negative value if `buffer` cannot hold the whole `path`.

### thunar_vfs_path_dup_uri ()

    gchar *             thunar_vfs_path_dup_uri             (const ThunarVfsPath *path);

Similar to `thunar_vfs_path_to_uri()`, but automatically allocates memory on the heap instead of using a user supplied buffer for the URI.

The caller is responsible to free the returned string using `g_free()` when no longer needed.

`path` : | a ThunarVfsPath.
Returns : | the escaped URI for `path`.

### thunar_vfs_path_to_uri ()

    gssize              thunar_vfs_path_to_uri              (const ThunarVfsPath *path,
                                                             gchar *buffer,
                                                             gsize bufsize,
                                                             GError **error);

Escapes `path` according to the rules of the file URI specification and stores the escaped URI to `buffer`. Returns the number of bytes stored to `buffer` or a negative value if `bufsize` is too small to store the escaped URI. In the latter case `error` will be set to point to an GError describing the problem.

When using the stack for `buffer`, it is suggested to use THUNAR_VFS_PATH_MAXURILEN for the buffer size in most cases. The stack should never be used in recursive functions; use `thunar_vfs_path_dup_uri()` instead there.

`path` : | a ThunarVfsPath.
`buffer` : | the buffer to store the URI string to.
`bufsize` : | the size of `buffer` in bytes.
`error` : | return location for errors or `NULL`.
Returns : | the number of bytes (including the null byte) stored to `buffer` or a negative value if `buffer` cannot hold the URI.

### thunar_vfs_path_list_from_string ()

    GList *             thunar_vfs_path_list_from_string    (const gchar *uri_string,
                                                             GError **error);

Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments and whitespace.

If all URIs were successfully parsed into ThunarVfsPath objects, the list of parsed URIs will be returned, and you'll need to call `thunar_vfs_path_list_free()` to release the list resources. Else if the parsing fails at some point, `NULL` will be returned and `error` will be set to describe the cause.

Note, that if `string` contains no URIs, this function will also return `NULL`, but `error` won't be set. So take care when checking for an error condition!

`uri_string` : | a string representation of an URI list.
`error` : | return location for errors.
Returns : | the list of ThunarVfsPath's or `NULL`.

### thunar_vfs_path_list_to_string ()

    gchar *             thunar_vfs_path_list_to_string      (GList *path_list);

Free the returned value using `g_free()` when you are done with it.

`path_list` : | a list of ThunarVfsPaths.
Returns : | the string representation of `path_list` conforming to the text/uri-list mime type defined in RFC 2483.

### thunar_vfs_path_list_append ()

    GList *             thunar_vfs_path_list_append         (GList *path_list,
                                                             ThunarVfsPath *path);

Appends `path` to the `path_list` while taking an additional reference for `path`.

`path_list` : | a list of ThunarVfsPaths.
`path` : | a ThunarVfsPath.
Returns : | pointer to the extended `path_list`.

### thunar_vfs_path_list_prepend ()

    GList *             thunar_vfs_path_list_prepend        (GList *path_list,
                                                             ThunarVfsPath *path);

Similar to `thunar_vfs_path_list_append()`, but prepends the `path` to the `path_list`.

`path_list` : | a list of ThunarVfsPaths.
`path` : | a ThunarVfsPath.
Returns : | pointer to the extended `path_list`.

### thunar_vfs_path_list_copy ()

    GList *             thunar_vfs_path_list_copy           (GList *path_list);

Takes a deep copy of `path_list` and returns the result. The caller is responsible to free the returned list using `thunar_vfs_path_list_free()`.

`path_list` : | a list of ThunarVfsPaths.
Returns : | a deep copy of `path_list`.

### thunar_vfs_path_list_free ()

    void                thunar_vfs_path_list_free           (GList *path_list);

Frees the ThunarVfsPaths in `path_list` and the `path_list` itself.

`path_list` : | a list of ThunarVfsPaths.