leo hendrickson / Mbed OS example-Ethernet-mbed-Cloud-connect

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

simple-mbed-cloud-client/mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Services-API/pal_fileSystem.h@0:8f0bb79ddd48, 2021-05-04 (annotated)

Committer:
leothedragon
Date:
Tue May 04 08:55:12 2021 +0000
Revision:
0:8f0bb79ddd48
nmn

Who changed what in which revision?

UserRevisionLine numberNew contents of line
leothedragon 0:8f0bb79ddd48 1 // ----------------------------------------------------------------------------
leothedragon 0:8f0bb79ddd48 2 // Copyright 2016-2019 ARM Ltd.
leothedragon 0:8f0bb79ddd48 3 //
leothedragon 0:8f0bb79ddd48 4 // SPDX-License-Identifier: Apache-2.0
leothedragon 0:8f0bb79ddd48 5 //
leothedragon 0:8f0bb79ddd48 6 // Licensed under the Apache License, Version 2.0 (the "License");
leothedragon 0:8f0bb79ddd48 7 // you may not use this file except in compliance with the License.
leothedragon 0:8f0bb79ddd48 8 // You may obtain a copy of the License at
leothedragon 0:8f0bb79ddd48 9 //
leothedragon 0:8f0bb79ddd48 10 // http://www.apache.org/licenses/LICENSE-2.0
leothedragon 0:8f0bb79ddd48 11 //
leothedragon 0:8f0bb79ddd48 12 // Unless required by applicable law or agreed to in writing, software
leothedragon 0:8f0bb79ddd48 13 // distributed under the License is distributed on an "AS IS" BASIS,
leothedragon 0:8f0bb79ddd48 14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
leothedragon 0:8f0bb79ddd48 15 // See the License for the specific language governing permissions and
leothedragon 0:8f0bb79ddd48 16 // limitations under the License.
leothedragon 0:8f0bb79ddd48 17 // ----------------------------------------------------------------------------
leothedragon 0:8f0bb79ddd48 18
leothedragon 0:8f0bb79ddd48 19 #ifndef PAL_FILE_SYSTEM_H
leothedragon 0:8f0bb79ddd48 20 #define PAL_FILE_SYSTEM_H
leothedragon 0:8f0bb79ddd48 21
leothedragon 0:8f0bb79ddd48 22 #ifndef _PAL_H
leothedragon 0:8f0bb79ddd48 23 #error "Please do not include this file directly, use pal.h instead"
leothedragon 0:8f0bb79ddd48 24 #endif
leothedragon 0:8f0bb79ddd48 25
leothedragon 0:8f0bb79ddd48 26 /*! \file pal_fileSystem.h
leothedragon 0:8f0bb79ddd48 27 * \brief PAL file system. This file contains the file system APIs and is part of the PAL service API.
leothedragon 0:8f0bb79ddd48 28 *
leothedragon 0:8f0bb79ddd48 29 * It provides APIs to create and remove directories as well as open, read and write to files.
leothedragon 0:8f0bb79ddd48 30 */
leothedragon 0:8f0bb79ddd48 31
leothedragon 0:8f0bb79ddd48 32 /*! \mainpage
leothedragon 0:8f0bb79ddd48 33 *
leothedragon 0:8f0bb79ddd48 34 *\section file_sec File System
leothedragon 0:8f0bb79ddd48 35 *
leothedragon 0:8f0bb79ddd48 36 *\subsection rev_hist Revision History
leothedragon 0:8f0bb79ddd48 37 * 19-Jan-2017 Created and First Draft\n
leothedragon 0:8f0bb79ddd48 38 * 25-Jan-2017 Updated Design according to DR meeting \n
leothedragon 0:8f0bb79ddd48 39 * 02-Jan-2017 Minor implementation Changes \n
leothedragon 0:8f0bb79ddd48 40 *
leothedragon 0:8f0bb79ddd48 41 *
leothedragon 0:8f0bb79ddd48 42 *
leothedragon 0:8f0bb79ddd48 43 * \subsection int_sec Introduction
leothedragon 0:8f0bb79ddd48 44 * This file details an abstraction layer for accessing POSIX-like file systems.
leothedragon 0:8f0bb79ddd48 45 *
leothedragon 0:8f0bb79ddd48 46 *
leothedragon 0:8f0bb79ddd48 47 * \subsection req_sec Requirements
leothedragon 0:8f0bb79ddd48 48 * The requirements for PAL Version 1.2 are to support the following POSIX-like APIs:
leothedragon 0:8f0bb79ddd48 49 *
leothedragon 0:8f0bb79ddd48 50 *
leothedragon 0:8f0bb79ddd48 51 *
leothedragon 0:8f0bb79ddd48 52 *\b Folder \b Operations
leothedragon 0:8f0bb79ddd48 53 * -# mkdir <a href="http://man7.org/linux/man-pages/man2/mkdir.2.html"> http://man7.org/linux/man-pages/man2/mkdir.2.html</a>
leothedragon 0:8f0bb79ddd48 54 * -# rmdir() <a href="http://man7.org/linux/man-pages/man2/rmdir.2.html"> http://man7.org/linux/man-pages/man2/rmdir.2.html</a>
leothedragon 0:8f0bb79ddd48 55 *
leothedragon 0:8f0bb79ddd48 56 *
leothedragon 0:8f0bb79ddd48 57 *\b File \b Operations
leothedragon 0:8f0bb79ddd48 58 * -# fopen() <a href="http://man7.org/linux/man-pages/man3/fopen.3.html"> http://man7.org/linux/man-pages/man3/fopen.3.html</a>
leothedragon 0:8f0bb79ddd48 59 * -# fclose() <a href="http://man7.org/linux/man-pages/man3/fclose.3.html"> http://man7.org/linux/man-pages/man3/fclose.3.html</a>
leothedragon 0:8f0bb79ddd48 60 * -# fread() <a href="http://man7.org/linux/man-pages/man3/fwrite.3.html"> http://man7.org/linux/man-pages/man3/fwrite.3.html</a>
leothedragon 0:8f0bb79ddd48 61 * -# fwrite() <a href="http://man7.org/linux/man-pages/man3/fwrite.3.html"> http://man7.org/linux/man-pages/man3/fwrite.3.html</a>
leothedragon 0:8f0bb79ddd48 62 * -# fseek() <a href="http://man7.org/linux/man-pages/man3/fseek.3.html"> http://man7.org/linux/man-pages/man3/fseek.3.html</a>
leothedragon 0:8f0bb79ddd48 63 * -# ftell() <a href="http://man7.org/linux/man-pages/man3/fseek.3.html"> http://man7.org/linux/man-pages/man3/fseek.3.html</a>
leothedragon 0:8f0bb79ddd48 64 * -# unlink() <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"> http://man7.org/linux/man-pages/man2/unlink.2.html</a>
leothedragon 0:8f0bb79ddd48 65 *
leothedragon 0:8f0bb79ddd48 66 *
leothedragon 0:8f0bb79ddd48 67 *\b Special \b Operations
leothedragon 0:8f0bb79ddd48 68
leothedragon 0:8f0bb79ddd48 69 * -# rmfiles() Delete folder content (files only) (flat deletion).
leothedragon 0:8f0bb79ddd48 70 * -# cpfiles() Copy all files in the folder to a different folder (flat copy).
leothedragon 0:8f0bb79ddd48 71 *
leothedragon 0:8f0bb79ddd48 72 *
leothedragon 0:8f0bb79ddd48 73 * \subsection preq_sec Prerequisites
leothedragon 0:8f0bb79ddd48 74 * User need to set up the file system on your project and mount the proper drive if needed.
leothedragon 0:8f0bb79ddd48 75 *
leothedragon 0:8f0bb79ddd48 76 *
leothedragon 0:8f0bb79ddd48 77 * \subsection Limitations
leothedragon 0:8f0bb79ddd48 78 * -# File size: Up to 2 GiB.
leothedragon 0:8f0bb79ddd48 79 * -# Filename length: PAL_MAX_FILE_NAME_SIZE.
leothedragon 0:8f0bb79ddd48 80 * -# Legal characters for object name: (file/directory name) are, (0-9), (a-z), (A - Z) (_ . # ).
leothedragon 0:8f0bb79ddd48 81 * -# System is case-insensitive.
leothedragon 0:8f0bb79ddd48 82 * -# The root folder can manage a maximum of 512 entries.
leothedragon 0:8f0bb79ddd48 83 * -# Max path length is 66 Characters.
leothedragon 0:8f0bb79ddd48 84 * -# Folder shall be separated with "/"
leothedragon 0:8f0bb79ddd48 85 * -# All folder Paths shall end with "/"
leothedragon 0:8f0bb79ddd48 86 *
leothedragon 0:8f0bb79ddd48 87 *
leothedragon 0:8f0bb79ddd48 88 *
leothedragon 0:8f0bb79ddd48 89 * \subsection References
leothedragon 0:8f0bb79ddd48 90 * PAL_FileSystemSpecification.doc
leothedragon 0:8f0bb79ddd48 91 */
leothedragon 0:8f0bb79ddd48 92
leothedragon 0:8f0bb79ddd48 93 /*! @defgroup PAL_GROUP_FS File System Specification
leothedragon 0:8f0bb79ddd48 94 *
leothedragon 0:8f0bb79ddd48 95 *
leothedragon 0:8f0bb79ddd48 96 */
leothedragon 0:8f0bb79ddd48 97 /**
leothedragon 0:8f0bb79ddd48 98 @defgroup PAL_DEFINES PAL Services Defined Symbols & Macros
leothedragon 0:8f0bb79ddd48 99 @ingroup PAL_GROUP_FS
leothedragon 0:8f0bb79ddd48 100 */
leothedragon 0:8f0bb79ddd48 101
leothedragon 0:8f0bb79ddd48 102 /**
leothedragon 0:8f0bb79ddd48 103 @defgroup PAL_ENUM PAL Services Enumerated Data Types
leothedragon 0:8f0bb79ddd48 104 @ingroup PAL_GROUP_FS
leothedragon 0:8f0bb79ddd48 105 */
leothedragon 0:8f0bb79ddd48 106
leothedragon 0:8f0bb79ddd48 107 /**
leothedragon 0:8f0bb79ddd48 108 @defgroup PAL_PUBLIC_FUNCTION PAL Services Public Functions
leothedragon 0:8f0bb79ddd48 109 @ingroup PAL_GROUP_FS
leothedragon 0:8f0bb79ddd48 110 */
leothedragon 0:8f0bb79ddd48 111
leothedragon 0:8f0bb79ddd48 112 /**
leothedragon 0:8f0bb79ddd48 113 @addtogroup PAL_DEFINES
leothedragon 0:8f0bb79ddd48 114 @{*/
leothedragon 0:8f0bb79ddd48 115
leothedragon 0:8f0bb79ddd48 116
leothedragon 0:8f0bb79ddd48 117 #define PAL_MAX_FILE_NAME_SIZE 8 //!< Max length for file name received by user.
leothedragon 0:8f0bb79ddd48 118 #define PAL_MAX_FILE_NAME_SUFFIX 3 //!< Max length for file name suffix.
leothedragon 0:8f0bb79ddd48 119 #define PAL_MAX_FOLDER_DEPTH_CHAR 66 //!< Max folder length in chars.
leothedragon 0:8f0bb79ddd48 120 #define PAL_MAX_FILE_AND_FOLDER_LENGTH (PAL_MAX_FILE_NAME_SIZE + PAL_MAX_FILE_NAME_SUFFIX + PAL_MAX_FOLDER_DEPTH_CHAR + 1) //!< Maximum combined file and folder name length. Plus 1 is for the period that separates file name and file suffix.
leothedragon 0:8f0bb79ddd48 121 #define PAL_MAX_FULL_FILE_NAME (PAL_MAX_FILE_NAME_SUFFIX + PAL_MAX_FOLDER_DEPTH_CHAR + 1) //!< Maximum combined file name. Plus 1 is for the period that separates file name and file suffix.
leothedragon 0:8f0bb79ddd48 122
leothedragon 0:8f0bb79ddd48 123 typedef uintptr_t palFileDescriptor_t; //!< Pointer to a generic File Descriptor object
leothedragon 0:8f0bb79ddd48 124
leothedragon 0:8f0bb79ddd48 125 /**
leothedragon 0:8f0bb79ddd48 126 @} */
leothedragon 0:8f0bb79ddd48 127 /**
leothedragon 0:8f0bb79ddd48 128 @addtogroup PAL_ENUM
leothedragon 0:8f0bb79ddd48 129 @{*/
leothedragon 0:8f0bb79ddd48 130
leothedragon 0:8f0bb79ddd48 131 /** \brief Enum for `fseek()` relative options. */
leothedragon 0:8f0bb79ddd48 132 typedef enum {
leothedragon 0:8f0bb79ddd48 133 PAL_FS_OFFSET_KEEP_FIRST = 0,
leothedragon 0:8f0bb79ddd48 134 PAL_FS_OFFSET_SEEKSET, //!< Relative to the start of the file.
leothedragon 0:8f0bb79ddd48 135 PAL_FS_OFFSET_SEEKCUR, //!< The current position indicator.
leothedragon 0:8f0bb79ddd48 136 PAL_FS_OFFSET_SEEKEND, //!< End of file.
leothedragon 0:8f0bb79ddd48 137 PAL_FS_OFFSET_KEEP_LAST,
leothedragon 0:8f0bb79ddd48 138
leothedragon 0:8f0bb79ddd48 139 } pal_fsOffset_t;
leothedragon 0:8f0bb79ddd48 140
leothedragon 0:8f0bb79ddd48 141 /** \brief Enum for `fopen()` permission options*/
leothedragon 0:8f0bb79ddd48 142 typedef enum {
leothedragon 0:8f0bb79ddd48 143 PAL_FS_FLAG_KEEP_FIRST = 0,
leothedragon 0:8f0bb79ddd48 144 PAL_FS_FLAG_READONLY, //!< Open file for reading only. The stream is positioned at the beginning of the file, same as "r". \note File must exist.
leothedragon 0:8f0bb79ddd48 145 PAL_FS_FLAG_READWRITE, //!< Open for reading and writing. The stream is positioned at the beginning of the file, same as "r+ ". \note File must exist.
leothedragon 0:8f0bb79ddd48 146 PAL_FS_FLAG_READWRITEEXCLUSIVE, //!< Open for reading and writing exclusively. The stream is positioned at the beginning of the file. same as "w+x" \note If the file already exists, `fopen()` fails.
leothedragon 0:8f0bb79ddd48 147 PAL_FS_FLAG_READWRITETRUNC, //!< Open for reading and writing exclusively. The stream is positioned at the beginning of the file. same as "w+" \note If the file already exists, it is truncated.
leothedragon 0:8f0bb79ddd48 148 PAL_FS_FLAG_KEEP_LAST,
leothedragon 0:8f0bb79ddd48 149 } pal_fsFileMode_t;
leothedragon 0:8f0bb79ddd48 150 /**
leothedragon 0:8f0bb79ddd48 151 @} */
leothedragon 0:8f0bb79ddd48 152
leothedragon 0:8f0bb79ddd48 153
leothedragon 0:8f0bb79ddd48 154 /** \brief Enum for partition access. */
leothedragon 0:8f0bb79ddd48 155 typedef enum {
leothedragon 0:8f0bb79ddd48 156 PAL_FS_PARTITION_PRIMARY = 0, //!< Primary partition.\n
leothedragon 0:8f0bb79ddd48 157 PAL_FS_PARTITION_SECONDARY, //!< Secondary partition.\n
leothedragon 0:8f0bb79ddd48 158 PAL_FS_PARTITION_LAST //!< Must be last value.\n
leothedragon 0:8f0bb79ddd48 159 } pal_fsStorageID_t;
leothedragon 0:8f0bb79ddd48 160
leothedragon 0:8f0bb79ddd48 161
leothedragon 0:8f0bb79ddd48 162 /**
leothedragon 0:8f0bb79ddd48 163 @addtogroup PAL_PUBLIC_FUNCTION
leothedragon 0:8f0bb79ddd48 164 @{*/
leothedragon 0:8f0bb79ddd48 165
leothedragon 0:8f0bb79ddd48 166 /*! \brief This function attempts to create a directory named \c pathName.
leothedragon 0:8f0bb79ddd48 167 *
leothedragon 0:8f0bb79ddd48 168 * @param[in] *pathName A pointer to the null-terminated string that specifies the directory name to create.
leothedragon 0:8f0bb79ddd48 169 *
leothedragon 0:8f0bb79ddd48 170 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 171 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 172 *
leothedragon 0:8f0bb79ddd48 173 * \note To remove a directory, use \c PAL_ERR_FS_rmdir.
leothedragon 0:8f0bb79ddd48 174 *
leothedragon 0:8f0bb79ddd48 175 *\b Example
leothedragon 0:8f0bb79ddd48 176 \code{.cpp}
leothedragon 0:8f0bb79ddd48 177 palStatus_t ret;
leothedragon 0:8f0bb79ddd48 178 ret = PAL_ERR_FS_mkdir("Dir1");
leothedragon 0:8f0bb79ddd48 179 if(!ret)
leothedragon 0:8f0bb79ddd48 180 {
leothedragon 0:8f0bb79ddd48 181 //Error
leothedragon 0:8f0bb79ddd48 182 }
leothedragon 0:8f0bb79ddd48 183 \endcode
leothedragon 0:8f0bb79ddd48 184 */
leothedragon 0:8f0bb79ddd48 185 palStatus_t pal_fsMkDir(const char *pathName);
leothedragon 0:8f0bb79ddd48 186
leothedragon 0:8f0bb79ddd48 187 /*! \brief This function deletes a directory
leothedragon 0:8f0bb79ddd48 188 *
leothedragon 0:8f0bb79ddd48 189 * @param[in] *pathName A pointer to the null-terminated string that specifies the directory name to be deleted.
leothedragon 0:8f0bb79ddd48 190 *
leothedragon 0:8f0bb79ddd48 191 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 192 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 193 *
leothedragon 0:8f0bb79ddd48 194
leothedragon 0:8f0bb79ddd48 195 * \note The deleted directory \b must be both \e empty and \e closed and the
leothedragon 0:8f0bb79ddd48 196 * folder path end with \c / .
leothedragon 0:8f0bb79ddd48 197
leothedragon 0:8f0bb79ddd48 198 *
leothedragon 0:8f0bb79ddd48 199 *\b Example
leothedragon 0:8f0bb79ddd48 200 \code{.cpp}
leothedragon 0:8f0bb79ddd48 201 palStatus_t ret;
leothedragon 0:8f0bb79ddd48 202 ret = PAL_ERR_FS_mkdir("Dir1"); //Create folder name "Dir1"
leothedragon 0:8f0bb79ddd48 203 if(!ret)
leothedragon 0:8f0bb79ddd48 204 {
leothedragon 0:8f0bb79ddd48 205 //Error
leothedragon 0:8f0bb79ddd48 206 }
leothedragon 0:8f0bb79ddd48 207 ret = PAL_ERR_FS_rmdir("Dir1); //Remove directory from partition
leothedragon 0:8f0bb79ddd48 208 if(!ret)
leothedragon 0:8f0bb79ddd48 209 {
leothedragon 0:8f0bb79ddd48 210 //Error
leothedragon 0:8f0bb79ddd48 211 }
leothedragon 0:8f0bb79ddd48 212 \endcode
leothedragon 0:8f0bb79ddd48 213 */
leothedragon 0:8f0bb79ddd48 214 palStatus_t pal_fsRmDir(const char *pathName);
leothedragon 0:8f0bb79ddd48 215
leothedragon 0:8f0bb79ddd48 216
leothedragon 0:8f0bb79ddd48 217 /*!\brief This function opens the file whose name is specified in the parameter `pathName` and associates it with a stream
leothedragon 0:8f0bb79ddd48 218 * that can be identified in future operations by the `fd` pointer returned.
leothedragon 0:8f0bb79ddd48 219 *
leothedragon 0:8f0bb79ddd48 220 * @param[out] fd The file descriptor to the file entered in the `pathName`.
leothedragon 0:8f0bb79ddd48 221 * @param[in] *pathName A pointer to the null-terminated string that specifies the file name to open or create.
leothedragon 0:8f0bb79ddd48 222 * @param[in] mode A mode flag that specifies the type of access and open method for the file.
leothedragon 0:8f0bb79ddd48 223 *
leothedragon 0:8f0bb79ddd48 224 *
leothedragon 0:8f0bb79ddd48 225 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 226 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 227 *
leothedragon 0:8f0bb79ddd48 228 * \note The folder path shall end with "/".
leothedragon 0:8f0bb79ddd48 229 *
leothedragon 0:8f0bb79ddd48 230 *\b Example
leothedragon 0:8f0bb79ddd48 231 \code{.cpp}
leothedragon 0:8f0bb79ddd48 232 //Copy File from "File1" to "File2"
leothedragon 0:8f0bb79ddd48 233 palStatus_t ret;
leothedragon 0:8f0bb79ddd48 234 palFileDescriptor_t fd1 = NULL,fd2 = NULL ; // File Object 1 & 2
leothedragon 0:8f0bb79ddd48 235 uint8 buffer[1024];
leothedragon 0:8f0bb79ddd48 236 size_t bytes_read = 0, Bytes_wrote = 0;
leothedragon 0:8f0bb79ddd48 237
leothedragon 0:8f0bb79ddd48 238 //Open first file with Read permission
leothedragon 0:8f0bb79ddd48 239 ret = PAL_ERR_FS_fopen(&fd1, "File1", PAL_ERR_FS_READWRITEEXCLUSIVE);
leothedragon 0:8f0bb79ddd48 240 if(ret) {//Error}
leothedragon 0:8f0bb79ddd48 241
leothedragon 0:8f0bb79ddd48 242 //Create second file with Read/Write permissions
leothedragon 0:8f0bb79ddd48 243 ret = PAL_ERR_FS_fopen(&fd2, "File2", PAL_ERR_FS_READWRITEEXCLUSIVE);
leothedragon 0:8f0bb79ddd48 244 if(ret) {//Error}
leothedragon 0:8f0bb79ddd48 245
leothedragon 0:8f0bb79ddd48 246 // Copy source to destination
leothedragon 0:8f0bb79ddd48 247 for (;;)
leothedragon 0:8f0bb79ddd48 248 {
leothedragon 0:8f0bb79ddd48 249 ret = PAL_ERR_FS_read(&fd1, buffer, sizeof(buffer), &bytes_read); // Read a chunk of source file
leothedragon 0:8f0bb79ddd48 250 if (ret || bytes_read == 0) break; // error or EOF
leothedragon 0:8f0bb79ddd48 251 ret = PAL_ERR_FS_write(&fd2, buffer, sizeof(buffer), &Bytes_wrote); // Write it to the destination file
leothedragon 0:8f0bb79ddd48 252 if (ret || Bytes_wrote < bytes_read) break; // error or disk full
leothedragon 0:8f0bb79ddd48 253 }
leothedragon 0:8f0bb79ddd48 254
leothedragon 0:8f0bb79ddd48 255 PAL_ERR_FS_close(&fd1);
leothedragon 0:8f0bb79ddd48 256 PAL_ERR_FS_close(&fd2);
leothedragon 0:8f0bb79ddd48 257 }
leothedragon 0:8f0bb79ddd48 258 \endcode
leothedragon 0:8f0bb79ddd48 259 */
leothedragon 0:8f0bb79ddd48 260 palStatus_t pal_fsFopen(const char *pathName, pal_fsFileMode_t mode,
leothedragon 0:8f0bb79ddd48 261 palFileDescriptor_t *fd);
leothedragon 0:8f0bb79ddd48 262
leothedragon 0:8f0bb79ddd48 263 /*! \brief This function closes an open file object.
leothedragon 0:8f0bb79ddd48 264 *
leothedragon 0:8f0bb79ddd48 265 * @param[in] fd A pointer to the open file object structure to be closed.
leothedragon 0:8f0bb79ddd48 266 *
leothedragon 0:8f0bb79ddd48 267 *
leothedragon 0:8f0bb79ddd48 268 * \return PAL_SUCCESS upon successful operation. \n
leothedragon 0:8f0bb79ddd48 269 * PAL_FILE_SYSTEM_ERROR - see error code \c palError_t.
leothedragon 0:8f0bb79ddd48 270 *
leothedragon 0:8f0bb79ddd48 271 * \note When the function has completed successfully, the file object is no longer valid and it can be discarded.
leothedragon 0:8f0bb79ddd48 272 *
leothedragon 0:8f0bb79ddd48 273 */
leothedragon 0:8f0bb79ddd48 274 palStatus_t pal_fsFclose(palFileDescriptor_t *fd);
leothedragon 0:8f0bb79ddd48 275
leothedragon 0:8f0bb79ddd48 276
leothedragon 0:8f0bb79ddd48 277 /*! \brief This function reads an array of bytes from the stream and stores it in the block of memory
leothedragon 0:8f0bb79ddd48 278 * specified by `buffer`. The position indicator of the stream is advanced by the total amount of bytes read.
leothedragon 0:8f0bb79ddd48 279 *
leothedragon 0:8f0bb79ddd48 280 * @param[in] fd A pointer to the open file object structure.
leothedragon 0:8f0bb79ddd48 281 * @param[in] buffer The buffer to store the read data.
leothedragon 0:8f0bb79ddd48 282 * @param[in] numOfBytes The number of bytes to read.
leothedragon 0:8f0bb79ddd48 283 * @param[out] numberOfBytesRead The number of bytes read.
leothedragon 0:8f0bb79ddd48 284
leothedragon 0:8f0bb79ddd48 285 *
leothedragon 0:8f0bb79ddd48 286 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 287 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 288 *
leothedragon 0:8f0bb79ddd48 289 * \note When the function has completed successfully,
leothedragon 0:8f0bb79ddd48 290 * `numberOfBytesRead` should be checked to detect end of the file.
leothedragon 0:8f0bb79ddd48 291 * If `numberOfBytesRead` is less than `numOfBytes`,
leothedragon 0:8f0bb79ddd48 292 * the read/write pointer has reached the end of the file during the read operation or there is an error.
leothedragon 0:8f0bb79ddd48 293 *
leothedragon 0:8f0bb79ddd48 294 */
leothedragon 0:8f0bb79ddd48 295 palStatus_t pal_fsFread(palFileDescriptor_t *fd, void * buffer,
leothedragon 0:8f0bb79ddd48 296 size_t numOfBytes, size_t *numberOfBytesRead);
leothedragon 0:8f0bb79ddd48 297
leothedragon 0:8f0bb79ddd48 298 /*! \brief This function starts to write data from \c buffer to the file at the position pointed by the read/write pointer.
leothedragon 0:8f0bb79ddd48 299 *
leothedragon 0:8f0bb79ddd48 300 * @param[in] fd A pointer to the open file object structure.
leothedragon 0:8f0bb79ddd48 301 * @param[in] buffer A pointer to the data to be written.
leothedragon 0:8f0bb79ddd48 302 * @param[in] numOfBytes The number of bytes to write.
leothedragon 0:8f0bb79ddd48 303 * @param[out] numberOfBytesWritten The number of bytes written.
leothedragon 0:8f0bb79ddd48 304 *
leothedragon 0:8f0bb79ddd48 305 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 306 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 307 *
leothedragon 0:8f0bb79ddd48 308 * \note The read/write pointer advances as number of bytes written. When the function has completed successfully,
leothedragon 0:8f0bb79ddd48 309 * \note `numberOfBytesWritten` should be checked to detect the whether the disk is full.
leothedragon 0:8f0bb79ddd48 310 * If `numberOfBytesWritten` is less than `numOfBytes`, the volume got full during the write operation.
leothedragon 0:8f0bb79ddd48 311 *
leothedragon 0:8f0bb79ddd48 312 */
leothedragon 0:8f0bb79ddd48 313 palStatus_t pal_fsFwrite(palFileDescriptor_t *fd, const void * buffer,
leothedragon 0:8f0bb79ddd48 314 size_t numOfBytes, size_t *numberOfBytesWritten);
leothedragon 0:8f0bb79ddd48 315
leothedragon 0:8f0bb79ddd48 316
leothedragon 0:8f0bb79ddd48 317 /*! \brief This function moves the file read/write pointer without any read/write operation to the file.
leothedragon 0:8f0bb79ddd48 318 *
leothedragon 0:8f0bb79ddd48 319 * @param[in] fd A pointer to the open file object structure.
leothedragon 0:8f0bb79ddd48 320 * @param[in] offset The byte offset from the top of the file to set the read/write pointer.
leothedragon 0:8f0bb79ddd48 321 * @param[out] whence Where the offset is relative to.
leothedragon 0:8f0bb79ddd48 322 *
leothedragon 0:8f0bb79ddd48 323 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 324 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 325 *
leothedragon 0:8f0bb79ddd48 326 * \note The `whence` options are: \n
leothedragon 0:8f0bb79ddd48 327 * -# PAL_ERR_FS_SEEKSET - Relative to the start of the file.
leothedragon 0:8f0bb79ddd48 328 * -# PAL_ERR_FS_SEEKCUR - The current position indicator.
leothedragon 0:8f0bb79ddd48 329 * -# PAL_ERR_FS_SEEKEND - End-of-file.
leothedragon 0:8f0bb79ddd48 330 *
leothedragon 0:8f0bb79ddd48 331 *\b Example
leothedragon 0:8f0bb79ddd48 332 \code{.cpp}
leothedragon 0:8f0bb79ddd48 333 palStatus_t ret;
leothedragon 0:8f0bb79ddd48 334 palFileDescriptor_t fd1 = NULL; // File Object 1
leothedragon 0:8f0bb79ddd48 335 uint8 buffer[1024];
leothedragon 0:8f0bb79ddd48 336 size_t bytes_read = 0, Bytes_wrote = 0;
leothedragon 0:8f0bb79ddd48 337
leothedragon 0:8f0bb79ddd48 338 //Open file with Read permission
leothedragon 0:8f0bb79ddd48 339 ret = PAL_ERR_FS_fopen(&fd1, "File1", PAL_ERR_FS_READ);
leothedragon 0:8f0bb79ddd48 340 if(ret) {//Error}
leothedragon 0:8f0bb79ddd48 341
leothedragon 0:8f0bb79ddd48 342 ret = PAL_ERR_FS_fseek(&fd1, 500, PAL_ERR_FS_SEEKSET)
leothedragon 0:8f0bb79ddd48 343
leothedragon 0:8f0bb79ddd48 344 \endcode
leothedragon 0:8f0bb79ddd48 345 */
leothedragon 0:8f0bb79ddd48 346 palStatus_t pal_fsFseek(palFileDescriptor_t *fd, int32_t offset,
leothedragon 0:8f0bb79ddd48 347 pal_fsOffset_t whence);
leothedragon 0:8f0bb79ddd48 348
leothedragon 0:8f0bb79ddd48 349 /*! \brief This function gets the current read/write pointer of a file.
leothedragon 0:8f0bb79ddd48 350 *
leothedragon 0:8f0bb79ddd48 351 * @param[in] fd A pointer to the open file object structure.
leothedragon 0:8f0bb79ddd48 352 *
leothedragon 0:8f0bb79ddd48 353 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 354 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 355 *
leothedragon 0:8f0bb79ddd48 356 */
leothedragon 0:8f0bb79ddd48 357 palStatus_t pal_fsFtell(palFileDescriptor_t *fd, int32_t *pos);
leothedragon 0:8f0bb79ddd48 358
leothedragon 0:8f0bb79ddd48 359 /*! \brief This function deletes a \e single file from the file system.
leothedragon 0:8f0bb79ddd48 360 *
leothedragon 0:8f0bb79ddd48 361 * @param[in] pathName A pointer to a null-terminated string that specifies the file to be removed.
leothedragon 0:8f0bb79ddd48 362 *
leothedragon 0:8f0bb79ddd48 363 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 364 * \return PAL_FILE_SYSTEM_ERROR - see error code description \c palError_t.
leothedragon 0:8f0bb79ddd48 365 *
leothedragon 0:8f0bb79ddd48 366 * \note The file must \b not \b be \b open.
leothedragon 0:8f0bb79ddd48 367 *
leothedragon 0:8f0bb79ddd48 368 */
leothedragon 0:8f0bb79ddd48 369 palStatus_t pal_fsUnlink(const char *pathName);
leothedragon 0:8f0bb79ddd48 370
leothedragon 0:8f0bb79ddd48 371 /*! \brief This function deletes \b all files and folders in a specified folder from the file system. Flat remove only.
leothedragon 0:8f0bb79ddd48 372 *
leothedragon 0:8f0bb79ddd48 373 * @param[in] pathName A pointer to a null-terminated string that specifies the folder.
leothedragon 0:8f0bb79ddd48 374 *
leothedragon 0:8f0bb79ddd48 375 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 376 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 377 *
leothedragon 0:8f0bb79ddd48 378 * \note The folder must \b not \b be \b open and the folder path must end with \c / .
leothedragon 0:8f0bb79ddd48 379 */
leothedragon 0:8f0bb79ddd48 380 palStatus_t pal_fsRmFiles(const char *pathName);
leothedragon 0:8f0bb79ddd48 381
leothedragon 0:8f0bb79ddd48 382 /*! \brief This function copies \b all files from the source folder to the destination folder. Flat copy only.
leothedragon 0:8f0bb79ddd48 383 *
leothedragon 0:8f0bb79ddd48 384 * @param[in] pathNameSrc A pointer to a null-terminated string that specifies the source folder.
leothedragon 0:8f0bb79ddd48 385 * @param[in] pathNameDest A pointer to a null-terminated string that specifies the destination folder. The folder MUST already exist.
leothedragon 0:8f0bb79ddd48 386 *
leothedragon 0:8f0bb79ddd48 387 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 388 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 389 *
leothedragon 0:8f0bb79ddd48 390 * \note Both folders must \b not \b be \b open. If the folders do not exist, the function fails.
leothedragon 0:8f0bb79ddd48 391 *
leothedragon 0:8f0bb79ddd48 392 */
leothedragon 0:8f0bb79ddd48 393 palStatus_t pal_fsCpFolder(const char *pathNameSrc, char *pathNameDest);
leothedragon 0:8f0bb79ddd48 394
leothedragon 0:8f0bb79ddd48 395 /*! \brief This function sets the mount directory for the given storage ID (primary or secondary),
leothedragon 0:8f0bb79ddd48 396 *
leothedragon 0:8f0bb79ddd48 397 * @param[in] Path A pointer to a null-terminated string that specifies the root folder.
leothedragon 0:8f0bb79ddd48 398 *
leothedragon 0:8f0bb79ddd48 399 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 400 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 401 *
leothedragon 0:8f0bb79ddd48 402 * \note If called with \c NULL, the ESFS root folder is set to default PAL_SOURCE_FOLDER.
leothedragon 0:8f0bb79ddd48 403 * \note The folder path must end with \c / .
leothedragon 0:8f0bb79ddd48 404 */
leothedragon 0:8f0bb79ddd48 405 palStatus_t pal_fsSetMountPoint(pal_fsStorageID_t dataID, const char *Path);
leothedragon 0:8f0bb79ddd48 406
leothedragon 0:8f0bb79ddd48 407 /*! \brief This function gets the mount directory for the given storage ID (primary or secondary), The function copies the path to the user pre allocated buffer.
leothedragon 0:8f0bb79ddd48 408 *
leothedragon 0:8f0bb79ddd48 409 * @param[in] length The length of the buffer.
leothedragon 0:8f0bb79ddd48 410 * @param[out] Path A pointer to a \e pre-allocated \e buffer with size \c PAL_MAX_FOLDER_DEPTH_CHAR + 1 chars. The plus 1 is to account for the '\0' terminator at the end of the buffer
leothedragon 0:8f0bb79ddd48 411 *
leothedragon 0:8f0bb79ddd48 412 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 413 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
leothedragon 0:8f0bb79ddd48 414 *
leothedragon 0:8f0bb79ddd48 415 */
leothedragon 0:8f0bb79ddd48 416 palStatus_t pal_fsGetMountPoint(pal_fsStorageID_t dataID, size_t length, char *Path);
leothedragon 0:8f0bb79ddd48 417
leothedragon 0:8f0bb79ddd48 418 /*! \brief This function formats a given SD partition.
leothedragon 0:8f0bb79ddd48 419 *
leothedragon 0:8f0bb79ddd48 420 * @param[in] dataID The ID of the partition to be formatted.
leothedragon 0:8f0bb79ddd48 421 *
leothedragon 0:8f0bb79ddd48 422 * \return PAL_SUCCESS upon successful operation.
leothedragon 0:8f0bb79ddd48 423 * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t. \n
leothedragon 0:8f0bb79ddd48 424 * \return PAL_ERR_INVALID_ARGUMENT an invalid `partitionID`.
leothedragon 0:8f0bb79ddd48 425 *
leothedragon 0:8f0bb79ddd48 426 * \note The actual partition values mapped to the IDs is determined by the porting layer.
leothedragon 0:8f0bb79ddd48 427 */
leothedragon 0:8f0bb79ddd48 428 palStatus_t pal_fsFormat(pal_fsStorageID_t dataID);
leothedragon 0:8f0bb79ddd48 429
leothedragon 0:8f0bb79ddd48 430 /*! \brief This function will return whether a given partition is used only by PAL or not.
leothedragon 0:8f0bb79ddd48 431 *
leothedragon 0:8f0bb79ddd48 432 * @param[in] dataID - the ID of the data to be cleared.
leothedragon 0:8f0bb79ddd48 433 *
leothedragon 0:8f0bb79ddd48 434 * \return true - if partition is used only by pal.
leothedragon 0:8f0bb79ddd48 435 * \return false - if partition is used by other component then pal.
leothedragon 0:8f0bb79ddd48 436 *
leothedragon 0:8f0bb79ddd48 437 * \note The actual partition values mapped the IDs will be determined by the porting layer.
leothedragon 0:8f0bb79ddd48 438 */
leothedragon 0:8f0bb79ddd48 439 bool pal_fsIsPrivatePartition(pal_fsStorageID_t dataID);
leothedragon 0:8f0bb79ddd48 440
leothedragon 0:8f0bb79ddd48 441
leothedragon 0:8f0bb79ddd48 442 /*! \brief This function will perform clean up on all file system resources.
leothedragon 0:8f0bb79ddd48 443 */
leothedragon 0:8f0bb79ddd48 444 void pal_fsCleanup(void);
leothedragon 0:8f0bb79ddd48 445
leothedragon 0:8f0bb79ddd48 446
leothedragon 0:8f0bb79ddd48 447 /**
leothedragon 0:8f0bb79ddd48 448 @} */
leothedragon 0:8f0bb79ddd48 449
leothedragon 0:8f0bb79ddd48 450 #endif//test