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 */
47typedef 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}
90PANSIFileSystem;
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 */
98PORTABLE_API ESR_ReturnCode PANSIFileSystemCreate(void);
99
100/**
101 * Shuts down the ANSI file-system module.
102 *
103 * @return ESR_SUCCESS
104 */
105PORTABLE_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 */
118PORTABLE_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 */
126PORTABLE_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 */
142PORTABLE_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 */
151PORTABLE_API ESR_ReturnCode PANSIFileSystemSetDefault(ESR_BOOL isDefault);
152
153/**
154 * @}
155 */
156#endif /* __PANSIFILESYSTEM_H */
157