1 /* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18 /** 19 * File Porting Layer. 20 */ 21 #ifndef __DRM_FILE_H__ 22 #define __DRM_FILE_H__ 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 #include <drm_common_types.h> 29 30 /** Type value of a regular file or file name. */ 31 #define DRM_FILE_ISREG 1 32 /** Type value of a directory or directory name. */ 33 #define DRM_FILE_ISDIR 2 34 /** Type value of a filter name */ 35 #define DRM_FILE_ISFILTER 3 36 37 38 /** Return code that indicates successful completion of an operation. */ 39 #define DRM_FILE_SUCCESS 0 40 /** Indicates that an operation failed. */ 41 #define DRM_FILE_FAILURE -1 42 /** Indicates that the a DRM_file_read() call reached the end of the file. */ 43 #define DRM_FILE_EOF -2 44 45 46 /** Open for read access. */ 47 #define DRM_FILE_MODE_READ 1 48 /** Open for write access. */ 49 #define DRM_FILE_MODE_WRITE 2 50 51 52 #ifndef MAX_FILENAME_LEN 53 /** Maximum number of characters that a filename may have. By default assumes 54 * that the entry results of DRM_file_listNextEntry() are returned in the async state 55 * buffer, after the #DRM_file_result_s, and calculates the maximum name 56 * from that. 57 */ 58 #define MAX_FILENAME_LEN 1024 59 #endif 60 61 62 /** 63 * Performs one-time initialization of the File System (FS). 64 * This function is called once during the lifetime of an application, 65 * and before any call to <code>DRM_file_*</code> functions by this application. 66 * When several applications are using the file interface, this function may be called 67 * several times, once per application. 68 * 69 * @return #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 70 */ 71 int32_t DRM_file_startup(void); 72 73 /** 74 * Returns the length of a file (by name, opened or unopened). 75 * 76 * @param name Name of the file, UCS-2 encoded. 77 * @param nameChars Number characters encoded in name. 78 * asynchronous operation returns #DRM_FILE_WOULDBLOCK. 79 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_FAILURE or the file length. 80 */ 81 int32_t DRM_file_getFileLength(const uint16_t* name, 82 int32_t nameChars); 83 84 /** 85 * Initializes a list iteration session. 86 * 87 * @param prefix Prefix that must be matched, UCS-2 encoded. * 88 * @param prefixChars Number characters encoded in prefix. 89 * @param session List session identifier. 90 * @param iteration List iteration identifier. 91 * 92 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 93 */ 94 int32_t DRM_file_listOpen(const uint16_t* prefix, 95 int32_t prefixChars, 96 int32_t* session, 97 int32_t* iteration); 98 99 /** 100 * Used to fetch a list of file names that match a given name prefix. 101 * 102 * @param prefix See DRM_file_listOpen(). This does not change during the 103 * iteration session. 104 * @param prefixChars See DRM_file_listOpen(). This does not change during 105 * the iteration session. 106 * @param entry Buffer parameter to return the next file name that matches the 107 * #prefix parameter, if any, when the function returns a positive number of 108 * characters. 109 * @param entryBytes Size of entry in bytes. 110 * @param session See DRM_file_listOpen(). 111 * @param iteration See DRM_file_listOpen(). 112 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_FAILURE or the number of 113 * characters encoded in entry. Returns 0 when the end of the list is reached. 114 */ 115 int32_t DRM_file_listNextEntry(const uint16_t* prefix, 116 int32_t prefixChars, 117 uint16_t* entry, 118 int32_t entryBytes, 119 int32_t* session, 120 int32_t* iteration); 121 122 /** 123 * Ends a list iteration session. Notifies the implementation 124 * that the list session is over and that any session resources 125 * can be released. 126 * 127 * @param session See DRM_file_listOpen(). 128 * @param iteration See DRM_file_listOpen(). 129 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 130 */ 131 int32_t DRM_file_listClose(int32_t session, int32_t iteration); 132 133 /** 134 * Renames a file, given its old name. The file or directory is renamed 135 * immediately on the actual file system upon invocation of this method. 136 * Any open handles on the file specified by oldName become invalid after 137 * this method has been called. 138 * 139 * @param oldName Current file name (unopened), UCS-2 encoded. 140 * @param oldNameChars Number of characters encoded on oldName. 141 * @param newName New name for the file (unopened), UCS-2 encoded. 142 * @param newNameChars Number of characters encoded on newName. 143 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. In particular, 144 * #DRM_FILE_FAILURE if a file or directory already exists with the new name. 145 */ 146 int32_t DRM_file_rename(const uint16_t* oldName, 147 int32_t oldNameChars, 148 const uint16_t* newName, 149 int32_t newNameChars); 150 151 /** 152 * Tests if a file exists given its name. 153 * 154 * @param name Name of the file, UCS-2 encoded. 155 * @param nameChars Number of characters encoded in name. 156 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_ISREG, #DRM_FILE_ISDIR, #DRM_FILE_FAILURE. If name 157 * exists, returns #DRM_FILE_ISREG if it is a regular file and #DRM_FILE_ISDIR if it is a directory. 158 * Returns #DRM_FILE_FAILURE in all other cases, including those where name exists but is neither 159 * a regular file nor a directory. Platforms that do not support directories MUST NOT return 160 * #DRM_FILE_ISDIR. 161 */ 162 int32_t DRM_file_exists(const uint16_t* name, 163 int32_t nameChars); 164 165 /** 166 * Opens a file with the given name and returns its file handle. 167 * 168 * @param name Name of the file, UCS-2 encoded. 169 * @param nameChars Number of characters encoded in name. 170 * @param mode Any combination of the #DRM_FILE_MODE_READ and 171 * #DRM_FILE_MODE_WRITE flags. If the file does not exist and mode contains the 172 * #DRM_FILE_MODE_WRITE flag, then the file is automatically created. If the 173 * file exists and the mode contains the #DRM_FILE_MODE_WRITE flag, the file is 174 * opened so it can be modified, but the data is not modified by the open call. 175 * In all cases the current position is set to the start of the file. 176 * The following table shows how to map the mode semantics above to UNIX 177 * fopen-style modes. For brevity in the table, R=#DRM_FILE_MODE_READ, 178 * W=#DRM_FILE_MODE_WRITE, E=File exists: 179 * <table> 180 * <tr><td>RW</td><td>E</td><td>Maps-to</td></tr> 181 * <tr><td>00</td><td>0</td><td>Return #DRM_FILE_FAILURE</td></tr> 182 * <tr><td>00</td><td>1</td><td>Return #DRM_FILE_FAILURE</td></tr> 183 * <tr><td>01</td><td>0</td><td>Use fopen mode "w"</td></tr> 184 * <tr><td>01</td><td>1</td><td>Use fopen mode "a" and fseek to the start</td></tr> 185 * <tr><td>10</td><td>0</td><td>Return #DRM_FILE_FAILURE</td></tr> 186 * <tr><td>10</td><td>1</td><td>Use fopen mode "r"</td></tr> 187 * <tr><td>11</td><td>0</td><td>Use fopen mode "w+"</td></tr> 188 * <tr><td>11</td><td>1</td><td>Use fopen mode "r+"</td></tr> 189 * </table> 190 * @param handle Pointer where the result handle value is placed when the function 191 * is called synchronously. 192 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 193 */ 194 int32_t DRM_file_open(const uint16_t* name, 195 int32_t nameChars, 196 int32_t mode, 197 int32_t* handle); 198 199 /** 200 * Deletes a file given its name, UCS-2 encoded. The file or directory is 201 * deleted immediately on the actual file system upon invocation of this 202 * method. Any open handles on the file specified by name become invalid 203 * after this method has been called. 204 * 205 * If the port needs to ensure that a specific application does not exceed a given storage 206 * space quota, then the bytes freed by the deletion must be added to the available space for 207 * that application. 208 * 209 * @param name Name of the file, UCS-2 encoded. 210 * @param nameChars Number of characters encoded in name. 211 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 212 */ 213 int32_t DRM_file_delete(const uint16_t* name, 214 int32_t nameChars); 215 216 /** 217 * Read bytes from a file at the current position to a buffer. Afterwards the 218 * new file position is the byte after the last byte read. 219 * DRM_FILE_FAILURE is returned if the handle is invalid (e.g., as a 220 * consquence of DRM_file_delete, DRM_file_rename, or DRM_file_close). 221 * 222 * @param handle File handle as returned by DRM_file_open(). 223 * @param dst Buffer where the data is to be copied. 224 * @param length Number of bytes to be copied. 225 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE, #DRM_FILE_EOF 226 * or the number of bytes that were read, i.e. in the range 0..length. 227 */ 228 int32_t DRM_file_read(int32_t handle, 229 uint8_t* dst, 230 int32_t length); 231 232 /** 233 * Write bytes from a buffer to the file at the current position. If the 234 * current position + number of bytes written > current size of the file, 235 * then the file is grown. Afterwards the new file position is the byte 236 * after the last byte written. 237 * DRM_FILE_FAILURE is returned if the handle is invalid (e.g., as a 238 * consquence of DRM_file_delete, DRM_file_rename, or DRM_file_close). 239 * 240 * @param handle File handle as returned by DRM_file_open(). 241 * @param src Buffer that contains the bytes to be written. 242 * @param length Number of bytes to be written. 243 * If the port needs to ensure that a specific application does not exceed a given storage 244 * space quota, the implementation must make sure the call does not violate that invariant. 245 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_FAILURE or the number of bytes 246 * that were written. This number must be in the range 0..length. 247 * Returns #DRM_FILE_FAILURE when storage is full or exceeds quota. 248 */ 249 int32_t DRM_file_write(int32_t handle, 250 const uint8_t* src, 251 int32_t length); 252 253 /** 254 * Closes a file. 255 * DRM_FILE_SUCCESS is returned if the handle is invalid (e.g., as a 256 * consquence of DRM_file_delete or DRM_file_rename). 257 * 258 * @param handle File handle as returned by DRM_file_open(). 259 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 260 */ 261 int32_t DRM_file_close(int32_t handle); 262 263 /** 264 * Sets the current position in an opened file. 265 * DRM_FILE_FAILURE is returned if the handle is invalid (e.g., as a 266 * consquence of DRM_file_delete, DRM_file_rename, or DRM_file_close). 267 * 268 * @param handle File handle as returned by DRM_file_open(). 269 * @param value The new current position of the file. If value is greater 270 * than the length of the file then the file should be extended. The contents 271 * of the newly extended portion of the file is undefined. 272 * If the port needs to ensure that a specific application does not exceed a given storage 273 * space quota, the implementation must make sure the call does not violate that invariant. 274 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 275 * Returns #DRM_FILE_FAILURE when storage is full or exceeds quota. 276 */ 277 int32_t DRM_file_setPosition(int32_t handle, int32_t value); 278 279 /** 280 * Creates a directory with the assigned name and full file permissions on 281 * the file system. The full path to the new directory must already exist. 282 * The directory is created immediately on the actual file system upon 283 * invocation of this method. 284 * 285 * @param name Name of the directory, UCS-2 encoded. 286 * @param nameChars Number of characters encoded in name. 287 * @return #DRM_FILE_WOULDBLOCK, #DRM_FILE_SUCCESS, #DRM_FILE_FAILURE. 288 */ 289 int32_t DRM_file_mkdir(const uint16_t* name, 290 int32_t nameChars); 291 292 #ifdef __cplusplus 293 } 294 #endif 295 296 #endif /* __DRM_FILE_H__ */ 297
