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. On error a negative value will be returned with th follwoing error codes:
  48  *                          ::EPERS_LOCKFS, ::EPERS_MAXHANDLE
  49  */
  50 int pclFileClose(int fd);
  51
  52
  53
  54 /**
  55  * @brief get the size of the file given by the file descriptor
  56  *
  57  * @param fd the POSIX file descriptor
  58  *
  59  * @return positive value. On error the negative value -1 will be returned
  60  */
  61 int pclFileGetSize(int fd);
  62
  63
  64
  65 /**
  66  * @brief map a file into the memory
  67  *
  68  * @param addr if NULL, kernel chooses address
  69  * @param size the size in bytes to map into the memory
  70  * @param offset in the file to map
  71  * @param fd the POSIX file descriptor of the file to map
  72  *
  73  * @return a pointer to the mapped area, or on error the value MAP_FAILED or
  74  *  EPERS_MAP_FAILEDLOCK if filesystem is currrently locked
  75  */
  76 void* pclFileMapData(void* addr, long size, long offset, int fd);
  77
  78
  79
  80 /**
  81  * @brief open a file
  82  *
  83  * @param ldbid logical database ID
  84  * @param resource_id the resource ID
  85  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
  86  * @param seat_no  the seat number
  87  *
  88  * @return positive value: the POSIX file descriptor;
  89  * On error a negative value will be returned with th follwoing error codes:
  90  * EPERS_LOCKFS, EPERS_MAXHANDLE, EPERS_NOKEY, EPERS_NOKEYDATA, EPERS_NOPRCTABLE or EPERS_COMMON,
  91  */
  92 int pclFileOpen(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
  93
  94
  95
  96 /**
  97  * @brief read persistent data from a file
  98  *
  99  * @param fd POSIX file descriptor
 100  * @param buffer buffer to read the data
 101  * @param buffer_size the size buffer for reading
 102  *
 103  * @return positive value: the size read;
 104  * On error a negative value will be returned with th follwoing error codes:
 105  * EPERS_LOCKFS or EPERS_COMMON
 106  */
 107 int pclFileReadData(int fd, void * buffer, int buffer_size);
 108
 109
 110
 111 /**
 112  * @brief remove the file
 113  *
 114  * @param ldbid logical database ID
 115  * @param resource_id the resource ID
 116  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 117  * @param seat_no  the seat number
 118  *
 119  * @return positive value: success;
 120  * On error a negative value will be returned with th follwoing error codes:
 121  * EPERS_LOCKFS or EPERS_COMMON
 122  */
 123 int pclFileRemove(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no);
 124
 125
 126
 127 /**
 128  * @brief reposition the file descriptor
 129  *
 130  * @param fd the POSIX file descriptor
 131  * @param offset the reposition offset
 132  * @param whence the direction to reposition
 133                  SEEK_SET
 134                       The offset is set to offset bytes.
 135                  SEEK_CUR
 136                       The offset is set to its current location plus offset bytes.
 137                  SEEK_END
 138                       The offset is set to the size of the file plus offset bytes.
 139  *
 140  * @return positive value: resulting offset location;
 141  * On error a negative value will be returned with th follwoing error codes:
 142  * EPERS_LOCKFS or EPERS_COMMON
 143  */
 144 int pclFileSeek(int fd, long int offset, int whence);
 145
 146
 147
 148 /**
 149  * @brief unmap the file from the memory
 150  *
 151  * @param address the address to unmap
 152  * @param size the size in bytes to unmap
 153  *
 154  * @return on success 0;
 155  * On error a negative value will be returned with th follwoing error codes:
 156  * EPERS_LOCKFS or EPERS_COMMON
 157  */
 158 int pclFileUnmapData(void* address, long size);
 159
 160
 161
 162 /**
 163  * @brief write persistent data to file
 164  *
 165  * @param fd the POSIX file descriptor
 166  * @param buffer the buffer to write
 167  * @param buffer_size the size of the buffer to write in bytes
 168  *
 169  * @return positive value: bytes written;
 170  * On error a negative value will be returned with th follwoing error codes:
 171  * EPERS_LOCKFS or EPERS_COMMON
 172  */
 173 int pclFileWriteData(int fd, const void * buffer, int buffer_size);
 174
 175
 176
 177 /**
 178  * @brief create a path to a file
 179  *
 180  * @param ldbid logical database ID
 181  * @param resource_id the resource ID
 182  * @param user_no  the user ID; user_no=0 can not be used as user-ID beacause ‘0’ is defined as System/node
 183  * @param seat_no  the seat number
 184  * @param path the path to the file
 185  * @param size the size of the path
 186  *
 187  * @note the allocated memory for the path string will be freed in tpclFileReleasePath
 188  *
 189  * @return positive value on success, which must be used when pclFileReleasePath will be called
 190  * On error a negative value will be returned with th follwoing error codes:
 191  * EPERS_LOCKFS or EPERS_COMMON
 192  */
 193 int pclFileCreatePath(unsigned int ldbid, const char* resource_id, unsigned int user_no, unsigned int seat_no, char** path, unsigned int* size);
 194
 195
 196 /**
 197  * @brief release a file path
 198  *
 199  * @param pathHandle the path to the file
 200  *
 201  * @note the allocated memory in pclFileCreatePath for the path will freed in the function
 202  *
 203  * @return positive value: success;
 204  * On error a negative value will be returned with th follwoing error codes:
 205  * EPERS_LOCKFS or EPERS_COMMON
 206  */
 207 int pclFileReleasePath(int pathPandle);
 208
 209 /** \} */
 210
 211 #ifdef __cplusplus
 212 }
 213 #endif
 214
 215
 216 /** \} */ /* End of API */
 217 /** \} */ /* End of MODULE */
 218
 219
 220 #endif /* PERSISTENCY_CLIENT_LIBRARY_FILE_H */