1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 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 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 // -*- c++ -*- 19 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 20 21 // O S C L _ F I L E _ I O 22 23 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 24 25 /*! \addtogroup osclio OSCL IO 26 * 27 * @{ 28 */ 29 30 31 /*! \file oscl_file_io.h 32 \brief The file oscl_file_io.h defines the class Oscl_File. This is the 33 public API to the basic file I/O operations. 34 */ 35 36 37 38 #ifndef OSCL_FILE_IO_H_INCLUDED 39 #define OSCL_FILE_IO_H_INCLUDED 40 41 #ifndef OSCLCONFIG_IO_H_INCLUDED 42 #include "osclconfig_io.h" 43 #endif 44 45 #ifndef OSCL_BASE_H_INCLUDED 46 #include "oscl_base.h" 47 #endif 48 49 #ifndef OSCL_MEM_H_INCLUDED 50 #include "oscl_mem.h" 51 #endif 52 53 /** 54 * Oscl_File_IO class defines the generic way of creating all the file object for all the platforms. 55 * The class defines all the input output files operations like open, close, read, write, seek, tell 56 * that will be common over various Operating Systems we are supporting. 57 * It stores an file pointer that is used to access the file, a cache reference depending whether 58 * cache is supported by the OS 59 */ 60 class PVLogger; 61 class OsclFileCache; 62 class Oscl_FileServer; 63 class OsclFileHandle; 64 class OsclNativeFile; 65 class OsclFileStats; 66 class OsclNativeFileParams; 67 class OsclAsyncFile; 68 #define TOsclFileOffsetInt32 int32 69 70 class Oscl_File : public HeapBase 71 { 72 public: 73 74 typedef enum 75 { 76 /** 77 * Beginning of file 78 */ 79 SEEKSET, 80 /** 81 * Current position of file pointer 82 */ 83 SEEKCUR, 84 /** 85 * End of file 86 */ 87 SEEKEND 88 } seek_type; 89 90 typedef enum 91 { 92 /** 93 * Opens a file for reading. The file must exist. 94 */ 95 MODE_READ = 0x0001, 96 /** 97 * Opens the file for reading and writing. If the file exists, 98 * its contents will be overwritten unless APPEND mode is 99 * specified. If the file does not exist, it will be created. 100 */ 101 MODE_READWRITE = 0x0002, 102 /** 103 * Specifies all write operations to occur at the end of the 104 * file. The file pointer can be moved with the Seek command, 105 * but will always be moved to the end of the file for write 106 * commands. 107 */ 108 MODE_APPEND = 0x0004, 109 /** 110 * Opens the file in 'binary' mode. This is the default. 111 */ 112 MODE_BINARY = 0x0008, 113 /** 114 * Opens the file in 'text' mode. The default mode is 'binary'. 115 */ 116 MODE_TEXT = 0x0010, 117 /** 118 * Open a file for reading and writing. The file must exist. 119 * The default mode is 'binary'. 120 */ 121 MODE_READ_PLUS = 0x0020 122 123 } mode_type; 124 125 /** 126 * Constructor 127 */ 128 OSCL_IMPORT_REF Oscl_File(); 129 130 /** 131 * Deprecated Constructor, present for back-compatibility. 132 * @param aCacheSize: sets native buffer size, and when pv cache is enabled, 133 * also sets pv cache size. 134 */ 135 OSCL_IMPORT_REF Oscl_File(uint32 aCacheSize); 136 /** 137 * Deprecated Constructor, present for back-compatibility. 138 * @param aCacheSize: sets native buffer size, and when pv cache is enabled, 139 * also sets pv cache size. 140 * @param aFileHandle: open file handle. 141 */ 142 OSCL_IMPORT_REF Oscl_File(uint32 aCacheSize, OsclFileHandle* aFileHandle); 143 144 /** 145 * Destructor 146 */ 147 OSCL_IMPORT_REF ~Oscl_File(); 148 149 /** 150 * SetPVCacheSize configures the read/write cache. 151 * 152 * This should be called before opening the file. If used when 153 * the file is open, the option will not take effect until the 154 * next Open. 155 * 156 * @param aSize: cache size in bytes. Zero disables the cache. 157 */ 158 OSCL_IMPORT_REF void SetPVCacheSize(uint32 aSize); 159 160 /** 161 * SetNativeAccessMode allows switching between different native file access 162 * modes, when available. 163 * 164 * Note: for For Symbian, use the TSymbianAccessMode values to choose the mode. 165 * If multiple access modes are not available on the platform, this call will 166 * have no effect. 167 * 168 * @param aMode: access mode. 169 */ 170 OSCL_IMPORT_REF void SetNativeAccessMode(uint32 aMode); 171 172 /** 173 * Defines mode options for SetNativeAccessMode on Symbian. 174 */ 175 enum TSymbianAccessMode 176 { 177 ESymbianAccessMode_Rfile = 0 178 , ESymbianAccessMode_RfileBuf = 1 179 }; 180 181 /** 182 * SetNativeBufferSize configures the native file buffering feature, 183 * when available. 184 * 185 * This should be called before opening the file. If used when 186 * the file is open, the option will not take effect until the 187 * next Open. 188 * 189 * Note: For Symbian, this sets the RFileBuf cache size. 190 * If native buffing is not available on the platform, this call 191 * will have no effect. 192 * 193 * @param aSize: native buffer size in bytes. Zero disables the feature. 194 */ 195 OSCL_IMPORT_REF void SetNativeBufferSize(int32 aSize); 196 197 /** 198 * SetAsyncReadBufferSize configures the asynchronous background 199 * read function. May not be available on all platforms. 200 * 201 * This should be called before opening the file. If used when 202 * the file is open, the option will not take effect until the 203 * next Open. 204 * 205 * Note: if asynchronous read is not available on the platform, 206 * this call will have no effect. 207 * 208 * @param aSize: buffer size in bytes. Zero disables the feature. 209 */ 210 OSCL_IMPORT_REF void SetAsyncReadBufferSize(uint32 aSize); 211 212 /** 213 * SetFileHandle adds an open file handle to the Oscl_File object. 214 * The Oscl_File object will use that handle to access the file. 215 * 216 * This call is not available when the Oscl_File object is already 217 * open. 218 * 219 * Note: This feature is used in Symbian with the MMF framework. 220 * The MMF framework provides an open RFile handle to access content. 221 * When using RFileBuf access mode with an RFile handle, the RFileBuf 222 * will be attached to the open RFile handle. 223 * 224 * To use the external file handle, the caller starts with a native file handle to an open file. The caller must 225 * wrap the native file handle in an OsclFileHandle object, pass the OsclFileHandle pointer to SetFileHandle, 226 * call Oscl_File::Open, then proceed to use the Oscl_File object, finally calling Oscl_File::Close. 227 * In this usage mode, Oscl_File::Open and Oscl_File::Close do not actually call native file open and close. 228 * It is assumed that the caller will close the original native file handle after usage is complete. 229 * 230 * @param aHandle: container for an open file handle. 231 * @return returns 0 if successful, non-zero if error. 232 * 233 */ 234 OSCL_IMPORT_REF int32 SetFileHandle(OsclFileHandle* aHandle); 235 236 /** 237 * Opens a file. 238 * 239 * Note: when an external file handle is used, Open will attach to the file 240 * handle and initialize cacheing features, but will not do a native file open. 241 * 242 * 243 * @param filename name of file to open (Utf8) 244 * @param mode combination of open mode flags 245 * @param fileserv fileserver to use 246 * 247 * @return returns 0 if successful and a non-zero value otherwise 248 */ 249 OSCL_IMPORT_REF int32 Open(const char *filename, uint32 mode, Oscl_FileServer& fileserv); 250 251 /** 252 * Opens a file. 253 * 254 * Note: when an external file handle is used, Open will attach to the file 255 * handle and initialize cacheing features, but will not do a native file open. 256 * 257 * @param filename name of file to open (Unicode) 258 * @param mode combination of open mode flags 259 * @param fileserv fileserver to use 260 * 261 * @return returns 0 if successful and a non-zero value otherwise 262 */ 263 OSCL_IMPORT_REF int32 Open(const oscl_wchar *filename, uint32 mode, Oscl_FileServer& fileserv); 264 265 /** 266 * The File Read operation 267 * Reads from the file into the buffer a maximum of 'numelements' 268 * of size 'size'. 269 * 270 * @param buffer pointer to buffer of type void 271 * @param size element size in bytes 272 * @param numelements 273 * max number of elements to read 274 * 275 * @return returns the number of full elements actually read, which 276 * may be less than count if an error occurs or if the end 277 * of the file is encountered before reaching count. Use the 278 * CheckEndOfFile or GetError function to distinguish a read 279 * error from an end-of-file condition. 280 */ 281 OSCL_IMPORT_REF uint32 Read(OsclAny *buffer, 282 uint32 size, 283 uint32 numelements); 284 285 /** 286 * The File Write operation 287 * Writes from the buffer 'numelements' objects of size 'size' 288 * 289 * @param buffer pointer to buffer of type void 290 * @param size element size in bytes 291 * @param numelements 292 * number of elements to write 293 * 294 * @return The number of elements written 295 */ 296 OSCL_IMPORT_REF uint32 Write(const OsclAny *buffer, 297 uint32 size, 298 uint32 numelements); 299 300 301 /** 302 * The File Seek operation 303 * Sets the position for file pointer 304 * 305 * @param offset offset from the specified origin. 306 * @param origin starting point 307 * 308 * @return returns 0 on success, and a non-zero value otherwise 309 */ 310 OSCL_IMPORT_REF int32 Seek(TOsclFileOffset offset, 311 seek_type origin); 312 313 /** 314 * The File Tell operation 315 * Returns the current file position for file specified by fp 316 */ 317 OSCL_IMPORT_REF TOsclFileOffset Tell(); 318 319 320 /** 321 * The File Close operation 322 * Closes the file after flushing any remaining data in the 323 * buffers. 324 * 325 * Note: If the file object was opened with an external file handle, 326 * then Close will simply flush the file. The file will remain open. 327 * 328 * @return returns 0 if successful, and a non-zero value otherwise 329 */ 330 OSCL_IMPORT_REF int32 Close(); 331 332 333 /** 334 * The File Flush operation 335 * On an output stream OSCL_FileFlush causes any buffered 336 * but unwritten data to be written to the file. 337 * 338 * @return returns 0 if successful, and a non-zero value otherwise 339 */ 340 OSCL_IMPORT_REF int32 Flush(); 341 342 343 /** 344 * The File EOF(end of file) operation 345 * returns a nonzero value after the first read operation 346 * that attempts to read past the end of the file 347 * 348 * @return 349 */ 350 OSCL_IMPORT_REF int32 EndOfFile(); 351 352 353 /** 354 * The File Error operation 355 * If no error has occurred on stream, returns 0. Otherwise, 356 * it returns a nonzero value 357 * 358 * @return 359 */ 360 OSCL_IMPORT_REF int32 GetError(); 361 362 /** 363 * Retrieve the file handle. 364 * 365 * @return file handle 366 */ 367 OsclFileHandle* Handle() 368 { 369 return iOpenFileHandle; 370 } 371 372 /** 373 * Get the file size in bytes. 374 * 375 * @return - The size of the file, or -1 on error. 376 */ 377 OSCL_IMPORT_REF TOsclFileOffset Size(); 378 379 /** 380 * SetLoggingEnable configures the PVLogger output for this file. 381 * This will enable full logging of each API entry and 382 * exit using the logger object "Oscl_File", plus full logging 383 * of native operation entry & exit using logger object "OsclNativeFile". 384 * 385 * @param aEnable: true to enable, false to disable logging. 386 */ 387 OSCL_IMPORT_REF void SetLoggingEnable(bool aEnable); 388 389 /** 390 * SetSummaryStatsLoggingEnable configures the PVLogger output for this file. 391 * This will enable summary statistics logging only, using the logger 392 * object "OsclFileStats". 393 * 394 * @param aEnable: true to enable, false to disable stats logging. 395 */ 396 OSCL_IMPORT_REF void SetSummaryStatsLoggingEnable(bool aEnable); 397 398 399 private: 400 friend class OsclFileCache; 401 friend class asyncfilereadwrite_test; 402 friend class largeasyncfilereadwrite_test; 403 friend class asyncfilereadcancel_test; 404 405 void Construct(); 406 void OldCacheDefaults(); 407 void OldCacheSelect(uint32); 408 409 //state info 410 bool iIsOpen; 411 412 //For Logging 413 PVLogger* iLogger; 414 PVLogger* iStatsLogger; 415 PVLogger* iNativeLogger; 416 PVLogger* iAsyncLogger; 417 OsclFileStats* iFileStats; 418 void CreateFileStats(); 419 420 //External file handle. 421 OsclFileHandle* iOpenFileHandle; 422 423 //For PV File Cache 424 uint32 iPVCacheSize; 425 OsclFileCache* iFileCache; 426 427 int32 OpenFileCacheOrAsyncBuffer(const char *filename 428 , const oscl_wchar* wfilename 429 , uint32 mode 430 , const OsclNativeFileParams& params 431 , Oscl_FileServer& fileserv) ; 432 433 //For native file I/O. 434 OsclNativeFile* iNativeFile; 435 int32 iNativeBufferSize; 436 uint32 iNativeAccessMode; 437 438 //For async read feature 439 uint32 iAsyncReadBufferSize; 440 OsclAsyncFile* iAsyncFile; 441 442 // These are wrappers to call the Native OS File IO calls with 443 // stats and logging. 444 445 int32 CallNativeOpen(const OsclFileHandle&, uint32 mode 446 , const OsclNativeFileParams& params 447 , Oscl_FileServer& fileserv); 448 int32 CallNativeOpen(const oscl_wchar *filename, uint32 mode 449 , const OsclNativeFileParams& params 450 , Oscl_FileServer& fileserv); 451 int32 CallNativeOpen(const char *filename, uint32 mode 452 , const OsclNativeFileParams& params 453 , Oscl_FileServer& fileserv); 454 uint32 CallNativeRead(OsclAny *buffer, uint32 size, uint32 numelements); 455 uint32 CallNativeWrite(const OsclAny *buffer, uint32 size, uint32 numelements); 456 int32 CallNativeSeek(TOsclFileOffset offset, Oscl_File::seek_type origin); 457 TOsclFileOffset CallNativeTell(); 458 int32 CallNativeFlush(); 459 int32 CallNativeEndOfFile(); 460 TOsclFileOffset CallNativeSize(); 461 int32 CallNativeClose(); 462 uint32 CallNativeMode(); 463 int32 CallNativeGetError(); 464 OSCL_IMPORT_REF uint32 GetAsyncFileNumOfRun(); 465 OSCL_IMPORT_REF uint32 GetAsyncFileNumOfRunError(); 466 467 }; 468 469 470 //Include all public file apis for convenience here. 471 #include "oscl_file_server.h" 472 #include "oscl_file_find.h" 473 #include "oscl_file_dir_utils.h" 474 #include "oscl_file_handle.h" 475 476 #endif // OSCL_FILE_IO_H_INCLUDED 477 478 /*! @} */ 479 480
