pal_plat_fileSystem.h

00001 /*******************************************************************************
00002  * Copyright 2016, 2017 ARM Ltd.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  *******************************************************************************/
00016 #ifndef PAL_PALT_FILE_SYSTEM_H
00017 #define PAL_PALT_FILE_SYSTEM_H
00018 
00019 #include "pal_fileSystem.h"
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 /*! \file pal_plat_fileSystem.h
00026  *  \brief PAL file system - platform.
00027  *  This file contains the file system APIs that need to be implemented in the platform layer.
00028  *
00029  *  \note You need to add the prefix of the ESFS folder root stored in \c g_esfsRootFolder to all files and folders.
00030  *  To change this, call \c pal_plat_fsSetEsfsRootFolder().
00031  *
00032  */
00033 
00034 /*! \brief  This function attempts to create a directory named \c pathName.
00035  *
00036  * @param[in]   *pathName A pointer to the null-terminated string that specifies the directory name to create.
00037  *
00038  * \return PAL_SUCCESS upon a successful operation.
00039  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00040  *
00041  * \note To remove a directory use \c PAL_ERR_FS_rmdir.
00042  *
00043  * \b Example
00044     \code{.cpp}
00045        palStatus_t ret;
00046        ret = PAL_ERR_FS_mkdir("Dir1");
00047        if(!ret)
00048        {
00049            //Error
00050        }
00051    \endcode
00052  */
00053 palStatus_t pal_plat_fsMkdir(const char *pathName);
00054 
00055 
00056 
00057 /*! \brief This function deletes a directory.
00058  *
00059  * @param[in]   *pathName A pointer to the null-terminated string that specifies the name of the directory to be deleted.
00060  *
00061  * \return PAL_SUCCESS upon a successful operation.
00062  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00063  *
00064  * \note The directory to be deleted \b must be \e Empty and \e closed.
00065  *      The folder path must end with "/".
00066  *      If given `..`, the function changes the root directory to one directory down and deletes the working directory.
00067  */
00068 palStatus_t pal_plat_fsRmdir(const char *pathName);
00069 
00070 
00071 
00072 /*!\brief This function opens the file whose name is specified in the parameter `pathName` and associates it with a stream
00073  *         that can be identified in future operations by the `fd` pointer returned.
00074  *
00075  * @param[out]  fd A file descriptor for the file entered in the `pathName`.
00076  * @param[in]   *pathName A pointer to the null-terminated string that specifies the file name to open or create.
00077  * @param[in]   mode A mode flag that specifies the type of access and open method for the file.
00078  *
00079  *
00080  * \return PAL_SUCCESS upon a successful operation.
00081  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00082  *
00083  * \note      The folder path must end with "/".
00084  * \note      If necessary, the platform layer \e allocates \e memory for the file descriptor. The structure
00085  *        \c pal_plat_fclose() frees that buffer.
00086  * \note   The mode flags sent to this function are normalized to \c pal_fsFileMode_t and each platform needs to replace them with the proper values.
00087  *
00088  */
00089 palStatus_t pal_plat_fsFopen(const char *pathName, pal_fsFileMode_t mode, palFileDescriptor_t *fd);
00090 
00091 
00092 
00093 /*! \brief This function closes an open file object.
00094  *
00095  * @param[in] fd A pointer to the open file object structure to be closed.
00096  *
00097  * \return PAL_SUCCESS upon a successful operation.
00098  * return PAL_FILE_SYSTEM_ERROR - see the error code \c palError_t.
00099  *
00100  * \note After the successful execution of the function, the file object is no longer valid and it can be discarded.
00101  * \note In some platforms, this function needs to \b free the file descriptor memory.
00102  */
00103 palStatus_t pal_plat_fsFclose(palFileDescriptor_t *fd);
00104 
00105 
00106 
00107 /*! \brief  This function reads an array of bytes from the stream and stores them in the block of memory
00108  *          specified by the buffer.
00109  *
00110  * The position indicator of the stream is advanced by the total amount of bytes read.
00111  *
00112  * @param[in]   fd A pointer to the open file object structure.
00113  * @param[in]   buffer A buffer for storing the read data.
00114  * @param[in]   numOfBytes The number of bytes to read.
00115  * @param[out]  numberOfBytesRead The number of bytes read.
00116  *
00117  * \return PAL_SUCCESS upon a successful operation.
00118  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00119  *
00120  * \note    After successful execution of the function,
00121  *      `numberOfBytesRead` should be checked to detect end of the file.
00122  *      If `numberOfBytesRead` is less than `numOfBytes`,
00123  *      the read/write pointer has reached the end of the file during the read operation or an error has occurred.
00124  *
00125  */
00126 palStatus_t pal_plat_fsFread(palFileDescriptor_t *fd, void * buffer, size_t numOfBytes, size_t *numberOfBytesRead);
00127 
00128 
00129 
00130 /*! \brief This function starts to write data from the \c buffer to the file at the position pointed by the read/write pointer.
00131  *
00132  * @param[in]   fd A pointer to the open file object structure.
00133  * @param[in]   buffer A pointer to the data to be written.
00134  * @param[in]   numOfBytes The number of bytes to write.
00135  * @param[out]  numberOfBytesWritten The number of bytes written.
00136  *
00137  * \return PAL_SUCCESS upon a successful operation.
00138  * \return PAL_FILE_SYSTEM_ERROR - see the error code \c palError_t.
00139  *
00140  * \note The read/write pointer advances with number of bytes written. After successful execution of the function,
00141  * \note `numberOfBytesWritten` should be checked to detect if the disk is full.
00142  *      If `numberOfBytesWritten` is less than `numOfBytes`, the volume became full during the write operation.
00143  *
00144  */
00145 palStatus_t pal_plat_fsFwrite(palFileDescriptor_t *fd, const void *buffer, size_t numOfBytes, size_t *numberOfBytesWritten);
00146 
00147 
00148 /*! \brief  This function moves the file read/write pointer without any read/write operation to the file.
00149  *
00150  * @param[in]   fd A pointer to the open file object structure.
00151  * @param[in]   offset The byte offset from `whence` to set the read/write pointer.
00152  * @param[out]   whence The offset is relative to this.
00153  *
00154  * \note - The `whence` options are:
00155  *       -# \c PAL_ERR_FS_SEEKSET - relative to the start of the file.
00156  *           -# \c PAL_ERR_FS_SEEKCUR - relative to the current position indicator.
00157  *       -# \c PAL_ERR_FS_SEEKEND - relative to the end-of-file.
00158  *
00159  * \note In some systems, there is no \c whence argument.
00160  *  If you need to implement the `whence` argument:\n
00161  *  \b PAL_ERR_FS_SEEKEND - The function first finds the length of the file, then subtracts the file length from the position to find the relative path from the beginning.\n
00162  *       \b PAL_ERR_FS_SEEKCUR - The function finds the current stream position and calculates the relative path from the file start.
00163  *
00164  * \note In both options, \c fseek() needs to verify that the offset is smaller than the file end or start.
00165  *
00166  * \return PAL_SUCCESS upon a successful operation.
00167  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00168  *
00169  */
00170 palStatus_t pal_plat_fsFseek(palFileDescriptor_t *fd, int32_t offset, pal_fsOffset_t whence);
00171 
00172 
00173 
00174 /*! \brief This function gets the current read/write pointer of a file.
00175  *
00176  * @param[in]   fd A pointer to the open file object structure.
00177  *
00178  * \return PAL_SUCCESS upon a successful operation.
00179  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00180  *
00181  */
00182 palStatus_t pal_plat_fsFtell(palFileDescriptor_t *fd, int32_t * pos);
00183 
00184 
00185 
00186 /*! \brief This function deletes a \e single file from the file system.
00187  *
00188  * @param[in]  pathName A pointer to a null-terminated string that specifies the file to be removed.
00189  *
00190  * \return PAL_SUCCESS upon a successful operation.
00191  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00192  *
00193  * \note The file must \b not be open.
00194  *
00195  */
00196 palStatus_t pal_plat_fsUnlink(const char *pathName);
00197 
00198 
00199 
00200 /*! \brief This function deletes \e all files in a folder from the file system (FLAT remove only).
00201  *
00202  * @param[in]  pathName A pointer to a null-terminated string that specifies the \b folder.
00203  *
00204  * \return PAL_SUCCESS upon a successful operation.
00205  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00206  *
00207  * \note The folder must \b not be open and the folder path must end with `/`.
00208  * \note The process deletes one file at a time by calling \c pal_plat_fsUnlink until all files are removed.
00209  * \note The function does not remove a directory found in the path.
00210  */
00211 palStatus_t pal_plat_fsRmFiles(const char *pathName);
00212 
00213 
00214 
00215 /*! \brief This function copies \e all files from a source folder to a destination folder (FLAT copy only).
00216  *
00217  * @param[in]  pathNameSrc A pointer to a null-terminated string that specifies the source folder.
00218  * @param[in]  pathNameDest A pointer to a null-terminated string that specifies the destination folder. The destination folder MUST exist.
00219  *
00220  * \return PAL_SUCCESS upon a successful operation.
00221  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00222  *
00223  * \note Both folders must \b not be open. If a folder does not exist the function fails.
00224  * \note The process copies one file at a time until all files are copied.
00225  * \note The function does not copy a directory found in the path.
00226  */
00227 palStatus_t pal_plat_fsCpFolder(const char *pathNameSrc,  char *pathNameDest);
00228 
00229 
00230 /*! \brief This function gets the default value for the root directory.
00231  *
00232  * @param[in]  dataID - ID of the data to get the root folder for.
00233  *
00234  * \return Pointer to the default path.
00235  *
00236  */
00237 const char* pal_plat_fsGetDefaultRootFolder(pal_fsStorageID_t dataID);
00238 
00239 
00240 
00241 /*! \brief This function finds the length of the string received.
00242  *
00243  *
00244  * @param[in]  stringToChk A pointer to the string received with a null terminator.
00245  *
00246  * \return The size of the string.
00247  *
00248  */
00249 size_t pal_plat_fsSizeCheck(const char *stringToChk);
00250 
00251 
00252 
00253 /*! \brief This function sets up the mount point.
00254  *
00255  *
00256  * @param void
00257  *
00258  * \return PAL_SUCCESS upon a successful operation.
00259  * \return PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00260  *
00261  */
00262 palStatus_t pal_plat_fsMountSystem(void);
00263 
00264 
00265 /*! \brief This function formats the SD partition indicated by `dataID`.
00266  *
00267  * Mapping the ID to an actual partition is done in the porting layer.
00268  *
00269  *
00270  * @param[in] dataID The ID of the partition to be formatted.
00271  *
00272  * \return PAL_SUCCESS upon a successful operation.\n
00273  *         PAL_FILE_SYSTEM_ERROR - see the error code description \c palError_t.
00274  *
00275  */
00276 palStatus_t pal_plat_fsFormat(pal_fsStorageID_t dataID);
00277 
00278 
00279 #ifdef __cplusplus
00280 }
00281 #endif
00282 #endif