src/delta-ua/engine/SS_FSUpdate.h

   1 /*
   2  * delta-ua
   3  *
   4  * Copyright (c) 2017 - 2022 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_Errors.h"
  30 #include "ua_types.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  * Copy file.<p>
  47  *
  48  * Must create the path to the new file as required. Must overwrite any contents
  49  * in the old file, if any. Must check if the source file is a symbolic link.
  50  * If it is, instead create a new symbolic link using \ref SS_Link.
  51  *
  52  * \param       strFromPath     Path to old file
  53  * \param       strToPath       Path to new file
  54  *
  55  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
  56  *******************************************************************************
  57  */
  58
  59         long SS_CopyFile(const char *strFromPath, const char *strToPath);
  60
  61 /*!
  62  *******************************************************************************
  63  * Move (rename) file.<p>
  64  *
  65  * \param       strFromPath     Path to old file location
  66  * \param       strToPath       Path to new file location
  67  *
  68  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
  69  *******************************************************************************
  70  */
  71
  72         long SS_MoveFile(const char *strFromPath, const char *strToPath);
  73
  74 /*!
  75  *******************************************************************************
  76  * Delete file.<p>
  77  *
  78  * Must return success if the file is deleted or didn't exist.
  79  *
  80  * \param       strPath         Path to file
  81  *
  82  * \return      S_SS_SUCCESS on success, E_SS_DELETEFILE if the file cannot be
  83  *                      deleted, or an \ref SS_vRM_Errors.h error code
  84  *******************************************************************************
  85  */
  86
  87         long SS_DeleteFile(const char *strPath);
  88
  89 /*!
  90  *******************************************************************************
  91  * Delete folder.<p>
  92  *
  93  * Must return success if the folder is now deleted or didn't exist.
  94  *
  95  * \param       strPath         Path to folder
  96  *
  97  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
  98  *******************************************************************************
  99  */
 100
 101         long SS_DeleteFolder(const char *strPath);
 102
 103 /*!
 104  *******************************************************************************
 105  * Create folder.<p>
 106  *
 107  * Must return success if the folder is created or already existsed. It is
 108  * recommended that the new folder's attributes are a copy of its parent's
 109  * attributes.
 110  *
 111  * \param       strPath         Path to folder
 112  *
 113  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 114  *******************************************************************************
 115  */
 116
 117         long SS_CreateFolder(const char *strPath);
 118
 119 /*!
 120  *******************************************************************************
 121  * Open file.<p>
 122  *
 123  * Must create the the file (and the path to the file) if it doesn't exist. Must
 124  * open in binary mode.
 125  *
 126  * \param       strPath         Path to file
 127  * \param       wFlag           Read/write mode, an \ref E_RW_TYPE value
 128  * \param       pwHandle        (out) File handle
 129  *
 130  * \return      S_SS_SUCCESS on success, E_SS_OPENFILE_ONLYR if attempting to open a
 131  *                      non-existant file in R/O mode, E_SS_OPENFILE_WRITE if there is an
 132  *                      error opening a file for writing, or an \ref SS_vRM_Errors.h error code
 133  *******************************************************************************
 134  */
 135
 136         long SS_OpenFile(const char *strPath, E_RW_TYPE wFlag, long *pwHandle);
 137
 138 /*!
 139  *******************************************************************************
 140  * Close file.
 141  *
 142  * \param       wHandle         File handle
 143  *
 144  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 145  *******************************************************************************
 146  */
 147
 148         long SS_CloseFile(long wHandle);
 149
 150 /*!
 151  *******************************************************************************
 152  * Write data to a specified position within a file.<p>
 153  *
 154  * Must return success if the block is written or at least resides in
 155  * non-volatile memory. Use \ref SS_SyncFile to commit the file to storage.
 156  *
 157  * \param       wHandle         File handle
 158  * \param       dwPosition      Position within the file to which to write
 159  * \param       pbBuffer        Data to write
 160  * \param       dwSize          Size of \a pbBuffer
 161  *
 162  * \return      S_SS_SUCCESS on success, or an \ref SS_vRM_Errors.h error code
 163  *******************************************************************************
 164  */
 165
 166         long SS_WriteFile(long wHandle, SS_UINT32 dwPosition, unsigned char *pbBuffer, SS_UINT32 dwSize);
 167
 168 /*!
 169  *******************************************************************************
 170  * Read data from a specified position within a file.
 171  * If fewer bytes than requested are available in the specified position, this
 172  * function should read up to the end of file and return S_SS_SUCCESS.
 173  *
 174  * \param       wHandle         File handle
 175  * \param       dwPosition      Position within the file from which to read
 176  * \param       pbBuffer        Buffer to contain data
 177  * \param       dwSize          Size of data to read
 178  *
 179  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 180  *******************************************************************************
 181  */
 182
 183         long SS_ReadFile(long wHandle, SS_UINT32 dwPosition, unsigned char *pbBuffer, SS_UINT32 dwSize);
 184
 185 /*!
 186  *******************************************************************************
 187  * Get file size.
 188  *
 189  * \param       wHandle         File handle
 190  *
 191  * \return      File size, -1 if file not found, or &lt; -1 on error
 192  *******************************************************************************
 193  */
 194         long SS_GetFileSize(long wHandle);
 195
 196 /*!
 197  *******************************************************************************
 198  * Get free space of a mounted file system.
 199  *
 200  * \param       path                                Name of any directory within the mounted
 201  *                                                                      file system
 202  * \param       available_flash_size    (out) Available space
 203  *
 204  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 205  *******************************************************************************
 206  */
 207         long SS_GetAvailableFreeSpace(const char *path, SS_UINT32 * available_flash_size);
 208
 209 /*!
 210  *******************************************************************************
 211  * Remove symbolic link.<p>
 212  *
 213  * Must return an error if the file does not exist or is not a symbolic link.<p>
 214  *
 215  * If your platform does not support symbolic links, you do not need to
 216  * implement this.
 217  *
 218  * \param       pLinkName       Link
 219  *
 220  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 221  *******************************************************************************
 222  */
 223         long SS_Unlink(char *pLinkName);
 224
 225 /*!
 226  *******************************************************************************
 227  * Create symbolic link.<p>
 228  *
 229  * Must create the path to the link as required. If a file already exists at the
 230  * named location, must return success if the file is a symbolic link or an
 231  * error if the file is a regular file. The non-existance of the target of the
 232  * link must NOT cause an error.<p>
 233  *
 234  * If your platform does not support symbolic links, you do not need to
 235  * implement this.
 236  *
 237  * \param       pbUserData                      Optional opaque data-structure to pass to IPL
 238  *                                                              functions
 239  * \param       pLinkName                       Path to the link file to create
 240  * \param       pReferenceFileName      Path to which to point the link
 241  *
 242  * \return      S_SS_SUCCESS on success or an \ref SS_vRM_Errors.h error code
 243  *******************************************************************************
 244  */
 245         long SS_Link(void *pbUserData, char *pLinkName, char *pReferenceFileName);
 246
 247 /*!
 248  *******************************************************************************
 249  * Set file attributes.<p>
 250  *
 251  * The file attributes token (\a ui8pAttribs) is defined at generation time.
 252  * If attributes are not defined explicitly, they are given the following,
 253  * OS-dependent values:
 254  * \li  Windows: _foo_ro_ for R/O files, _foo_rw_ for R/W files
 255  * \li  Linux: _foo_oooooo:xxxx:yyyy indicating the file mode, uid, and gid
 256  *              (uid and gid use capitalized hex digits as required)
 257  *
 258  * \param       pbUserData              Optional opaque data-structure to pass to IPL
 259  *                                                      functions
 260  * \param       ui16pFilePath   File path
 261  * \param       ui32AttribSize  Size of \a ui8pAttribs
 262  * \param       ui8pAttribs             Attributes to set
 263  *
 264  * \return      S_SS_SUCCESS on success or &lt; 0 on error
 265  *******************************************************************************
 266  */
 267
 268         long SS_SetFileAttributes(const char *ui16pFilePath,
 269                         const SS_UINT32 ui32AttribSize, const unsigned char *ui8pAttribs);
 270
 271 /**
 272  *******************************************************************************
 273  * Allocate a memory block.
 274  *
 275  * \param       size    Memory block size, in blocks
 276  *
 277  * \return      A pointer to the memory block on success, NULL on failure
 278  *******************************************************************************
 279  */
 280         void *SS_Malloc(SS_UINT32 size);
 281
 282 /**
 283  *******************************************************************************
 284  * Free a memory block.
 285  *
 286  * \param       pMemBlock       Pointer to the memory block
 287  *******************************************************************************
 288  */
 289         void SS_Free(void *pMemBlock);
 290 /**
 291  *******************************************************************************
 292  * Get capability feature flag value
 293  *
 294  * \return      The value of feature_support_capability
 295  *******************************************************************************
 296  */
 297         int SS_get_feature_support_capability(void);
 298
 299 /**
 300  *******************************************************************************
 301  * Set capability feature flag
 302  *
 303  * \param       val     The value to set feature_support_capability
 304  *******************************************************************************
 305  */
 306         void SS_set_feature_support_capability(int val);
 307
 308 /**
 309  *******************************************************************************
 310  * Create a hardlink to a file
 311  *
 312  * \param       hardLinkName    Name of the hardlink to be created
 313  * \param       referenceName   Name of the file that we link to
 314  *
 315  * \return      S_SS_SUCCESS on success, E_SS_FAILURE otherwise
 316  *******************************************************************************
 317  */
 318
 319         long SS_HardLink(char *hardLinkName, char *referenceName);
 320
 321 #ifdef __cplusplus
 322 }
 323 #endif                          /* __cplusplus */
 324 #endif