1/* 2 * Python bindings. 3 * 4 * Open Phone Abstraction Library (OPAL) 5 * 6 * Copyright (c) 2011 Demetrius Cassidy 7 * 8 * The contents of this file are subject to the Mozilla Public License 9 * Version 1.0 (the "License"); you may not use this file except in 10 * compliance with the License. You may obtain a copy of the License at 11 * http://www.mozilla.org/MPL/ 12 * 13 * Software distributed under the License is distributed on an "AS IS" 14 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 15 * the License for the specific language governing rights and limitations 16 * under the License. 17 * 18 * The Original Code is Open Phone Abstraction Library (OPAL) 19 * 20 * The Initial Developer of the Original Code is Demetrius Cassidy 21 * 22 * Contributor(s): ______________________________________. 23 * 24 * $Revision: 26117 $ 25 * $Author: rjongbloed $ 26 * $Date: 2011-07-04 22:45:05 -0500 (Mon, 04 Jul 2011) $ 27 */ 28 29%ModuleHeaderCode 30#include <ptlib.h> 31#include <ptlib/file.h> 32%End 33 34 35/////////////////////////////////////////////////////////////////////////////// 36// Binary Files 37 38/**This class represents a disk file. This is a particular type of I/O channel 39 that has certain attributes. All platforms have a disk file, though exact 40 details of naming convertions etc may be different. 41 42 The basic model for files is that they are a named sequence of bytes that 43 persists within a directory structure. The transfer of data to and from 44 the file is made at a current position in the file. This may be set to 45 random locations within the file. 46 */ 47class PFile : PChannel 48{ 49 private: 50 PFile(const PFile& ); 51 52 public: 53 /**@name Construction */ 54 //@{ 55 /**Create a file object but do not open it. It does not initially have a 56 valid file name. However, an attempt to open the file using the 57 <code>Open()</code> function will generate a unique temporary file. 58 */ 59 PFile(); 60 61 /**When a file is opened, it may restrict the access available to 62 operations on the object instance. A value from this enum is passed to 63 the <code>Open()</code> function to set the mode. 64 */ 65 enum OpenMode { 66 ReadOnly, ///< File can be read but not written. 67 WriteOnly, ///< File can be written but not read. 68 ReadWrite ///< File can be both read and written. 69 }; 70 71 /**When a file is opened, a number of options may be associated with the 72 open file. These describe what action to take on opening the file and 73 what to do on closure. A value from this enum is passed to the 74 <code>Open()</code> function to set the options. 75 76 The <code>ModeDefault</code> option will use the following values: 77 \arg \c ReadOnly <code>MustExist</code> 78 \arg \c WriteOnly <code>Create | Truncate</code> 79 \arg \c ReadWrite <code>Create</code> 80 */ 81 enum OpenOptions { 82 /// File options depend on the OpenMode parameter. 83 ModeDefault = -1, 84 /// File open fails if file does not exist. 85 MustExist = 0, 86 /// File is created if it does not exist. 87 Create = 1, 88 /// File is set to zero length if it already exists. 89 Truncate = 2, 90 /// File open fails if file already exists. 91 Exclusive = 4, 92 /// File is temporary and is to be deleted when closed. 93 Temporary = 8, 94 /// File may not be read by another process. 95 DenySharedRead = 16, 96 /// File may not be written by another process. 97 DenySharedWrite = 32 98 }; 99 100 /**Create a unique temporary file name, and open the file in the specified 101 mode and using the specified options. Note that opening a new, unique, 102 temporary file name in ReadOnly mode will always fail. This would only 103 be usefull in a mode and options that will create the file. 104 105 The <code>PChannel::IsOpen()</code> function may be used after object 106 construction to determine if the file was successfully opened. 107 */ 108 PFile( 109 OpenMode mode, ///< Mode in which to open the file. 110 int opts = ModeDefault ///< <code>OpenOptions</code> enum# for open operation. 111 ); 112 113 /**Create a file object with the specified name and open it in the 114 specified mode and with the specified options. 115 116 The <code>PChannel::IsOpen()</code> function may be used after object 117 construction to determine if the file was successfully opened. 118 */ 119 PFile( 120 const PFilePath & name, ///< Name of file to open. 121 OpenMode mode = ReadWrite, ///< Mode in which to open the file. 122 int opts = ModeDefault ///< <code>OpenOptions</code> enum# for open operation. 123 ); 124 125 /// Close the file on destruction. 126 ~PFile(); 127 //@} 128 129 130 /**@name Overrides from class PObject */ 131 //@{ 132 /**Determine the relative rank of the two objects. This is essentially the 133 string comparison of the <code>PFilePath</code> names of the files. 134 135 @return 136 relative rank of the file paths. 137 */ 138 Comparison Compare( 139 const PObject & obj ///< Other file to compare against. 140 ) const; 141 //@} 142 143 144 /**@name Overrides from class PChannel */ 145 //@{ 146 /**Get the platform and I/O channel type name of the channel. For example, 147 it would return the filename in <code>PFile</code> type channels. 148 149 @return 150 the name of the channel. 151 */ 152 virtual PString GetName() const; 153 154 /**Low level read from the file channel. The read timeout is ignored for 155 file I/O. The GetLastReadCount() function returns the actual number 156 of bytes read. 157 158 The GetErrorCode() function should be consulted after Read() returns 159 false to determine what caused the failure. 160 161 @return 162 true indicates that at least one character was read from the channel. 163 false means no bytes were read due to timeout or some other I/O error. 164 */ 165 virtual PBoolean Read( 166 void * buf, ///< Pointer to a block of memory to receive the read bytes. 167 PINDEX len ///< Maximum number of bytes to read into the buffer. 168 ); 169 170 /**Low level write to the file channel. The write timeout is ignored for 171 file I/O. The GetLastWriteCount() function returns the actual number 172 of bytes written. 173 174 The GetErrorCode() function should be consulted after Write() returns 175 false to determine what caused the failure. 176 177 @return true if at least len bytes were written to the channel. 178 */ 179 virtual PBoolean Write( 180 const void * buf, ///< Pointer to a block of memory to write. 181 PINDEX len ///< Number of bytes to write. 182 ); 183 184 /** Close the file channel. 185 @return true if close was OK. 186 */ 187 virtual PBoolean Close(); 188 //@} 189 190 191 /**@name File manipulation functions */ 192 //@{ 193 /**Check for file existance. 194 Determine if the file specified actually exists within the platforms 195 file system. 196 197 @return 198 true if the file exists. 199 */ 200 static PBoolean Exists( 201 const PFilePath & name ///< Name of file to see if exists. 202 ); 203 204 /**Check for file existance. 205 Determine if the file path specification associated with the instance 206 of the object actually exists within the platforms file system. 207 208 @return 209 true if the file exists. 210 */ 211 PBoolean Exists() const; 212 213 /**Check for file access modes. 214 Determine if the file specified may be opened in the specified mode. This would 215 check the current access rights to the file for the mode. For example, 216 for a file that is read only, using mode == ReadWrite would return 217 false but mode == ReadOnly would return true. 218 219 @return 220 true if a file open would succeed. 221 */ 222 static PBoolean Access( 223 const PFilePath & name, ///< Name of file to have its access checked. 224 OpenMode mode ///< Mode in which the file open would be done. 225 ); 226 227 /**Check for file access modes. 228 Determine if the file path specification associated with the 229 instance of the object may be opened in the specified mode. This would 230 check the current access rights to the file for the mode. For example, 231 for a file that is read only, using mode == ReadWrite would return 232 false but mode == ReadOnly would return true. 233 234 @return 235 true if a file open would succeed. 236 */ 237 PBoolean Access( 238 OpenMode mode ///< Mode in which the file open would be done. 239 ); 240 241 /**Delete the specified file. If <code>force</code> is false and the file 242 is protected against being deleted then the function fails. If 243 <code>force</code> is true then the protection is ignored. What 244 constitutes file deletion protection is platform dependent, eg on DOS 245 is the Read Only attribute and on a Novell network it is a Delete 246 trustee right. Some protection may not be able to overridden with the 247 <code>force</code> parameter at all, eg on a Unix system and you are 248 not the owner of the file. 249 250 @return 251 true if the file was deleted. 252 */ 253 static PBoolean Remove( 254 const PFilePath & name, // Name of file to delete. 255 PBoolean force = false // Force deletion even if file is protected. 256 ); 257 static PBoolean Remove( 258 const PString & name, // Name of file to delete. 259 PBoolean force = false // Force deletion even if file is protected. 260 ); 261 262 /**Delete the current file. If <code>force</code> is false and the file 263 is protected against being deleted then the function fails. If 264 <code>force</code> is true then the protection is ignored. What 265 constitutes file deletion protection is platform dependent, eg on DOS 266 is the Read Only attribute and on a Novell network it is a Delete 267 trustee right. Some protection may not be able to overridden with the 268 <code>force</code> parameter at all, eg on a Unix system and you are 269 not the owner of the file. 270 271 @return 272 true if the file was deleted. 273 */ 274 PBoolean Remove( 275 PBoolean force = false // Force deletion even if file is protected. 276 ); 277 278 /**Change the specified files name. This does not move the file in the 279 directory hierarchy, it only changes the name of the directory entry. 280 281 The <code>newname</code> parameter must consist only of the file name 282 part, as returned by the <code>PFilePath::GetFileName()</code> function. Any 283 other file path parts will cause an error. 284 285 The first form uses the file path specification associated with the 286 instance of the object. The name within the instance is changed to the 287 new name if the function succeeds. The second static function uses an 288 arbitrary file specified by name. 289 290 @return 291 true if the file was renamed. 292 */ 293 static PBoolean Rename( 294 const PFilePath & oldname, ///< Old name of the file. 295 const PString & newname, ///< New name for the file. 296 PBoolean force = false 297 ///< Delete file if a destination exists with the same name. 298 ); 299 300 /**Change the current files name. 301 This does not move the file in the 302 directory hierarchy, it only changes the name of the directory entry. 303 304 The <code>newname</code> parameter must consist only of the file name 305 part, as returned by the <code>PFilePath::GetFileName()</code> function. Any 306 other file path parts will cause an error. 307 308 The first form uses the file path specification associated with the 309 instance of the object. The name within the instance is changed to the 310 new name if the function succeeds. The second static function uses an 311 arbitrary file specified by name. 312 313 @return 314 true if the file was renamed. 315 */ 316 PBoolean Rename( 317 const PString & newname, ///< New name for the file. 318 PBoolean force = false 319 ///< Delete file if a destination exists with the same name. 320 ); 321 322 /**Make a copy of the specified file. 323 324 @return 325 true if the file was renamed. 326 */ 327 static PBoolean Copy( 328 const PFilePath & oldname, ///< Old name of the file. 329 const PFilePath & newname, ///< New name for the file. 330 PBoolean force = false 331 ///< Delete file if a destination exists with the same name. 332 ); 333 334 /**Make a copy of the current file. 335 336 @return 337 true if the file was renamed. 338 */ 339 PBoolean Copy( 340 const PFilePath & newname, ///< New name for the file. 341 PBoolean force = false 342 ///< Delete file if a destination exists with the same name. 343 ); 344 345 /**Move the specified file. This will move the file from one position in 346 the directory hierarchy to another position. The actual operation is 347 platform dependent but the reslt is the same. For instance, for Unix, 348 if the move is within a file system then a simple rename is done, if 349 it is across file systems then a copy and a delete is performed. 350 351 @return 352 true if the file was moved. 353 */ 354 static PBoolean Move( 355 const PFilePath & oldname, ///< Old path and name of the file. 356 const PFilePath & newname, ///< New path and name for the file. 357 PBoolean force = false 358 ///< Delete file if a destination exists with the same name. 359 ); 360 361 /**Move the current file. This will move the file from one position in 362 the directory hierarchy to another position. The actual operation is 363 platform dependent but the reslt is the same. For instance, for Unix, 364 if the move is within a file system then a simple rename is done, if 365 it is across file systems then a copy and a delete is performed. 366 367 @return 368 true if the file was moved. 369 */ 370 // Function is not defined. 371 // PBoolean Move( 372 // const PFilePath & newname, ///< New path and name for the file. 373 // PBoolean force = false 374 // ///< Delete file if a destination exists with the same name. 375 // ); 376 //@} 377 378 /**@name File channel functions */ 379 //@{ 380 /**Get the full path name of the file. The <code>PFilePath</code> object 381 describes the full file name specification for the particular platform. 382 383 @return 384 the name of the file. 385 */ 386 const PFilePath & GetFilePath() const; 387 388 /**Set the full path name of the file. The <code>PFilePath</code> object 389 describes the full file name specification for the particular platform. 390 */ 391 void SetFilePath( 392 const PString & path ///< New file path. 393 ); 394 395 396 /**Open the current file in the specified mode and with 397 the specified options. If the file object already has an open file then 398 it is closed. 399 400 If there has not been a filename attached to the file object (via 401 <code>SetFilePath()</code>, the <code>name</code> parameter or a previous 402 open) then a new unique temporary filename is generated. 403 404 @return 405 true if the file was successfully opened. 406 */ 407 virtual PBoolean Open( 408 OpenMode mode = ReadWrite, // Mode in which to open the file. 409 int opts = ModeDefault // Options for open operation. 410 ); 411 412 /**Open the specified file name in the specified mode and with 413 the specified options. If the file object already has an open file then 414 it is closed. 415 416 Note: if <code>mode</code> is StandardInput, StandardOutput or StandardError, 417 then the <code>name</code> parameter is ignored. 418 419 @return 420 true if the file was successfully opened. 421 */ 422 virtual PBoolean Open( 423 const PFilePath & name, // Name of file to open. 424 OpenMode mode = ReadWrite, // Mode in which to open the file. 425 int opts = ModeDefault // <code>OpenOptions</code> enum# for open operation. 426 ); 427 428 /**Get the current size of the file. 429 430 @return 431 length of file in bytes. 432 */ 433 virtual off_t GetLength() const; 434 435 /**Set the size of the file, padding with 0 bytes if it would require 436 expanding the file, or truncating it if being made shorter. 437 438 @return 439 true if the file size was changed to the length specified. 440 */ 441 virtual PBoolean SetLength( 442 off_t len // New length of file. 443 ); 444 445 /// Options for the origin in setting the file position. 446 enum FilePositionOrigin { 447 /// Set position relative to start of file. 448 Start = SEEK_SET, 449 /// Set position relative to current file position. 450 Current = SEEK_CUR, 451 /// Set position relative to end of file. 452 End = SEEK_END 453 }; 454 455 /**Set the current active position in the file for the next read or write 456 operation. The <code>pos</code> variable is a signed number which is 457 added to the specified origin. For <code>origin == PFile::Start</code> 458 only positive values for <code>pos</code> are meaningful. For 459 <code>origin == PFile::End</code> only negative values for 460 <code>pos</code> are meaningful. 461 462 @return 463 true if the new file position was set. 464 */ 465 virtual PBoolean SetPosition( 466 off_t pos, ///< New position to set. 467 FilePositionOrigin origin = Start ///< Origin for position change. 468 ); 469 470 /**Get the current active position in the file for the next read or write 471 operation. 472 473 @return 474 current file position relative to start of file. 475 */ 476 virtual off_t GetPosition() const; 477 478 /**Determine if the current file position is at the end of the file. If 479 this is true then any read operation will fail. 480 481 @return 482 true if at end of file. 483 */ 484 PBoolean IsEndOfFile() const; 485 486 /**Get information (eg protection, timestamps) on the specified file. 487 488 @return 489 true if the file info was retrieved. 490 */ 491 static PBoolean GetInfo( 492 const PFilePath & name, // Name of file to get the information on. 493 PFileInfo & info 494 // <code>PFileInfo</code> structure to receive the information. 495 ); 496 497 /**Get information (eg protection, timestamps) on the current file. 498 499 @return 500 true if the file info was retrieved. 501 */ 502 PBoolean GetInfo( 503 PFileInfo & info 504 // <code>PFileInfo</code> structure to receive the information. 505 ); 506 507 /**Set permissions on the specified file. 508 509 @return 510 true if the file was renamed. 511 */ 512 static PBoolean SetPermissions( 513 const PFilePath & name, // Name of file to change the permission of. 514 int permissions // New permissions mask for the file. 515 ); 516 /**Set permissions on the current file. 517 518 @return 519 true if the file was renamed. 520 */ 521 PBoolean SetPermissions( 522 int permissions // New permissions mask for the file. 523 ); 524 //@} 525 526/////////////////////////////////////////////////////////////////////////////// 527// PFile 528// #include "msos/ptlib/file.h" 529 530 protected: 531 virtual PBoolean IsTextFile() const; 532 // Return PTrue if text file translation is required 533 534// End Of File /////////////////////////////////////////////////////////////// 535 536}; 537 538 539 540// End Of File /////////////////////////////////////////////////////////////// 541