ss_engine/SS_FSUpdate.h

   1 /*
   2  * libtota
   3  *
   4  * Copyright (c) 2017 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License);
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 /*!
  20  *******************************************************************************
  21  * \file        SS_FileSystemUpdate.h
  22  *
  23  * \brief       UPI FS Update API
  24  *******************************************************************************
  25  */
  26 #ifndef _SS_FILESYSTEM_UPDATE_H_
  27 #define _SS_FILESYSTEM_UPDATE_H_
  28
  29 #include "SS_Engine_Update.h"
  30 #include "SS_Engine_Errors.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif                          /* __cplusplus */
  35
  36 /*!
  37  * File access modes
  38  */
  39     typedef enum tag_RW_TYPE {
  40         ONLY_R,                 //!< Read-only
  41         ONLY_W,                 //!< Write-only
  42         BOTH_RW                 //!< Read-write
  43     } E_RW_TYPE;
  44
  45 /*!
  46  *******************************************************************************
  47  * Copy file.<p>
  48  *
  49  * Must create the path to the new file as required. Must overwrite any contents
  50  * in the old file, if any. Must check if the source file is a symbolic link.
  51  * If it is, instead create a new symbolic link using \ref SS_Link.
  52  *
  53  * \param       pbUserData      Optional opaque data-structure to pass to IPL
  54  *                                              functions
  55  * \param       strFromPath     Path to old file
  56  * \param       strToPath       Path to new file
  57  *
  58  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
  59  *******************************************************************************
  60  */
  61
  62     long SS_CopyFile(void *pbUserData, const char *strFromPath, const char *strToPath);
  63
  64 /*!
  65  *******************************************************************************
  66  * Move (rename) file.<p>
  67  *
  68  * \param       pbUserData      Optional opaque data-structure to pass to IPL
  69  *                                              functions
  70  * \param       strFromPath     Path to old file location
  71  * \param       strToPath       Path to new file location
  72  *
  73  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
  74  *******************************************************************************
  75  */
  76
  77     long SS_MoveFile(void *pbUserData, const char *strFromPath, const char *strToPath);
  78
  79 /*!
  80  *******************************************************************************
  81  * Delete file.<p>
  82  *
  83  * Must return success if the file is deleted or didn't exist.
  84  *
  85  * \param       pbUserData      Optional opaque data-structure to pass to IPL
  86  *                                              functions
  87  * \param       strPath         Path to file
  88  *
  89  * \return      S_SS_SUCCESS on success, E_SS_DELETEFILE if the file cannot be
  90  *                      deleted, or an \ref SS_vRM_Errors.h error code
  91  *******************************************************************************
  92  */
  93
  94     long SS_DeleteFile(void *pbUserData, const char *strPath);
  95
  96 /*!
  97  *******************************************************************************
  98  * Delete folder.<p>
  99  *
 100  * Must return success if the folder is now deleted or didn't exist.
 101  *
 102  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 103  *                                              functions
 104  * \param       strPath         Path to folder
 105  *
 106  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 107  *******************************************************************************
 108  */
 109
 110     long SS_DeleteFolder(void *pbUserData, const char *strPath);
 111
 112 /*!
 113  *******************************************************************************
 114  * Create folder.<p>
 115  *
 116  * Must return success if the folder is created or already existsed. It is
 117  * recommended that the new folder's attributes are a copy of its parent's
 118  * attributes.
 119  *
 120  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 121  *                                              functions
 122  * \param       strPath         Path to folder
 123  *
 124  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 125  *******************************************************************************
 126  */
 127
 128     long SS_CreateFolder(void *pbUserData, const char *strPath);
 129
 130 /*!
 131  *******************************************************************************
 132  * Open file.<p>
 133  *
 134  * Must create the the file (and the path to the file) if it doesn't exist. Must
 135  * open in binary mode.
 136  *
 137  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 138  *                                              functions
 139  * \param       strPath         Path to file
 140  * \param       wFlag           Read/write mode, an \ref E_RW_TYPE value
 141  * \param       pwHandle        (out) File handle
 142  *
 143  * \return      S_SS_SUCCESS on success, E_SS_OPENFILE_ONLYR if attempting to open a
 144  *                      non-existant file in R/O mode, E_SS_OPENFILE_WRITE if there is an
 145  *                      error opening a file for writing, or an \ref SS_vRM_Errors.h error code
 146  *******************************************************************************
 147  */
 148
 149     long SS_OpenFile(void *pbUserData, const char *strPath, E_RW_TYPE wFlag, long *pwHandle);
 150
 151 /*!
 152  *******************************************************************************
 153  * Set file size.
 154  *
 155  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 156  *                                              functions
 157  * \param       wHandle         File handle
 158  * \param       dwSize          New file size
 159  *
 160  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 161  *******************************************************************************
 162  */
 163
 164     long SS_ResizeFile(void *pbUserData, long wHandle, SS_UINT32 dwSize);
 165
 166 /*!
 167  *******************************************************************************
 168  * Close file.
 169  *
 170  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 171  *                                              functions
 172  * \param       wHandle         File handle
 173  *
 174  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 175  *******************************************************************************
 176  */
 177
 178     long SS_CloseFile(void *pbUserData, long wHandle);
 179
 180 /*!
 181  *******************************************************************************
 182  * Write data to a specified position within a file.<p>
 183  *
 184  * Must return success if the block is written or at least resides in
 185  * non-volatile memory. Use \ref SS_SyncFile to commit the file to storage.
 186  *
 187  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 188  *                                              functions
 189  * \param       wHandle         File handle
 190  * \param       dwPosition      Position within the file to which to write
 191  * \param       pbBuffer        Data to write
 192  * \param       dwSize          Size of \a pbBuffer
 193  *
 194  * \return      S_SS_SUCCESS on success, or an \ref SS_vRM_Errors.h error code
 195  *******************************************************************************
 196  */
 197
 198     long SS_WriteFile(void *pbUserData, long wHandle, SS_UINT32 dwPosition, unsigned char *pbBuffer, SS_UINT32 dwSize);
 199
 200 /*!
 201  *******************************************************************************
 202  * Commit file to storage.<p>
 203  *
 204  * Generally called after \ref SS_WriteFile.
 205  *
 206  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 207  *                                              functions
 208  * \param       wHandle         File handle
 209  *
 210  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 211  *******************************************************************************
 212  */
 213     long SS_SyncFile(void *pbUserData, long wHandle);
 214
 215 /*!
 216  *******************************************************************************
 217  * Read data from a specified position within a file.
 218  * If fewer bytes than requested are available in the specified position, this
 219  * function should read up to the end of file and return S_SS_SUCCESS.
 220  *
 221  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 222  *                                              functions
 223  * \param       wHandle         File handle
 224  * \param       dwPosition      Position within the file from which to read
 225  * \param       pbBuffer        Buffer to contain data
 226  * \param       dwSize          Size of data to read
 227  *
 228  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 229  *******************************************************************************
 230  */
 231
 232     long SS_ReadFile(void *pbUserData, long wHandle, SS_UINT32 dwPosition, unsigned char *pbBuffer, SS_UINT32 dwSize);
 233
 234 /*!
 235  *******************************************************************************
 236  * Get file size.
 237  *
 238  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 239  *                                              functions
 240  * \param       wHandle         File handle
 241  *
 242  * \return      File size, -1 if file not found, or &lt; -1 on error
 243  *******************************************************************************
 244  */
 245     long SS_GetFileSize(void *pbUserData, long wHandle);
 246
 247 /*!
 248  *******************************************************************************
 249  * Get free space of a mounted file system.
 250  *
 251  * \param       pbUserData                              Optional opaque data-structure to pass to
 252  *                                                                      IPL functions
 253  * \param       path                                Name of any directory within the mounted
 254  *                                                                      file system
 255  * \param       available_flash_size    (out) Available space
 256  *
 257  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 258  *******************************************************************************
 259  */
 260     long SS_GetAvailableFreeSpace(void *pbUserData, const char *path, SS_UINT32 * available_flash_size);
 261
 262 /*!
 263  *******************************************************************************
 264  * Remove symbolic link.<p>
 265  *
 266  * Must return an error if the file does not exist or is not a symbolic link.<p>
 267  *
 268  * If your platform does not support symbolic links, you do not need to
 269  * implement this.
 270  *
 271  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 272  *                                              functions
 273  * \param       pLinkName       Link
 274  *
 275  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 276  *******************************************************************************
 277  */
 278     long SS_Unlink(void *pbUserData, char *pLinkName);
 279
 280 /*!
 281  *******************************************************************************
 282  * Create symbolic link.<p>
 283  *
 284  * Must create the path to the link as required. If a file already exists at the
 285  * named location, must return success if the file is a symbolic link or an
 286  * error if the file is a regular file. The non-existance of the target of the
 287  * link must NOT cause an error.<p>
 288  *
 289  * If your platform does not support symbolic links, you do not need to
 290  * implement this.
 291  *
 292  * \param       pbUserData                      Optional opaque data-structure to pass to IPL
 293  *                                                              functions
 294  * \param       pLinkName                       Path to the link file to create
 295  * \param       pReferenceFileName      Path to which to point the link
 296  *
 297  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 298  *******************************************************************************
 299  */
 300     long SS_Link(void *pbUserData, char *pLinkName, char *pReferenceFileName);
 301
 302 /*!
 303  *******************************************************************************
 304  * Set file attributes.<p>
 305  *
 306  * The file attributes token (\a ui8pAttribs) is defined at generation time.
 307  * If attributes are not defined explicitly, they are given the following,
 308  * OS-dependent values:
 309  * \li  Windows: _redbend_ro_ for R/O files, _redbend_rw_ for R/W files
 310  * \li  Linux: _redbend_oooooo:xxxx:yyyy indicating the file mode, uid, and gid
 311  *              (uid and gid use capitalized hex digits as required)
 312  *
 313  * \param       pbUserData              Optional opaque data-structure to pass to IPL
 314  *                                                      functions
 315  * \param       ui16pFilePath   File path
 316  * \param       ui32AttribSize  Size of \a ui8pAttribs
 317  * \param       ui8pAttribs             Attributes to set
 318  *
 319  * \return      S_SS_SUCCESS on success or &lt; 0 on error
 320  *******************************************************************************
 321  */
 322
 323     long SS_SetFileAttributes(const char *ui16pFilePath,
 324                               const SS_UINT32 ui32AttribSize, const unsigned char *ui8pAttribs);
 325
 326 /*!
 327  *******************************************************************************
 328  * Print status and debug information.
 329  *
 330  * \param       pbUserData      Optional opaque data-structure to pass to IPL
 331  *                                              functions
 332  * \param       aFormat         A NULL-terminated printf-like string with support for
 333  *                                              the following tags:
 334  *                                              \li %x:  Hex number
 335  *                                              \li %0x: Hex number with leading zeros
 336  *                                              \li %u:  Unsigned decimal
 337  *                                              \li %s:  NULL-terminated string
 338  * \param       ...                     Strings to insert in \a aFormat
 339  *
 340  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 341  *******************************************************************************
 342  */
 343     SS_UINT32 SS_Trace(void *pbUserData, const char *aFormat, ...
 344         );
 345
 346 #ifdef __cplusplus
 347 }
 348 #endif                          /* __cplusplus */
 349 #endif