/*---------------------------------------------------------------------------*
* PFileSystem.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 __PFILESYSTEM_H
#define __PFILESYSTEM_H
#include "ESR_ReturnCode.h"
#include "PortPrefix.h"
#include "PFile.h"
#include "ptypes.h"
/**
* @addtogroup PFileSystemModule PFileSystem 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.
*
* @{
*/
/**
* Portable standard input.
*/
/*PORTABLE_API PFile* PSTDIN;*/
/**
* Portable standard output.
*/
/*PORTABLE_API PFile* PSTDOUT;*/
/**
* Portable standard error.
*/
/*PORTABLE_API PFile* PSTDERR;*/
#define PSTDIN stdin
#define PSTDOUT stdout
#define PSTDERR stderr
/**
* Portable file-system.
*/
typedef struct PFileSystem_t
{
/**
* Destroys the PFileSystem.
*
* @param self PFileSystem handle
* @return ESR_INVALID_ARGUMENT if self is null
*/
ESR_ReturnCode(*destroy)(struct PFileSystem_t* self);
/**
* Creates a new PFile using this file-system.
*
* @param self PFileSystem handle
* @param path Fully qualified file path
* @param littleEndian True if file is in little-endian format
* @param file [out] Resulting PFile
*/
ESR_ReturnCode(*createPFile)(struct PFileSystem_t* self, const LCHAR* path, ESR_BOOL littleEndian, PFile** file);
/**
* Creates a new directory.
*
* @param self PFileSystem handle
* @param path Fully qualified directory path
* @return ESR_INVALID_ARGUMENT if path is null; ESR_IDENTIFIER_COLLISION if directory already exists;
* ESR_NO_MATCH_ERROR if parent directory does not exist; ESR_INVALID_STATE if an internal error occurs
*/
ESR_ReturnCode(*mkdir)(struct PFileSystem_t* self, const LCHAR* path);
/**
* Sets the current working directory.
*
* @param self PFileSystem handle
* @param path Fully qualified file path
* @return ESR_SUCCESS if change of directory is allowed
*/
ESR_ReturnCode(*chdir)(struct PFileSystem_t* self, const LCHAR* path);
}
PFileSystem;
/**
* Initializes the portable file-system module.
*
* @return ESR_INVALID_STATE if calling StackTraceCreate() fails (see its documentation for more detail).
*/
PORTABLE_API ESR_ReturnCode PFileSystemCreate(void);
/**
* Indicates if the portable file-system module is initialized.
*
* @param isCreated [in/out] True if the module is initialized.
* @return ESR_INVALID_ARGUMENT if isCreated is null
*/
PORTABLE_API ESR_ReturnCode PFileSystemIsCreated(ESR_BOOL* isCreated);
/**
* Shuts down the portable file-system module.
*
* @return ESR_INVALID_ARGUMENT if self is null
*/
PORTABLE_API ESR_ReturnCode PFileSystemDestroy(void);
/**
* Creates a new PFile using this file-system.
*
* @param path Fully qualified file path
* @param littleEndian True if file is in little-endian format
* @param file [out] Resulting PFile
* @return ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_STATE if mutex could not be created
*/
PORTABLE_API ESR_ReturnCode PFileSystemCreatePFile(const LCHAR* path, ESR_BOOL littleEndian, PFile** file);
/**
* Indicates if path is absolute.
*
* @param path Path to be processed
* @param isAbsolute True if path is absolute
* @return ESR_INVALID_ARGUMENT if path or isAbsolute are null
*/
PORTABLE_API ESR_ReturnCode PFileSystemIsAbsolutePath(const LCHAR* path, ESR_BOOL* isAbsolute);
/**
* Returns the canonical pathname string of this abstract pathname.
*
* A canonical pathname is both absolute and unique. The precise definition of canonical
* form is system-dependent. This method first converts this pathname to absolute form.
* This typically involves removing redundant names such as "." and ".." from the pathname,
* resolving symbolic links (on UNIX platforms), and converting drive letters to
* a standard case (on Microsoft Windows platforms).
*
* POST-CONDITION: Path will contain only canonical slashes
*
* @param path Path to process
* @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 path or len are null
*/
PORTABLE_API ESR_ReturnCode PFileSystemGetAbsolutePath(LCHAR* path, size_t* len);
/**
* Converts all slashes in path to '/'.
*
* @param path [in/out] Path to process
* @return ESR_INVALID_ARGUMENT if path is null
*/
PORTABLE_API ESR_ReturnCode PFileSystemCanonicalSlashes(LCHAR* path);
/**
* Returns parent directory of specified path.
* If the path ends with a filename, its directory is returned.
* If the path ends with a directory, its parent directory is returned.
*
* PRECONDITION: Directory names must end with '/'
*
* @param path [in/out] Path to process
* @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 path or len are null; ESR_BUFFER_OVERFLOW if path is too small to contain the result
*/
PORTABLE_API ESR_ReturnCode PFileSystemGetParentDirectory(LCHAR* path, size_t* len);
/**
* Creates a new directory.
*
* @param path Directory path
* @return ESR_INVALID_ARGUMENT if path is null; ESR_IDENTIFIER_COLLISION if directory already exists;
* ESR_NO_MATCH_ERROR if parent directory does not exist; ESR_INVALID_STATE if an internal error occurs
*/
PORTABLE_API ESR_ReturnCode PFileSystemMkdir(const LCHAR* path);
/**
* Returns the current working directory (always ends with '/').
*
* @param path [out] The 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 path or len are null; ESR_BUFFER_OVERFLOW if path is too small to contain the result
*/
PORTABLE_API ESR_ReturnCode PFileSystemGetcwd(LCHAR* path, size_t* len);
/**
* Sets the current working directory.
*
* @param path Fully qualified file path
* @return ESR_SUCCESS if change of directory is allowed
*/
PORTABLE_API ESR_ReturnCode PFileSystemChdir(const LCHAR* path);
/**
* Converts a linear path string to an array of path tokens.
* Tokens ending with a '/' denote a directory, otherwise they are a file.
*
* POST-CONDITION: The array is allocated internally, but must be freed by the caller.
*
* @param path Command-line string to parse
* @param tokenArray [out] The array used to hold the tokens
* @param count [out] The number of tokens found
* @return ESR_INVALID_ARGUMENT if path, tokenArray or count are null; ESR_OUT_OF_MEMORY if system is out of memory
*/
PORTABLE_API ESR_ReturnCode PFileSystemLinearToPathTokens(const LCHAR* path, LCHAR*** tokenArray, size_t* count);
/**
* @}
*/
#endif /* __PFILESYSTEM_H */