ReadFile()

Syntax

Result = ReadFile(#File, Filename$, Callback [, Flags])
Description
Open an existing file for read-only operations.

Parameters

#File The number to identify the file. #PB_Any can be used to auto-generate this number.
Filename$ The name of the file to read. The filename can be an URL or a local file (if the flag #PB_LocalFile is set).
Callback The callback to be called when data has been read from the file. If the flag #PB_File_Streaming is not set, the callback will be called only when the whole file has been read. It has to use the following syntax:
  Procedure Callback(Status, Filename$, File, SizeRead)
    Select Status
      Case #PB_Status_Loaded
        ; File correctly loaded
        
      Case #PB_Status_Progress
        ; File loading in progress, use FileProgress() get the current progress

      Case #PB_Status_Error
        ; File loading has failed
    EndSelect
  EndProcedure
Flags (optional) It can be a combination (using the '| operand) of the following values:
  #PB_LocalFile: the filename is a local file. OpenFileRequester()() needs to be called before
                 to have access to local files. SelectedFileID()() is used to get the
                 local file identifier.
  #PB_GoogleDriveFile: the filename is a google drive file identifier. OpenFileRequester()() can be called with the #PB_Requester_GoogleDrive
                 flag, SelectedFileID()() can be used to get the google drive file identifier.
  #PB_File_Streaming: the file will be read chunk by chunk, using FetchData(). It is only 
                      supported with #PB_LocalFile. 
  #PB_LocalStorage: will read the file on client side using its filename. The file should have been created before with OpenFile() or CreateFile()
                  using the  #PB_LocalStorage flag.
combined with one of the following values (the following flags affect the ReadString() and ReadCharacter() behaviour):
  #PB_Ascii  : all read string operation will use ascii if not specified otherwise.
  #PB_UTF8   : all read string operation will use UTF-8 if not specified otherwise (default).
  #PB_Unicode: all read string operation will use Unicode if not specified otherwise.

Return value

Returns nonzero if the file was opened successfully and zero if there was an error. If #PB_Any was used as the #File parameter then the new generated number is returned on success.

Remarks

To create a new and empty file, use the CreateFile() function.

Example


  Procedure ReadCallback(Status, Filename$, File, Size)
    If Status = #PB_Status_Loaded
      Debug "File: " + Filename$ + " - Size: " + Size + " bytes"
      
      ; Read the first 10 lines
      ;
      While Eof(0) = 0 And NbLine < 10 
        Debug ReadString(0)            
        NbLine+1
      Wend
      
      CloseFile(0)
      
    ElseIf Status = #PB_Status_Error
      Debug "Error when loading the file: " + Filename$
    EndIf
  EndProcedure
  
  Procedure OpenFileRequesterCallback()
    If NextSelectedFile()
      ReadFile(0, SelectedFileID(), @ReadCallback(), #PB_LocalFile)
    EndIf
  EndProcedure
  
  Procedure ChooseFileEvent()
    OpenFileRequester("*.txt", @OpenFileRequesterCallback())
  EndProcedure
  
  OpenWindow(0, 0, 0, 300, 50, "Read file example", #PB_Window_ScreenCentered)
    ButtonGadget(0, 10, 10, 280, 30, "Choose a file...")
    
  BindGadgetEvent(0, @ChooseFileEvent())

See Also

CreateFile(), CloseFile(), FileProgress()()
<- ReadDouble() - File Index - ReadFloat() ->