1 /*---------------------------------------------------------------------------* 2 * PANSIFileSystem.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 __PANSIFILESYSTEM_H 21 #define __PANSIFILESYSTEM_H 22 23 24 25 #include "ESR_ReturnCode.h" 26 #include "PortPrefix.h" 27 #include "PFileSystem.h" 28 #include "ptypes.h" 29 30 /** 31 * @addtogroup PANSIFileSystemModule PANSIFileSystem 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 * NOTE: It is technically impossible to provide a cross-platform version of scanf() and its 38 * variants (since vscanf() does not exist). As a result, this module does not provide this 39 * functionality. End-users are encourages to do their own parsing. 40 * 41 * @{ 42 */ 43 44 /** 45 * Portable ANSI file-system. 46 */ 47 typedef struct PANSIFileSystem_t 48 { 49 /** 50 * Superinterface. 51 */ 52 PFileSystem super; 53 54 /** 55 * Mounts an ANSI path. 56 * 57 * For example, if "c:/" is mounted as "/dev/c", then any file referenced under "/dev/c" will access 58 * "c:/" under the hood. 59 * 60 * @param self PFileSystem handle 61 * @param virtualPath PFileSystem path 62 * @param realPath ANSI path 63 * @return ESR_INVALID_ARGUMENT if self or virtualPath or realPath is null or realPath is not a valid path; 64 * ESR_OUT_OF_MEMORY if the system is out of memory; ESR_IDENTIFIER_COLLISION if virtualPath is already mounted. 65 */ 66 ESR_ReturnCode(*addPath)(PFileSystem* self, const LCHAR* virtualPath, const LCHAR* realPath); 67 68 /** 69 * Deassociates the file-system from a base path. 70 * 71 * @param self PFileSystem handle 72 * @param virtualPath PFileSystem path 73 * @return ESR_INVALID_ARGUMENT if self or virtualPath is null or virtualPath is not mounted 74 */ 75 ESR_ReturnCode(*removePath)(PFileSystem* self, const LCHAR* virtualPath); 76 /** 77 * Returns the current working directory from the operating-system's point of view. 78 * This differs from PFileSystemGetcwd() in that the latter returns the current working 79 * directory on the virtual file-system while this function returns the native working directory. 80 * 81 * @param self PFileSystem handle 82 * @param cwd [out] Current working directory 83 * @param len [in/out] Length of path argument. If the return code is ESR_BUFFER_OVERFLOW, 84 * the required length is returned in this variable. 85 * @return ESR_INVALID_ARGUMENT if self or cwd is null; ESR_BUFFER_OVERFLOW if cwd is not large enough to contain result; 86 * ESR_INVALID_STATE if operating-system returns unexpected value. 87 */ 88 ESR_ReturnCode(*getcwd)(PFileSystem* self, LCHAR* cwd, size_t* len); 89 } 90 PANSIFileSystem; 91 92 /** 93 * Initializes the ANSI file-system module. 94 * 95 * @return ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_STATE if mutex could not be created or if this 96 * function is called after the Ptrd module has been shut down. 97 */ 98 PORTABLE_API ESR_ReturnCode PANSIFileSystemCreate(void); 99 100 /** 101 * Shuts down the ANSI file-system module. 102 * 103 * @return ESR_SUCCESS 104 */ 105 PORTABLE_API ESR_ReturnCode PANSIFileSystemDestroy(void); 106 107 /** 108 * Mounts an ANSI path. 109 * 110 * For example, if "c:/" is mounted as "/dev/c", then any file referenced under "/dev/c" will access 111 * "c:/" under the hood. 112 * 113 * @param virtualPath PFileSystem path 114 * @param realPath ANSI path 115 * @return ESR_INVALID_ARGUMENT if self or virtualPath or realPath is null or realPath is not a valid path; 116 * ESR_OUT_OF_MEMORY if the system is out of memory; ESR_IDENTIFIER_COLLISION if virtualPath is already mounted. 117 */ 118 PORTABLE_API ESR_ReturnCode PANSIFileSystemAddPath(const LCHAR* virtualPath, const LCHAR* realPath); 119 120 /** 121 * Deassociates the file-system from a base path. 122 * 123 * @param virtualPath PFileSystem path 124 * @return ESR_INVALID_ARGUMENT if self or virtualPath is null or virtualPath is not mounted 125 */ 126 PORTABLE_API ESR_ReturnCode PANSIFileSystemRemovePath(const LCHAR* virtualPath); 127 128 /** 129 * Returns a virtual path associated with the current ANSI directory. 130 * 131 * For example, if "/dev/ansi" is mapped to "/" and the current ANSI directory is "/usr/bin" then 132 * this function will return "/dev/ansi/usr/bin". 133 * 134 * If multiple virtual paths correspond to the current ANSI directory, the first one will be returned. 135 * 136 * @param cwd [out] Current working directory 137 * @param len [in/out] Length of path argument. If the return code is ESR_BUFFER_OVERFLOW, 138 * the required length is returned in this variable. 139 * @return ESR_INVALID_ARGUMENT if self or cwd is null; ESR_BUFFER_OVERFLOW if cwd is not large enough to contain result; 140 * ESR_INVALID_STATE if operating-system returns unexpected value. 141 */ 142 PORTABLE_API ESR_ReturnCode PANSIFileSystemGetcwd(LCHAR* cwd, size_t* len); 143 144 /** 145 * Indicates if this file-system should act as the default file-system. 146 * If a path is specified which does not match any other file-system, it is resolved using this one. 147 * 148 * @param isDefault True if the file-system should be the default file-system 149 * @return ESR_OUT_OF_MEMORY if system is out of memory 150 */ 151 PORTABLE_API ESR_ReturnCode PANSIFileSystemSetDefault(ESR_BOOL isDefault); 152 153 /** 154 * @} 155 */ 156 #endif /* __PANSIFILESYSTEM_H */ 157