# Class Storage#readFile

storage

- Defined in: storage.js

Class Summary
Constructor Attributes | Constructor Name and Description
--- | ---
| Storage#readFile(successCallback, errorCallback, options) Reads from a file.

## Class Detail

Storage#readFile(successCallback, errorCallback, options)

Reads from a file.
It is designed to read a small data file from filesystem (not suited for a big data file).

Note : For reading a big chunk of data, it is recommended to use AJAX with local file.

    function readFile() {
       // This example will read a file as binary.

       var successCb = function (cbObject){
         // If file is read as binary, array of uint8 will be returned.
         // Create an image element, and set the source as the binary data.

         var binary_data = cbObject.data;
         var data_base64 = bin_array_to_base64(binary_data);
         var ele = document.createElement('img');
         ele.src = "data:image/jpeg;base64, " + data_base64;
         document.body.appendChild(ele);
       };

       var failureCb = function(cbObject){
         var errorCode = cbObject.errorCode;
         var errorText = cbObject.errorText;
         console.log( " Error Code [" + errorCode + "]: " + errorText);
       };

        // Read file from the start, read the whole file, and read as binary
       var options = {
         path: "file://internal/image.jpg",
         position : 0,
         encoding: 'binary'
       };

       var storage = new Storage();
       storage.readFile(successCb, failureCb, options);

       // This example will read file as text.
       var successCb = function (cbObject){
         // If file is read as text, utf encoded string will be returned.
         // Create an image element, and set the source as the binary data.

         var data_text = cbObject.data;
         var ele = document.createElement('div');
         ele.innerHTML = "Text is read: " + data_text;
         document.body.appendChild(ele);
       };

       var failureCb = function(cbObject){
         var errorCode = cbObject.errorCode;
         var errorText = cbObject.errorText;
         console.log( " Error Code [" + errorCode + "]: " + errorText);
       };

       // Read file from the start, read the whole file, and read as text.
       var options = {
         path : "file://internal/text.txt",
         position : 0,
         encoding: 'utf8'
       };

       var storage = new Storage();
       storage.readFile(successCb, failureCb, options);

    }

     // This is a recommended way of reading a big chunk of data from file with JQuery Ajax.
     // Reading a data chunk bigger than 50MB is not recommended because it can lead to memory overflow (depends on system).
     function readFileAjax(){
     	$.ajax({
     		url: "http://127.0.0.1:9080/chunk.data"
     	})
     	.fail(function(err){
     		// Handle error.
     	})
     	.done(function(data){
     		// Handle the data.
     	});
     }

Parameters:
{Function} successCallback
  success callback function.
{Function} errorCallback
  failure callback function.
{Object} options

  Property | Type | Description | Required
  --- | --- | --- | ---
  path | Storage.SCAP_URI | URI to the resource (internal/usb/sdcard). | required
  position | Number | Position where this file will be read from. Default value is 0. If the value of the position parameter is out of the range of the input file, error will be returned. | optional
  length | Number | The length of the Read buffer. Maximum length of the buffer that can be read is currently 10KB. Default value is 10KB. If the size of the file intended to be read is smaller than the length parameter, return data will include the contents of the file. | optional
  encoding | String | Encoding method to be used for return value. Default value is 'utf8'. Value of encoding can be: 'utf8' : Encoded as UTF-8. Return value will be a string. 'base64' : Encoded as base64. Return value will be a string. 'binary' : Raw binary data. Return value will be an ArrayBuffer. | optional

Since:
  1.2
Returns:

  A string containing the file data with given encoding will be returned ('utf8', 'base64'). If the encoding is 'binary', an ArrayBuffer will be returned.

  After the method is successfully executed, successCallback is called with file data. If an error occurs, errorCallback is called with errorCode and errorText. To see how error codes are defined, check Error.ERROR_CODE