280 lines
9.9 KiB
C
280 lines
9.9 KiB
C
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* file: aFile.h */
|
|
/* */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* description: Definition of a platform-independent file utility. */
|
|
/* */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* Copyright (c) 2018 Acroname Inc. - All Rights Reserved */
|
|
/* */
|
|
/* This file is part of the BrainStem release. See the license.txt */
|
|
/* file included with this package or go to */
|
|
/* https://acroname.com/software/brainstem-development-kit */
|
|
/* for full license details. */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
|
|
#ifndef _aFile_H_
|
|
#define _aFile_H_
|
|
|
|
#include "aDefs.h"
|
|
#include "aError.h"
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Platform Independent File Access Interface
|
|
|
|
/** \defgroup aFile File Interface
|
|
* \ref aFile "aFile.h" provides a platform independent interface for opening, reading,
|
|
* and writing files.
|
|
*/
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Typedef #aFileRef Opaque reference to a file handle.
|
|
typedef void* aFileRef;
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Enum #aFileMode.
|
|
|
|
/**
|
|
* Represents whether the file is to be opened in read or write mode.
|
|
*/
|
|
typedef enum aFileMode {
|
|
aFileModeReadOnly, /**< File read mode. */
|
|
aFileModeWriteOnly, /**< File write mode. */
|
|
aFileModeAppend, /**< File write mode from end of current file. */
|
|
aFileModeUnknown /**< File in unknown mode. */
|
|
} aFileMode;
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Enum #aFileSeekMode.
|
|
|
|
/**
|
|
* Represents the seek start location.
|
|
*/
|
|
typedef enum aFileSeekMode {
|
|
aSeekStart, /**< Perform a seek from the beginning of the file. */
|
|
aSeekCurrent, /**< Perform a seek from the current location. */
|
|
aSeekEnd /**< Perform a seek from the end of the file. */
|
|
} aFileSeekMode;
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Does the File Exist.
|
|
|
|
/**
|
|
* Checks for the existence of a file at filename.
|
|
* \param pFilename path to file.
|
|
* \return bool True if file exists, false otherwise.
|
|
*/
|
|
aLIBEXPORT bool aFile_Exists(const char* pFilename);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Open a File.
|
|
|
|
/**
|
|
* Opens the file Given in pFilename with the given fileMode eMode.
|
|
* \param pFilename path to file.
|
|
* \param eMode Open the file for Reading or Writing.
|
|
* \return aFileRef on success or NULL on failure.
|
|
*/
|
|
aLIBEXPORT aFileRef aFile_Open(const char* pFilename, const aFileMode eMode);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Close an open file.
|
|
|
|
/**
|
|
* Close an open file. The fileRef is set to NULL on success.
|
|
* \param fileRef Pointer to the handle to the open file.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrParam invalid file reference.
|
|
*/
|
|
aLIBEXPORT aErr aFile_Close(aFileRef* fileRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Read from an open file.
|
|
|
|
/**
|
|
* Read from an open file.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
* \param pBuffer The data buffer to read into.
|
|
* \param nLength The length of the read buffer.
|
|
* \param pActuallyRead The Number of bytes actually read from the file.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrMode The file is not readable.
|
|
* \retval aErrIO An error occured reading from the file.
|
|
* \retval aErrEOF Read reached the end of the file.
|
|
*/
|
|
aLIBEXPORT aErr aFile_Read(aFileRef fileRef,
|
|
uint8_t* pBuffer,
|
|
const size_t nLength,
|
|
size_t* pActuallyRead);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Write to an open file.
|
|
|
|
/**
|
|
* Write to an open file.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
* \param pBuffer The data to write.
|
|
* \param nLength The length of the data to write.
|
|
* \param pActuallyWritten The Number of bytes actually written to the file.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrMode The file is not writable.
|
|
* \retval aErrIO An error occured writing to the file.
|
|
*/
|
|
aLIBEXPORT aErr aFile_Write(aFileRef fileRef,
|
|
const uint8_t* pBuffer,
|
|
const size_t nLength,
|
|
size_t* pActuallyWritten);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Seek within an open file.
|
|
|
|
/**
|
|
* Seek within an open file.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
* \param nOffset The number of bytes to move within the file.
|
|
* \param seekFrom The location to begin the seek from.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrEOF Seek would run off the end of the file.
|
|
* \retval aErrRange Seek would run off the beginning of the file.
|
|
* \retval aErrIO An error occured moving the file pointer.
|
|
*/
|
|
aLIBEXPORT aErr aFile_Seek(aFileRef fileRef,
|
|
const long nOffset,
|
|
aFileSeekMode seekFrom);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Get the size of an open file.
|
|
|
|
/**
|
|
* Get the size of an open file.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
* \param pulSize Out param filled with the size of the open file.
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrParam the fileRef is invalid.
|
|
* \retval aErrIO an error occured calculating the size.
|
|
*/
|
|
aLIBEXPORT aErr aFile_GetSize(aFileRef fileRef, size_t* pulSize);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Delete a File.
|
|
|
|
/**
|
|
* Deletes the given file pFilename.
|
|
* \param pFilename Path to file.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrPermission user has insufficient priviledges.
|
|
* \retval aErrNotFound if the file cannot be located.
|
|
*/
|
|
aLIBEXPORT aErr aFile_Delete(const char *pFilename);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Read a line from an open file.
|
|
/**
|
|
* Read a line from an open file.
|
|
*
|
|
* This function will treat the file as an ASCII file,
|
|
* even though the file is opened for binary operations.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
* \param pBuffer The data buffer to read into.
|
|
* \param nLength The length of the read buffer.
|
|
* \param pActuallyRead The Number of bytes actually read from the file.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrMode The file is not readable.
|
|
* \retval aErrIO An error occured reading from the file.
|
|
* \retval aErrEOF Read reached the end of the file.
|
|
*/
|
|
aLIBEXPORT aErr aFile_ReadLine(aFileRef fileRef,
|
|
uint8_t* pBuffer,
|
|
const size_t nLength,
|
|
size_t* pActuallyRead);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Set the I/O for this file to be unbuffered.
|
|
/**
|
|
* Set the I/O for this file to be unbuffered. This function
|
|
* call must be performed before any other operations are made on
|
|
* an open file.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
*
|
|
* \return Function returns aErrMode on error.
|
|
* \retval aErrNone Success.
|
|
*/
|
|
aLIBEXPORT aErr aFile_SetUnbuffered(aFileRef fileRef);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Get the current position of this file.
|
|
/**
|
|
* Get the current position of this file.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
* \param pPos The current position of the file.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
*/
|
|
aLIBEXPORT aErr aFile_GetPosition(aFileRef fileRef, size_t* pPos);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Write formatted string to an open file.
|
|
/**
|
|
* Write formatted string to an open file.
|
|
*
|
|
* This function will treat the file as an ASCII file,
|
|
* even though the file is opened for binary operations.
|
|
*
|
|
* \param fileRef The handle to the open file.
|
|
* \param pFormat The data buffer to read into.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone Success.
|
|
* \retval aErrMode The file is not writable.
|
|
* \retval aErrIO An error occured writing to the file.
|
|
*/
|
|
aLIBEXPORT aErr aFile_Printf(aFileRef fileRef,
|
|
const char* pFormat,
|
|
...);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _aFile_H_ */
|