include/persistence_client_library_file.h

   1 #ifndef PERSISTENCE_CLIENT_LIBRARY_FILE_H
   2 #define PERSISTENCE_CLIENT_LIBRARY_FILE_H
   3
   4 /******************************************************************************
   5  * Project         Persistency
   6  * (c) copyright   2011
   7  * Company         XS Embedded GmbH
   8  *****************************************************************************/
   9 /******************************************************************************
  10  * This Source Code Form is subject to the terms of the
  11  * Mozilla Public License, v. 2.0. If a  copy of the MPL was not distributed
  12  * with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
  13 ******************************************************************************/
  14  /**
  15  * @file           persistence_client_library_file.h
  16  * @ingroup        Persistence client library
  17  * @author         Ingo Huerner (XSe) / Guy Sagnes (Continental)
  18  * @brief          Header of the persistence client library.
  19  *                 Library provides an API to access persistent data
  20  * @see
  21  */
  22 /** \ingroup GEN_PERS */
  23 /** \defgroup PERS_FILE Client: File access
  24  *  \{
  25  */
  26 /** \defgroup PERS_FILE_INTERFACE API document
  27  *  \{
  28  */
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33
  34 #define  PERSIST_FILEAPI_INTERFACE_VERSION   (0x03010000U)
  35
  36 #include "persistence_client_library.h"
  37
  38 /** \defgroup PCL_FILE functions file access
  39  * \{
  40  */
  41
  42 /**
  43  * @brief close the given POSIX file descriptor
  44  *
  45  * @param fd the file descriptor to close
  46  *
  47  * @return zero on success.
  48  * On error a negative value will be returned with th following error codes:
  49  * ::EPERS_MAXHANDLE ::EPERS_COMMON
  50  * If ::EPERS_COMMON will be returned errno will be set.
  51  */
  52 int pclFileClose(int fd);
  53
  54
  55
  56 /**
  57  * @brief get the size of the file given by the file descriptor
  58  *
  59  * @param fd the POSIX file descriptor
  60  *
  61  * @return positive value (0 or greater). On error ::EPERS_NOT_INITIALIZED, ::EPERS_COMMON
  62  * If ::EPERS_COMMON will be returned errno will be set.
  63  */
  64 int pclFileGetSize(int fd);
  65
  66
  67
  68 /**
  69  * @brief map a file into the memory
  70  *
  71  * @param addr if NULL, kernel chooses address
  72  * @param size the size in bytes to map into the memory
  73  * @param offset in the file to map
  74  * @param fd the POSIX file descriptor of the file to map
  75  *
  76  * @return a pointer to the mapped area, or on error the value MAP_FAILED or
  77  *  EPERS_MAP_FAILEDLOCK if filesystem is currrently locked
  78  */
  79 void* pclFileMapData(void* addr, long size, long offset, int fd);
  80
  81
  82
  83 /**
  84  * @brief open a file
  85  *
  86  * @param ldbid logical database ID
  87  * @param resource_id the resource ID
  88  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
  89  * @param seat_no  the seat number
  90  *
  91  * @return positive value (0 or greater): the POSIX file descriptor;
  92  * On error a negative value will be returned with th following error codes:
  93  * ::EPERS_LOCKFS, ::EPERS_MAXHANDLE, ::EPERS_NOKEY, ::EPERS_NOKEYDATA,
  94  * ::EPERS_NOPRCTABLE, ::EPERS_NOT_INITIALIZED, ::EPERS_COMMON
  95  * If ::EPERS_COMMON will be returned errno will be set.
  96  */
  97 int pclFileOpen(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
  98
  99
 100
 101 /**
 102  * @brief read persistent data from a file
 103  *
 104  * @param fd POSIX file descriptor
 105  * @param buffer buffer to read the data
 106  * @param buffer_size the size buffer for reading
 107  *
 108  * @return positive value (0 or greater): the size read;
 109  * On error a negative value will be returned with th following error codes:
 110  * ::EPERS_NOT_INITIALIZED, ::EPERS_LOCKFS, ::EPERS_COMMON.
 111  * If ::EPERS_COMMON will be returned errno will be set
 112  */
 113 int pclFileReadData(int fd, void * buffer, int buffer_size);
 114
 115
 116
 117 /**
 118  * @brief remove the file
 119  *
 120  * @param ldbid logical database ID
 121  * @param resource_id the resource ID
 122  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 123  * @param seat_no  the seat number
 124  *
 125  * @return positive value (0 or greater): success;
 126  * On error a negative value will be returned with th following error codes:
 127  * ::EPERS_NOT_INITIALIZED, ::EPERS_LOCKFS, ::EPERS_COMMON.
 128  * If ::EPERS_COMMON will be returned errno will be set
 129  */
 130 int pclFileRemove(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 131
 132
 133
 134 /**
 135  * @brief reposition the file descriptor
 136  *
 137  * @param fd the POSIX file descriptor
 138  * @param offset the reposition offset
 139  * @param whence the direction to reposition
 140                  SEEK_SET
 141                       The offset is set to offset bytes.
 142                  SEEK_CUR
 143                       The offset is set to its current location plus offset bytes.
 144                  SEEK_END
 145                       The offset is set to the size of the file plus offset bytes.
 146  *
 147  * @return positive value (0 or greater): resulting offset location;
 148  * On error a negative value will be returned with th following error codes:
 149  * ::EPERS_LOCKFS, ::EPERS_NOT_INITIALIZED, ::EPERS_COMMON.
 150  * If ::EPERS_COMMON will be returned errno will be set
 151  */
 152 int pclFileSeek(int fd, long int offset, int whence);
 153
 154
 155
 156 /**
 157  * @brief unmap the file from the memory
 158  *
 159  * @param address the address to unmap
 160  * @param size the size in bytes to unmap
 161  *
 162  * @return on success 0;
 163  * On error a negative value will be returned with th following error codes:
 164  * ::EPERS_LOCKFS, EPERS_NOT_INITIALIZED, ::EPERS_COMMON.
 165  * If ::EPERS_COMMON will be returned errno will be set
 166  */
 167 int pclFileUnmapData(void* address, long size);
 168
 169
 170
 171 /**
 172  * @brief write persistent data to file
 173  *
 174  * @param fd the POSIX file descriptor
 175  * @param buffer the buffer to write
 176  * @param buffer_size the size of the buffer to write in bytes
 177  *
 178  * @return positive value (0 or greater): bytes written;
 179  * On error a negative value will be returned with th following error codes:
 180  * ::EPERS_LOCKFS, ::EPERS_NOT_INITIALIZED or ::EPERS_COMMON ::EPERS_RESOURCE_READ_ONLY
 181  * If ::EPERS_COMMON will be returned errno will be set.
 182  */
 183 int pclFileWriteData(int fd, const void * buffer, int buffer_size);
 184
 185
 186
 187 /**
 188  * @brief create a path to a file
 189  *
 190  * @param ldbid logical database ID
 191  * @param resource_id the resource ID
 192  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 193  * @param seat_no  the seat number
 194  * @param path the path to the file
 195  * @param size the size of the path
 196  *
 197  * @note the allocated memory for the path string will be freed in pclFileReleasePath
 198  *
 199  * @return positive value (0 or greater) on success, which must be used when pclFileReleasePath will be called
 200  * On error a negative value will be returned with th following error codes:
 201  * ::EPERS_LOCKFS or ::EPERS_COMMON
 202  * If ::EPERS_COMMON will be returned errno will be set.
 203  */
 204 int pclFileCreatePath(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, char** path, unsigned int* size);
 205
 206
 207 /**
 208  * @brief release a file path
 209  *
 210  * @param pathHandle the path to the file
 211  *
 212  * @note the allocated memory in pclFileCreatePath for the path will freed in the function
 213  *
 214  * @return positive value (0 or greater): success;
 215  * On error a negative value will be returned with th following error codes:
 216  * ::EPERS_LOCKFS or ::EPERS_COMMON
 217  * If ::EPERS_COMMON will be returned errno will be set.
 218  */
 219 int pclFileReleasePath(int pathHandle);
 220
 221 /** \} */
 222
 223 #ifdef __cplusplus
 224 }
 225 #endif
 226
 227
 228 /** \} */ /* End of API */
 229 /** \} */ /* End of MODULE */
 230
 231
 232 #endif /* PERSISTENCY_CLIENT_LIBRARY_FILE_H */