Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

RhoFile

Methods25
Constructs
DestructorConstructor
Methods - Class
basenamecopydeleteDirdeleteFiledeleteRecursivedirnameexistsgetFileSizeisDirisFilejoinlistDirmakeDirmakeDirsreadrename
Methods - Instance
flushisOpenedreadreadAllseeksizewrite
Examples1
List contents of a folder

This API provides several methods for access to files and folders found on the device’s local file system.

Use this API to access local files for reading and writing. Only string data can be read and written with this API. Please note that binary files are not supported. Strings filled with \0 will be truncated to the last non \0 character.

Enabling the API

This API is part of the coreapi extension that is included automatically.

extensions: ["coreapi"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

basename
(STRING path)

Return basename part for the specified path. Will remove any prefix up to the last path separator (‘/’ or ‘\’ depending on platform). Example: for path ‘/full/path/to/file.ext’ basename will return ‘file.ext’.

Parameters

  • path : STRING

    Absolute path for which basename is given.

Synchronous Return:

  • STRING :

    Basename part for the given path.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.basename(STRING path)
    • Ruby: Rho::RhoFile.basename(STRING path)
Destructor close
()

Closes file. Once Close method is invoked, no file object will be alive.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method is a destructor and can only be accessed via the object that was created by the `new` constructor.
    • JavaScript: myObj.close()
    • Ruby: @myObj.close()
copy
(STRING from, STRING to)

Copies file from “from” (source) to “to” (destination).

Parameters

  • from : STRING

    File name to be copied.

  • to : STRING

    Destination path.

Synchronous Return:

  • INTEGER :

    Error code raised during copy operation. 0 if no error.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.copy(STRING from, STRING to)
    • Ruby: Rho::RhoFile.copy(STRING from, STRING to)
deleteDir
(STRING path)

Deletes specified directory. The specified directory must be empty to be deleted.

Parameters

  • path : STRING

    Absolute path to the directory to be deleted.

Synchronous Return:

  • INTEGER :

    Error code raised on directory deletion. 0 on success, -1 otherwise.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.deleteDir(STRING path)
    • Ruby: Rho::RhoFile.deleteDir(STRING path)
deleteFile
(STRING path)

Deletes file.

Parameters

  • path : STRING

    Absolute path to the file to be deleted.

Synchronous Return:

  • INTEGER :

    Error code raised on file deletion. 0 on success, -1 otherwise.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.deleteFile(STRING path)
    • Ruby: Rho::RhoFile.deleteFile(STRING path)
deleteRecursive
(STRING path, BOOLEAN leaveRoot)

Deletes all directory contents.

Parameters

  • path : STRING

    Absolute path to the directory.

  • leaveRoot : BOOLEAN Optional Default: false

    Set to true if you only want to delete directory contents, but no the directory itself.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.deleteRecursive(STRING path, BOOLEAN leaveRoot)
    • Ruby: Rho::RhoFile.deleteRecursive(STRING path, BOOLEAN leaveRoot)
dirname
(STRING path)

Returns directory name part of the specified path.

Parameters

  • path : STRING

    Absolute path to directory.

Synchronous Return:

  • STRING :

    Directory name.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.dirname(STRING path)
    • Ruby: Rho::RhoFile.dirname(STRING path)
exists
(STRING path)

Checks if specified path exists.

Parameters

  • path : STRING

    Absolute path to file or directory.

Synchronous Return:

  • BOOLEAN :

    True if path exists, otherwise false.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.exists(STRING path)
    • Ruby: Rho::RhoFile.exists(STRING path)
flush
()

Flushes all buffered data to the storage media.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.flush()
getFileSize
(STRING path)

Returns size of the file.

Parameters

  • path : STRING

    Absolute path to the file.

Synchronous Return:

  • INTEGER :

    File size in bytes.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.getFileSize(STRING path)
    • Ruby: Rho::RhoFile.getFileSize(STRING path)
isDir
(STRING path)

Checks if specified path is a directory.

Parameters

  • path : STRING

    Absolute path of the directory.

Synchronous Return:

  • BOOLEAN :

    True if path is a directory. False otherwise.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.isDir(STRING path)
    • Ruby: Rho::RhoFile.isDir(STRING path)
isFile
(STRING path)

Checks if specified path is a file.

Parameters

  • path : STRING

    Absolute path of the file.

Synchronous Return:

  • BOOLEAN :

    True if path is a file, false otherwise.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.isFile(STRING path)
    • Ruby: Rho::RhoFile.isFile(STRING path)
isOpened
()

Checks if file is opened.

Synchronous Return:

  • BOOLEAN :

    True if file is opened, false otherwise.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.isOpened()
join
(STRING p1, STRING p2)

Joins two parts of the path considering all necessary path delimiters. I.e.: join(‘/path/to’,‘file’) will return ‘/path/to/file’

Parameters

  • p1 : STRING

    First part of the path.

  • p2 : STRING

    Second part of the path.

Synchronous Return:

  • STRING :

    Joined path.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.join(STRING p1, STRING p2)
    • Ruby: Rho::RhoFile.join(STRING p1, STRING p2)
listDir
(STRING path)

Lists all entries of specified directory.

Parameters

  • path : STRING

    Absolute path to directory.

Synchronous Return:

  • ARRAY :

    Array of directory entry names. If directory is empty array of size 0 will be returned.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.listDir(STRING path)
    • Ruby: Rho::RhoFile.listDir(STRING path)
makeDir
(STRING path)

Creates directory with the provided path. If all top-level nodes of the path doesn’t exists, directory will not be created.

Parameters

  • path : STRING

    Path to the new directory.

Synchronous Return:

  • INTEGER :

    Error code raised on directory creation. 0 on success, -1 otherwise.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.makeDir(STRING path)
    • Ruby: Rho::RhoFile.makeDir(STRING path)
makeDirs
(STRING path)

Creates directory and all top-level directories if necessary. Subsequent isDir call is necessary to check if path was successfully created.

Parameters

  • path : STRING

    Absolute path to the directory to be created.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.makeDirs(STRING path)
    • Ruby: Rho::RhoFile.makeDirs(STRING path)
Constructor Rho::RhoFile
(STRING path, INTEGER mode)

Opens file in a mode specified by the “mode” parameter.

Parameters

  • path : STRING

    Absolute path to the file.

  • mode : INTEGER

    Mode in which to open the file.

    Possible Values :

    Constant: Rho::RhoFile.OPEN_FOR_APPEND (For Ruby use "::" for all "." when referencing constants)
    String:1

    Open file for output at the end of a file. The file is created if it does not exist.

    Constant: Rho::RhoFile.OPEN_FOR_READ (For Ruby use "::" for all "." when referencing constants)
    String:2

    Open file for read-only operations. The file must exist.

    Constant: Rho::RhoFile.OPEN_FOR_WRITE (For Ruby use "::" for all "." when referencing constants)
    String:3

    Create an empty file for output operations. If a file with the same name already exists, its contents are discarded and the file is treated as a new empty file.

    Constant: Rho::RhoFile.OPEN_FOR_READ_WRITE (For Ruby use "::" for all "." when referencing constants)
    String:4

    Open a file for update (both for read and write). The file must exist.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method is a constructor and can only be accessed via the `new` construct.
    • JavaScript: var myObj = new Rho.RhoFile(STRING path, INTEGER mode)
    • Ruby: @myObj = Rho::RhoFile.new(STRING path, INTEGER mode)
read
(INTEGER size)

Reads specified number of characters from current position of the file.

Parameters

  • size : INTEGER

    Number of characters to be read.

Synchronous Return:

  • STRING :

    String from current position of file containing specified number of characters.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.read(INTEGER size)
read
(STRING path)

Reads specified file to a string object.

Parameters

  • path : STRING

    Absolute path to file.

Synchronous Return:

  • STRING :

    File contents.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.read(STRING path)
    • Ruby: Rho::RhoFile.read(STRING path)
readAll
()

Reads all file contents to the string object.

Synchronous Return:

  • STRING :

    Contents of the file.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.readAll()
rename
(STRING from, STRING to)

Renames / moves file.

Parameters

  • from : STRING

    Original path / name.

  • to : STRING

    New path / name.

Synchronous Return:

  • INTEGER :

    Error code raised on move / rename. 0 on success, -1 otherwise.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.RhoFile.rename(STRING from, STRING to)
    • Ruby: Rho::RhoFile.rename(STRING from, STRING to)
seek
(INTEGER pos)

Sets file position to specified value from the beginning of the file.

Parameters

  • pos : INTEGER

    Position within the file.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.seek(INTEGER pos)
size
()

Returns file size.

Synchronous Return:

  • INTEGER :

    File size in bytes.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.size()
write
(STRING val)

Writes the provided string at current position in the file.

Parameters

  • val : STRING

    String to be written to the file.

Synchronous Return:

  • INTEGER :

    Number of bytes written.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.write(STRING val)

Examples

List contents of a folder

Iterate through the contents of a folder and divide the entries in “folders” and “files”.

var folders = [];
var files = [];
var root_path = "/arbitrary/path"
var entries = Rho.RhoFile.listDir(root_path);

for (var i = 0; i < entries.length; i++) {
  var entry = entries[i];
  if ((entry != ".") && (entry != "..")) {

    (Rho.RhoFile.isDir(Rho.RhoFile.join(root_path, entry)) ? folders : files).push(entry);
  }
}
                   
                 
folders = []
files = []

root_path = "/arbitrary/path"
entries = Rho::RhoFile.listDir(root_path)

entries.each do |entry|
  unless (entry == "." || entry == "..")
    (Rho::RhoFile.isDir(Rho::RhoFile.join(root_path,entry)) ? folders : files) << entry
  end
end