1/*---------------------------------------------------------------------------*
2 *  PFileSystem.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef __PFILESYSTEM_H
21#define __PFILESYSTEM_H
22
23
24
25#include "ESR_ReturnCode.h"
26#include "PortPrefix.h"
27#include "PFile.h"
28#include "ptypes.h"
29
30/**
31 * @addtogroup PFileSystemModule PFileSystem API functions
32 * Portable file-system API.
33 *
34 * Must call pmemInit() before using this module.
35 * If threads are to be used, ptrdInit() must be called before using this module as well.
36 *
37 * @{
38 */
39
40/**
41 * Portable standard input.
42 */
43/*PORTABLE_API PFile* PSTDIN;*/
44/**
45 * Portable standard output.
46 */
47/*PORTABLE_API PFile* PSTDOUT;*/
48/**
49 * Portable standard error.
50 */
51/*PORTABLE_API PFile* PSTDERR;*/
52
53#define PSTDIN 	stdin
54#define PSTDOUT stdout
55#define PSTDERR stderr
56/**
57 * Portable file-system.
58 */
59typedef struct PFileSystem_t
60{
61  /**
62  * Destroys the PFileSystem.
63  *
64  * @param self PFileSystem handle
65  * @return ESR_INVALID_ARGUMENT if self is null
66  */
67  ESR_ReturnCode(*destroy)(struct PFileSystem_t* self);
68
69  /**
70    * Creates a new PFile using this file-system.
71   *
72   * @param self PFileSystem handle
73   * @param path Fully qualified file path
74   * @param littleEndian True if file is in little-endian format
75   * @param file [out] Resulting PFile
76   */
77  ESR_ReturnCode(*createPFile)(struct PFileSystem_t* self, const LCHAR* path, ESR_BOOL littleEndian, PFile** file);
78
79  /**
80   * Creates a new directory.
81   *
82   * @param self PFileSystem handle
83   * @param path Fully qualified directory path
84    * @return ESR_INVALID_ARGUMENT if path is null; ESR_IDENTIFIER_COLLISION if directory already exists;
85    * ESR_NO_MATCH_ERROR if parent directory does not exist; ESR_INVALID_STATE if an internal error occurs
86   */
87  ESR_ReturnCode(*mkdir)(struct PFileSystem_t* self, const LCHAR* path);
88
89  /**
90   * Sets the current working directory.
91   *
92   * @param self PFileSystem handle
93   * @param path Fully qualified file path
94   * @return ESR_SUCCESS if change of directory is allowed
95   */
96  ESR_ReturnCode(*chdir)(struct PFileSystem_t* self, const LCHAR* path);
97}
98PFileSystem;
99
100
101/**
102 * Initializes the portable file-system module.
103 *
104 * @return ESR_INVALID_STATE if calling StackTraceCreate() fails (see its documentation for more detail).
105 */
106PORTABLE_API ESR_ReturnCode PFileSystemCreate(void);
107
108/**
109 * Indicates if the portable file-system module is initialized.
110 *
111 * @param isCreated [in/out] True if the module is initialized.
112 * @return ESR_INVALID_ARGUMENT if isCreated is null
113 */
114PORTABLE_API ESR_ReturnCode PFileSystemIsCreated(ESR_BOOL* isCreated);
115
116/**
117 * Shuts down the portable file-system module.
118 *
119 * @return ESR_INVALID_ARGUMENT if self is null
120 */
121PORTABLE_API ESR_ReturnCode PFileSystemDestroy(void);
122
123/**
124 * Creates a new PFile using this file-system.
125 *
126 * @param path Fully qualified file path
127 * @param littleEndian True if file is in little-endian format
128 * @param file [out] Resulting PFile
129 * @return ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_STATE if mutex could not be created
130 */
131PORTABLE_API ESR_ReturnCode PFileSystemCreatePFile(const LCHAR* path, ESR_BOOL littleEndian, PFile** file);
132
133/**
134 * Indicates if path is absolute.
135 *
136 * @param path Path to be processed
137 * @param isAbsolute True if path is absolute
138 * @return ESR_INVALID_ARGUMENT if path or isAbsolute are null
139 */
140PORTABLE_API ESR_ReturnCode PFileSystemIsAbsolutePath(const LCHAR* path, ESR_BOOL* isAbsolute);
141
142/**
143 * Returns the canonical pathname string of this abstract pathname.
144 *
145 * A canonical pathname is both absolute and unique. The precise definition of canonical
146 * form is system-dependent. This method first converts this pathname to absolute form.
147 * This typically involves removing redundant names such as "." and ".." from the pathname,
148 * resolving symbolic links (on UNIX platforms), and converting drive letters to
149 * a standard case (on Microsoft Windows platforms).
150 *
151 * POST-CONDITION: Path will contain only canonical slashes
152 *
153 * @param path Path to process
154 * @param len [in/out] Length of path argument. If the return code is ESR_BUFFER_OVERFLOW,
155 *            the required length is returned in this variable.
156 * @return ESR_INVALID_ARGUMENT if path or len are null
157 */
158PORTABLE_API ESR_ReturnCode PFileSystemGetAbsolutePath(LCHAR* path, size_t* len);
159
160/**
161 * Converts all slashes in path to '/'.
162 *
163 * @param path [in/out] Path to process
164 * @return ESR_INVALID_ARGUMENT if path is null
165 */
166PORTABLE_API ESR_ReturnCode PFileSystemCanonicalSlashes(LCHAR* path);
167
168/**
169 * Returns parent directory of specified path.
170 * If the path ends with a filename, its directory is returned.
171 * If the path ends with a directory, its parent directory is returned.
172 *
173 * PRECONDITION: Directory names must end with '/'
174 *
175 * @param path [in/out] Path to process
176 * @param len [in/out] Length of path argument. If the return code is ESR_BUFFER_OVERFLOW,
177 *            the required length is returned in this variable.
178 * @return ESR_INVALID_ARGUMENT if path or len are null; ESR_BUFFER_OVERFLOW if path is too small to contain the result
179 */
180PORTABLE_API ESR_ReturnCode PFileSystemGetParentDirectory(LCHAR* path, size_t* len);
181
182/**
183 * Creates a new directory.
184 *
185 * @param path Directory path
186 * @return ESR_INVALID_ARGUMENT if path is null; ESR_IDENTIFIER_COLLISION if directory already exists;
187 * ESR_NO_MATCH_ERROR if parent directory does not exist; ESR_INVALID_STATE if an internal error occurs
188 */
189PORTABLE_API ESR_ReturnCode PFileSystemMkdir(const LCHAR* path);
190
191/**
192 * Returns the current working directory (always ends with '/').
193 *
194 * @param path [out] The current working directory
195 * @param len [in/out] Length of path argument. If the return code is ESR_BUFFER_OVERFLOW,
196 *            the required length is returned in this variable.
197 * @return ESR_INVALID_ARGUMENT if path or len are null; ESR_BUFFER_OVERFLOW if path is too small to contain the result
198 */
199PORTABLE_API ESR_ReturnCode PFileSystemGetcwd(LCHAR* path, size_t* len);
200
201/**
202 * Sets the current working directory.
203 *
204 * @param path Fully qualified file path
205 * @return ESR_SUCCESS if change of directory is allowed
206 */
207PORTABLE_API ESR_ReturnCode PFileSystemChdir(const LCHAR* path);
208
209/**
210 * Converts a linear path string to an array of path tokens.
211 * Tokens ending with a '/' denote a directory, otherwise they are a file.
212 *
213 * POST-CONDITION: The array is allocated internally, but must be freed by the caller.
214 *
215 * @param path Command-line string to parse
216 * @param tokenArray [out] The array used to hold the tokens
217 * @param count [out] The number of tokens found
218 * @return ESR_INVALID_ARGUMENT if path, tokenArray or count are null; ESR_OUT_OF_MEMORY if system is out of memory
219 */
220PORTABLE_API ESR_ReturnCode PFileSystemLinearToPathTokens(const LCHAR* path, LCHAR*** tokenArray, size_t* count);
221
222/**
223 * @}
224 */
225#endif /* __PFILESYSTEM_H */
226