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 */ 59 typedef 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 } 98 PFileSystem; 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 */ 106 PORTABLE_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 */ 114 PORTABLE_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 */ 121 PORTABLE_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 */ 131 PORTABLE_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 */ 140 PORTABLE_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 */ 158 PORTABLE_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 */ 166 PORTABLE_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 */ 180 PORTABLE_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 */ 189 PORTABLE_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 */ 199 PORTABLE_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 */ 207 PORTABLE_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 */ 220 PORTABLE_API ESR_ReturnCode PFileSystemLinearToPathTokens(const LCHAR* path, LCHAR*** tokenArray, size_t* count); 221 222 /** 223 * @} 224 */ 225 #endif /* __PFILESYSTEM_H */ 226