source: trunk/libtransmission/file.h @ 14314

Last change on this file since 14314 was 14314, checked in by jordan, 8 years ago

(trunk, libT) mike.dld's 4160-02a-path.patch: portability wrapper around file paths.

File size: 6.3 KB
Line 
1/*
2 * This file Copyright (C) 2013-2014 Mnemosyne LLC
3 *
4 * It may be used under the GNU GPL versions 2 or 3
5 * or any future license endorsed by Mnemosyne LLC.
6 *
7 * $Id$
8 */
9
10#ifndef TR_FILE_H
11#define TR_FILE_H
12
13#include <inttypes.h>
14#include <time.h>
15
16#ifdef WIN32
17 #include <windows.h>
18#endif
19
20#include "error.h"
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26/**
27 * @addtogroup file_io File IO
28 * @{
29 */
30
31typedef enum
32{
33    TR_SYS_PATH_NO_FOLLOW = 1 << 0
34}
35tr_sys_path_get_info_flags_t;
36
37typedef enum
38{
39  TR_SYS_PATH_IS_FILE,
40  TR_SYS_PATH_IS_DIRECTORY,
41  TR_SYS_PATH_IS_OTHER
42}
43tr_sys_path_type_t;
44
45typedef struct tr_sys_path_info
46{
47  tr_sys_path_type_t type;
48  uint64_t           size;
49  time_t             last_modified_at;
50}
51tr_sys_path_info;
52
53/**
54 * @name Platform-specific wrapper functions
55 *
56 * Following functions accept paths in UTF-8 encoding and convert them to native
57 * encoding internally if needed.
58 *
59 * @{
60 */
61
62/* Path-related wrappers */
63
64/**
65 * @brief Portability wrapper for `stat ()`.
66 *
67 * @param[in]  path  Path to file or directory.
68 * @param[in]  flags Combination of @ref tr_sys_path_get_info_flags_t values.
69 * @param[out] info  Result buffer.
70 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
71 *                   not interested in error details.
72 *
73 * @return `True` on success, `false` otherwise (with `error` set accordingly).
74 */
75bool            tr_sys_path_get_info        (const char         * path,
76                                             int                  flags,
77                                             tr_sys_path_info   * info,
78                                             tr_error          ** error);
79
80/**
81 * @brief Portability wrapper for `access ()`.
82 *
83 * @param[in]  path  Path to file or directory.
84 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
85 *                   not interested in error details.
86 *
87 * @return `True` if path exists, `false` otherwise. Note that `false` will also
88 *         be returned in case of error; if you need to distinguish the two,
89 *         check if `error` is `NULL` afterwards.
90 */
91bool            tr_sys_path_exists          (const char         * path,
92                                             tr_error          ** error);
93
94/**
95 * @brief Test to see if the two filenames point to the same file.
96 *
97 * @param[in]  path1  Path to first file or directory.
98 * @param[in]  path2  Path to second file or directory.
99 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
100 *                   not interested in error details.
101 *
102 * @return `True` if two paths point to the same file or directory, `false`
103 *         otherwise. Note that `false` will also be returned in case of error;
104 *         if you need to distinguish the two, check if `error` is `NULL`
105 *         afterwards.
106 */
107bool            tr_sys_path_is_same         (const char         * path1,
108                                             const char         * path2,
109                                             tr_error          ** error);
110
111/**
112 * @brief Portability wrapper for `realpath ()`.
113 *
114 * @param[in]  path  Path to file or directory.
115 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
116 *                   not interested in error details.
117 *
118 * @return Pointer to newly allocated buffer containing full path (with symbolic
119 *         links, `.` and `..` resolved) on success (use @ref tr_free to free it
120 *         when no longer needed), `NULL` otherwise (with `error` set
121 *         accordingly).
122 */
123char          * tr_sys_path_resolve         (const char         * path,
124                                             tr_error          ** error);
125
126/**
127 * @brief Portability wrapper for `basename ()`.
128 *
129 * @param[in]  path  Path to file or directory.
130 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
131 *                   not interested in error details.
132 *
133 * @return Pointer to newly allocated buffer containing base name (last path
134 *         component; parent path removed) on success (use @ref tr_free to free
135 *         it when no longer needed), `NULL` otherwise (with `error` set
136 *         accordingly).
137 */
138char          * tr_sys_path_basename        (const char         * path,
139                                             tr_error          ** error);
140
141/**
142 * @brief Portability wrapper for `dirname ()`.
143 *
144 * @param[in]  path  Path to file or directory.
145 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
146 *                   not interested in error details.
147 *
148 * @return Pointer to newly allocated buffer containing directory (parent path;
149 *         last path component removed) on success (use @ref tr_free to free it
150 *         when no longer needed), `NULL` otherwise (with `error` set
151 *         accordingly).
152 */
153char          * tr_sys_path_dirname         (const char         * path,
154                                             tr_error          ** error);
155
156/**
157 * @brief Portability wrapper for `rename ()`.
158 *
159 * @param[in]  src_path Path to source file or directory.
160 * @param[in]  dst_path Path to destination file or directory.
161 * @param[out] error    Pointer to error object. Optional, pass `NULL` if you
162 *                      are not interested in error details.
163 *
164 * @return `True` on success, `false` otherwise (with `error` set accordingly).
165 *         Rename will generally only succeed if both source and destination are
166 *         on the same partition.
167 */
168bool            tr_sys_path_rename          (const char         * src_path,
169                                             const char         * dst_path,
170                                             tr_error          ** error);
171
172/**
173 * @brief Portability wrapper for `remove ()`.
174 *
175 * @param[in]  path  Path to file or directory.
176 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
177 *                   not interested in error details.
178 *
179 * @return `True` on success, `false` otherwise (with `error` set accordingly).
180 *         Directory removal will only succeed if it is empty (contains no other
181 *         files and directories).
182 */
183bool            tr_sys_path_remove          (const char         * path,
184                                             tr_error          ** error);
185
186/** @} */
187/** @} */
188
189#ifdef __cplusplus
190}
191#endif
192
193#endif
Note: See TracBrowser for help on using the repository browser.