/*---------------------------------------------------------------------------*
* PANSIFileSystem.h *
* *
* Copyright 2007, 2008 Nuance Communciations, Inc. *
* *
* Licensed under the Apache License, Version 2.0 (the 'License'); *
* you may not use this file except in compliance with the License. *
* *
* You may obtain a copy of the License at *
* http://www.apache.org/licenses/LICENSE-2.0 *
* *
* Unless required by applicable law or agreed to in writing, software *
* distributed under the License is distributed on an 'AS IS' BASIS, *
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
* See the License for the specific language governing permissions and *
* limitations under the License. *
* *
*---------------------------------------------------------------------------*/
#ifndef __PANSIFILESYSTEM_H
#define __PANSIFILESYSTEM_H
#include "ESR_ReturnCode.h"
#include "PortPrefix.h"
#include "PFileSystem.h"
#include "ptypes.h"
/**
* @addtogroup PANSIFileSystemModule PANSIFileSystem API functions
* Portable file-system API.
*
* Must call pmemInit() before using this module.
* If threads are to be used, ptrdInit() must be called before using this module as well.
*
* NOTE: It is technically impossible to provide a cross-platform version of scanf() and its
* variants (since vscanf() does not exist). As a result, this module does not provide this
* functionality. End-users are encourages to do their own parsing.
*
* @{
*/
/**
* Portable ANSI file-system.
*/
typedef struct PANSIFileSystem_t
{
/**
* Superinterface.
*/
PFileSystem super;
/**
* Mounts an ANSI path.
*
* For example, if "c:/" is mounted as "/dev/c", then any file referenced under "/dev/c" will access
* "c:/" under the hood.
*
* @param self PFileSystem handle
* @param virtualPath PFileSystem path
* @param realPath ANSI path
* @return ESR_INVALID_ARGUMENT if self or virtualPath or realPath is null or realPath is not a valid path;
* ESR_OUT_OF_MEMORY if the system is out of memory; ESR_IDENTIFIER_COLLISION if virtualPath is already mounted.
*/
ESR_ReturnCode(*addPath)(PFileSystem* self, const LCHAR* virtualPath, const LCHAR* realPath);
/**
* Deassociates the file-system from a base path.
*
* @param self PFileSystem handle
* @param virtualPath PFileSystem path
* @return ESR_INVALID_ARGUMENT if self or virtualPath is null or virtualPath is not mounted
*/
ESR_ReturnCode(*removePath)(PFileSystem* self, const LCHAR* virtualPath);
/**
* Returns the current working directory from the operating-system's point of view.
* This differs from PFileSystemGetcwd() in that the latter returns the current working
* directory on the virtual file-system while this function returns the native working directory.
*
* @param self PFileSystem handle
* @param cwd [out] Current working directory
* @param len [in/out] Length of path argument. If the return code is ESR_BUFFER_OVERFLOW,
* the required length is returned in this variable.
* @return ESR_INVALID_ARGUMENT if self or cwd is null; ESR_BUFFER_OVERFLOW if cwd is not large enough to contain result;
* ESR_INVALID_STATE if operating-system returns unexpected value.
*/
ESR_ReturnCode(*getcwd)(PFileSystem* self, LCHAR* cwd, size_t* len);
}
PANSIFileSystem;
/**
* Initializes the ANSI file-system module.
*
* @return ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_STATE if mutex could not be created or if this
* function is called after the Ptrd module has been shut down.
*/
PORTABLE_API ESR_ReturnCode PANSIFileSystemCreate(void);
/**
* Shuts down the ANSI file-system module.
*
* @return ESR_SUCCESS
*/
PORTABLE_API ESR_ReturnCode PANSIFileSystemDestroy(void);
/**
* Mounts an ANSI path.
*
* For example, if "c:/" is mounted as "/dev/c", then any file referenced under "/dev/c" will access
* "c:/" under the hood.
*
* @param virtualPath PFileSystem path
* @param realPath ANSI path
* @return ESR_INVALID_ARGUMENT if self or virtualPath or realPath is null or realPath is not a valid path;
* ESR_OUT_OF_MEMORY if the system is out of memory; ESR_IDENTIFIER_COLLISION if virtualPath is already mounted.
*/
PORTABLE_API ESR_ReturnCode PANSIFileSystemAddPath(const LCHAR* virtualPath, const LCHAR* realPath);
/**
* Deassociates the file-system from a base path.
*
* @param virtualPath PFileSystem path
* @return ESR_INVALID_ARGUMENT if self or virtualPath is null or virtualPath is not mounted
*/
PORTABLE_API ESR_ReturnCode PANSIFileSystemRemovePath(const LCHAR* virtualPath);
/**
* Returns a virtual path associated with the current ANSI directory.
*
* For example, if "/dev/ansi" is mapped to "/" and the current ANSI directory is "/usr/bin" then
* this function will return "/dev/ansi/usr/bin".
*
* If multiple virtual paths correspond to the current ANSI directory, the first one will be returned.
*
* @param cwd [out] Current working directory
* @param len [in/out] Length of path argument. If the return code is ESR_BUFFER_OVERFLOW,
* the required length is returned in this variable.
* @return ESR_INVALID_ARGUMENT if self or cwd is null; ESR_BUFFER_OVERFLOW if cwd is not large enough to contain result;
* ESR_INVALID_STATE if operating-system returns unexpected value.
*/
PORTABLE_API ESR_ReturnCode PANSIFileSystemGetcwd(LCHAR* cwd, size_t* len);
/**
* Indicates if this file-system should act as the default file-system.
* If a path is specified which does not match any other file-system, it is resolved using this one.
*
* @param isDefault True if the file-system should be the default file-system
* @return ESR_OUT_OF_MEMORY if system is out of memory
*/
PORTABLE_API ESR_ReturnCode PANSIFileSystemSetDefault(ESR_BOOL isDefault);
/**
* @}
*/
#endif /* __PANSIFILESYSTEM_H */