src/OSD/OSD_File.cdl

   1 -- Created on: 1992-02-17
   2 -- Created by: Stephan GARNAUD
   3 -- Copyright (c) 1992-1999 Matra Datavision
   4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21
  22 -- Updated by:   J.P. TIRAULT September,1 1993
  23 --               The methods Read and Write have been overloaded. Now they
  24 --               accept as input/output buffer both an AsciiString and an
  25 --               address to a structure.
  26 -- Updated by:   J.P. TIRAULT January, 15 1995
  27 --               The method Read has been overloaded to read a line up to
  28 --               character LF (LineFeed)
  29 -- Updated by:   J.P. TIRAULT June, 15 1995
  30 --               Adds a data member for FILE* associated to the file
  31 -- Updated by:   E. PLOTNIKOV October 21 1999
  32 --                Set access method for myFILE field as 'protected' to
  33 --                 use it in sub-classes
  34
  35
  36 class File from OSD inherits FileNode
  37
  38     ---Purpose: Basic tools to manage files
  39     --  Warning: 'ProgramError' is raised when somebody wants to use the methods
  40     --          Read, Write, Seek, Close when File is not open.
  41
  42     uses
  43             Address from Standard,
  44             LockType from OSD,
  45             Protection from OSD,
  46             Path from OSD,
  47             Printer from OSD,
  48             OpenMode from OSD,
  49             FromWhere from OSD,
  50             KindFile from OSD,
  51             AsciiString from TCollection
  52
  53     raises ProgramError
  54
  55  is
  56   Create returns File;
  57      ---Purpose: Creates File object.
  58      ---Level: Public
  59
  60   Create (Name : Path) returns File;
  61      ---Purpose: Instantiates the object file, storing its name
  62      ---Level: Public
  63
  64   Build (me : in out; Mode : OpenMode; Protect : Protection)
  65      ---Purpose: CREATES a file if it doesn't already exists or empties
  66      --          an existing file.
  67      --          After 'Build', the file is open.
  68      --          If no name was given, ProgramError is raised.
  69      ---Level: Public
  70      raises ProgramError is static;
  71
  72   Open (me : in out; Mode : OpenMode ; Protect : Protection)
  73      ---Purpose: Opens a File with specific attributes
  74      --          This works only on already existing file.
  75      --          If no name was given, ProgramError is raised.
  76      ---Level: Public
  77      raises ProgramError is static;
  78
  79   Append (me : in out; Mode : OpenMode; Protect : Protection)
  80      ---Purpose: Appends data to an existing file.
  81      --          If file doesn't exist, creates it first.
  82      --          After 'Append', the file is open.
  83      --          If no name was given, ProgramError is raised.
  84      ---Level: Public
  85      raises ProgramError is static;
  86
  87   Read (me : in out; Buffer : out AsciiString ; Nbyte : Integer)
  88      ---Purpose: Attempts to read Nbyte bytes from the file associated with
  89      --          the object file.
  90      --          Upon successful completion, Read returns the number of
  91      --          bytes actually read and placed in the Buffer. This number
  92      --          may be less than Nbyte if the number of bytes left in the file
  93      --          is less than Nbyte bytes. In this case only number of read
  94      --          bytes will be placed in the buffer.
  95      ---Level: Public
  96
  97      raises ProgramError is static;
  98
  99
 100   ReadLine (me : in out; Buffer : out AsciiString ; NByte : Integer;
 101     NbyteRead : out Integer)
 102      ---Purpose:  Reads bytes from the data pointed to by the object file
 103      --           into the buffer <Buffer>.
 104      --           Data is read until <NByte-1> bytes have been read,
 105      --           until a newline character is read and transferred into
 106      --           <Buffer>, or until an EOF (End-of-File) condition is
 107      --           encountered.
 108      --           Upon successful completion, Read returns the number of
 109      --           bytes actually read into <NByteRead> and placed into the
 110      --           Buffer <Buffer>.
 111      ---Level: Public
 112
 113      raises ProgramError is static;
 114
 115   Read (me : in out; Buffer : out Address ; Nbyte    : Integer ;
 116                                             Readbyte : out Integer )
 117      ---Purpose: Attempts to read Nbyte bytes from the files associated with
 118      --          the object File.
 119      --          Upon successful completion, Read returns the number of
 120      --          bytes actually read and placed in the Buffer. This number
 121      --          may be less than Nbyte if the number of bytes left in the file
 122      --          is less than Nbyte bytes. For this reason the output
 123      --          parameter Readbyte will contain the number of read bytes.
 124      ---Level: Public
 125
 126      raises ProgramError is static;
 127
 128   Write (me : in out; Buffer: AsciiString ; Nbyte: Integer )
 129      ---Purpose: Attempts to write Nbyte bytes from the AsciiString to the file
 130      --          associated to the object File.
 131      ---Level: Public
 132
 133      raises ProgramError is static;
 134
 135   Write (me : in out; Buffer: Address ; Nbyte: Integer )
 136      ---Purpose: Attempts to write Nbyte bytes from the buffer pointed
 137      --          to by Buffer to the file associated to the object File.
 138      ---Level: Public
 139      raises ProgramError is static;
 140
 141
 142   Seek (me : in out; Offset : Integer ; Whence: FromWhere )
 143      ---Purpose: Sets the seek pointer associated with the open file
 144      ---Warning: This is very slow on VMS.
 145      ---Level: Public
 146      raises ProgramError is static;
 147
 148   Close (me : in out)
 149      ---Purpose: Closes the file (and deletes a descriptor)
 150      ---Level: Public
 151      raises ProgramError is static;
 152
 153   IsAtEnd (me : in out) returns Boolean
 154      ---Purpose: Returns TRUE if the seek pointer is at end of file.
 155      ---Level: Public
 156      raises ProgramError is static;
 157
 158   KindOfFile (me) returns KindFile;
 159      ---Purpose: Returns the kind of file. A file can be a
 160      --          file, a directory or a link.
 161
 162   BuildTemporary (myclass) returns File;
 163      ---Purpose: Makes a temporary File
 164      --          This returned file is already open !
 165      --          This file is non-persistent and will be automatically
 166      --          removed when its process finishes.
 167      ---Level: Public
 168
 169   SetLock (me : in out ; Lock : LockType)
 170      ---Purpose: Locks current file
 171      ---Level: Public
 172      raises ProgramError is static;
 173
 174   UnLock (me : in out)
 175      ---Purpose: Unlocks current file
 176      ---Level: Public
 177      raises ProgramError is static;
 178
 179   GetLock (me : in out) returns LockType
 180      ---Purpose: Returns the current lock state
 181      ---Level: Public
 182      raises ProgramError is static;
 183
 184   IsLocked (me : in out) returns Boolean
 185      ---Purpose: Returns TRUE if this file is locked.
 186      ---Level: Public
 187      raises ProgramError is static;
 188
 189   Size (me: out) returns Integer
 190      ---Purpose: Returns actual number of bytes of <me>.
 191      ---Level: Public
 192      raises ProgramError is static;
 193
 194   Print (me : in out; WhichPrinter : Printer)
 195      ---Purpose: Prints a file on selected printer.
 196      ---Level: Public
 197      raises ProgramError is static;
 198
 199   IsOpen (me) returns Boolean
 200      ---Purpose: Returns TRUE if <me> is open.
 201      ---Level: Public
 202      raises ProgramError is static;
 203
 204   IsReadable (me : in out)     returns Boolean from Standard ;
 205      ---Purpose: returns TRUE if the file exists and if the user
 206      --          has the autorization to read it.
 207
 208   IsWriteable(me : in out)     returns Boolean from Standard ;
 209      ---Purpose: returns TRUE if the file can be read and overwritten.
 210
 211   IsExecutable(me : in out)     returns Boolean from Standard ;
 212      ---Purpose: returns TRUE if the file can be executed.
 213
 214   ReadLastLine (me: in out; aLine: out AsciiString ; aDelay: in Integer ;
 215     aNbTries: in Integer)  returns Boolean
 216      ---Purpose: Enables to emulate unix "tail -f" command.
 217      -- If a line is available in the file <me> returns it.
 218      -- Otherwise attemps to read again aNbTries times in the file
 219      -- waiting aDelay seconds between each read.
 220      -- If meanwhile the file increases returns the next line, otherwise
 221      -- returns FALSE.
 222      raises ProgramError is static;
 223
 224   Edit(me: in out)
 225     returns Boolean from Standard;
 226     ---Purpose: find an editor on the system and edit the given file
 227     ---Level: Public
 228
 229  fields
 230     ImperativeFlag : Boolean; -- Says if lock is imperative or not
 231     myLock         : LockType;
 232     myMode         : OpenMode;
 233     myIO           : Integer is protected; -- Stores peculiar I/O informations
 234     myFILE         : Address is protected;
 235     myBuffer       : CString ;
 236     myCurrPtr      : CString ;
 237     myEndPtr       : CString ;
 238 end File from OSD;
 239
 240