File

File

このAPIはW3Cの File API をベースとしています。ファイルシステムへの読み書きのための API です。

オブジェクト

File

このオブジェクトは一つのファイルの属性を含みます。

プロパティー

詳細

この File オブジェクトは一つのファイルの属性を含みます。 FileEntry オブジェクトの file メソッドを呼び出すことで、 File オブジェクトのインスタンスを取得できます。

サポートされているプラットフォーム

FileReader

FileReader はファイルの読み込みを行うオブジェクトです。

プロパティー

メソッド

詳細

FileReader オブジェクトはデバイスのファイルシステムからファイルを読み込む際に使用します。ファイルはテキストもしくは Base64 でエンコードされた文字列として読み込まれます。また、 loadstart, progress, load, loadend, error や abort などのイベントを受け取るための独自のイベントリスナーを登録することも出来ます。

サポートされているプラットフォーム

データ URL として読み込む場合

パラメーター: - file - 読み込むファイルのフルパスを表します

使用例

function win(file) {
    var reader = new FileReader();
    reader.onloadend = function(evt) {
        console.log("読み込み成功");
        console.log(evt.target.result);
    };
    reader.readAsDataURL(file);
};

var fail = function(evt) {
    console.log(error.code);
};

entry.file(win, fail);

テキストとして読み込む場合

パラメーター:

使用例

function win(file) {
    var reader = new FileReader();
    reader.onloadend = function(evt) {
        console.log("読み込み成功");
        console.log(evt.target.result);
    };
    reader.readAsText(file);
};

var fail = function(evt) {
    console.log(error.code);
};

entry.file(win, fail);

Abort の例

function win(file) {
    var reader = new FileReader();
    reader.onloadend = function(evt) {
        console.log("読み込み成功");
        console.log(evt.target.result);
    };
    reader.readAsText(file);
    reader.abort();
};

function fail(error) {
    console.log(error.code);
}

entry.file(win, fail);

詳細な使用例

<!DOCTYPE html>
<html>
  <head>
    <title>FileReader の使用例</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.7.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Cordova の読み込み完了まで待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // Cordova 準備完了
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, gotFS, fail);
    }

    function gotFS(fileSystem) {
        fileSystem.root.getFile("readme.txt", null, gotFileEntry, fail);
    }

    function gotFileEntry(fileEntry) {
        fileEntry.file(gotFile, fail);
    }

    function gotFile(file){
        readDataUrl(file);
        readAsText(file);
    }

    function readDataUrl(file) {
        var reader = new FileReader();
        reader.onloadend = function(evt) {
            console.log("データ URL として読み込み");
            console.log(evt.target.result);
        };
        reader.readAsDataURL(file);
    }

    function readAsText(file) {
        var reader = new FileReader();
        reader.onloadend = function(evt) {
            console.log("テキストとして読み込み");
            console.log(evt.target.result);
        };
        reader.readAsText(file);
    }

    function fail(evt) {
        console.log(evt.target.error.code);
    }

    </script>
  </head>
  <body>
    <h1>使用例</h1>
    <p>ファイルを読み込みます。</p>
  </body>
</html>

iOS に関する注意点

FileWriter

FileWriter はファイルへの書き込みを行うオブジェクトです。

プロパティー

メソッド

詳細

FileWriter オブジェクトはデバイスのファイルシステムに書きこむ際に使用します。また、 writestart, progress, write, writeend, error や abort などのイベントを受け取るための独自のイベントリスナーを登録することも出来ます。

FileWriter は一つのファイルに対して使用されます。複数回の書き込みを行うこともできます。 FileWriter はファイルポインタの位置と length 属性を指定することができるので、ファイルのどの位置からでも書き込みを行うことができます。デフォルトではファイルの開始位置にポインタがセットされ、既存のデータを上書きしながら書き込みが行われます。書き込みをファイルの最終から始める場合は、 FileWriter のコンストラクタに true をオプションとして指定してください。

サポートされているプラットフォーム

Seek の例

function win(writer) {
    // ファイルポインタを EOF (ファイルの終端) に移動
    writer.seek(writer.length);
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Truncate の例

function win(writer) {
    writer.truncate(10);
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Write の例

function win(writer) {
    writer.onwrite = function(evt) {
        console.log("書き込み成功");
    };
    writer.write("サンプルテキスト");
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Append の例

function win(writer) {
    writer.onwrite = function(evt) {
        console.log("書き込み成功");
    };
    writer.seek(writer.length);
    writer.write("付加テキスト);
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Abort の例

function win(writer) {
    writer.onwrite = function(evt) {
        console.log("書き込み成功");
    };
    writer.write("サンプルテキスト");
    writer.abort();
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

詳細な使用例

<!DOCTYPE html>
<html>
  <head>
    <title>FileWriter の使用例</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.7.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Cordova の読み込み完了まで待機
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova 準備完了
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, gotFS, fail);
    }

    function gotFS(fileSystem) {
        fileSystem.root.getFile("readme.txt", {create: true, exclusive: false}, gotFileEntry, fail);
    }

    function gotFileEntry(fileEntry) {
        fileEntry.createWriter(gotFileWriter, fail);
    }

    function gotFileWriter(writer) {
        writer.onwriteend = function(evt) {
            console.log("ファイルの内容が 'some sample text' となりました");
            writer.truncate(11); 
            writer.onwriteend = function(evt) {
                console.log("ファイルの内容が 'some sample' となりました");
                writer.seek(4);
                writer.write(" different text");
                writer.onwriteend = function(evt){
                    console.log("ファイルの内容が 'some different text' となりました");
                }
            };
        };
        writer.write("サンプルテキスト");
    }

    function fail(error) {
        console.log(error.code);
    }

    </script>
  </head>
  <body>
    <h1>使用例</h1>
    <p>ファイルに書き込みます。</p>
  </body>
</html>

FileSystem

このオブジェクトはファイルシステムを表します。

プロパティー

詳細

FileSystem オブジェクトはファイルシステムの情報を表します。ファイルシステムの名前は既にあるファイルシステムに対して一意になります。 root プロパティーはファイルシステムのルートディレクトリを表す DirectoryEntry オブジェクトを保持します。

サポートされているプラットフォーム

File System の使用例

function onSuccess(fileSystem) {
    console.log(fileSystem.name);
    console.log(fileSystem.root.name);
}

// ファイルシステムをリクエスト
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, null);

詳細な使用例

<!DOCTYPE html>
<html>
  <head>
    <title>File System の使用例</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.7.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Cordova の読み込み完了まで待機
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova 準備完了
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onFileSystemSuccess, fail);
    }

    function onFileSystemSuccess(fileSystem) {
        console.log(fileSystem.name);
        console.log(fileSystem.root.name);
    }

    function fail(evt) {
        console.log(evt.target.error.code);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>File System</p>
  </body>
</html>

FileEntry

このオブジェクトはファイルシステムのファイルを表します。これは W3C Directories and Systems の仕様書で定義されています。

プロパティー

注意: 以下の属性は W3C の仕様書によって定義されていますが、 Cordova では サポートされていません :

メソッド

サポートされているプラットフォーム

getMetadata

ファイルのメタデータを取得します。

パラメーター:

使用例

function success(metadata) {
    console.log("最終更新日: " + metadata.modificationTime);
}

function fail(error) {
    alert(error.code);
}

// このエントリーの Metadata オブジェクトを取得
entry.getMetadata(success, fail);

moveTo

ファイルを、ファイルシステム内の別の場所に移動します。 以下のことを試みるとエラーが発生します:

ファイルをすでに存在するファイルの場所に移動する行為は、削除してファイルを置き換える行為となります。

パラメーター:

使用例

function success(entry) {
    console.log("新しいパス: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function moveFile(entry) {
    var parent = document.getElementById('parent').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // ファイルを新しいディレクトリに移動し、名前付け替えます
    entry.moveTo(parentEntry, "newFile.txt", success, fail);
}

copyTo

ファイルを、ファイルシステム内の別の場所にコピーします。以下のことを試みるとエラーが発生します:

パラメーター:

使用例

function win(entry) {
    console.log("新しいパス: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function copyFile(entry) {
    var parent = document.getElementById('parent').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // ファイルを新しいディレクトリにコピーし、名前付け替えます
    entry.copyTo(parentEntry, "file.copy", success, fail);
}

toURI

ファイルの位置特定に使用できる URI を返します。

使用例

// このエントリーの URI を取得
var uri = entry.toURI();
console.log(uri);

remove

ファイルを削除します。

パラメーター:

使用例

function success(entry) {
    console.log("削除成功");
}

function fail(error) {
    alert('ファイルの削除に失敗しました: ' + error.code);
}

// ファイルの削除
entry.remove(success, fail);

getParent

そのファイルの親 DirectoryEntry を取得します。

パラメーター:

使用例

function success(parent) {
    console.log("親ディレクトリの名前: " + parent.name);
}

function fail(error) {
    alert(error.code);
}

// 親 DirectoryEntry を取得
entry.getParent(success, fail);

createWriter

FileEntry の表すファイルに使われる FileWriter オブジェクトを作成します。

パラメーター:

使用例

function success(writer) {
    writer.write("ファイルに書き込むテキスト");
}

function fail(error) {
    alert(error.code);
}

// ファイルへの書き込みのための FileWriter を作成
entry.createWriter(success, fail);

file

FileEntry の表すファイルの現在の状態を表す File オブジェクトを返します。

パラメーター:

使用例

function success(file) {
    console.log("File サイズ: " + file.size);
}

function fail(error) {
    alert("ファイルのプロパティーを取得できませんでした: " + error.code);
}

// ファイルのプロパティーを取得
entry.file(success, fail);

DirectoryEntry

このオブジェクトはファイルシステムのディレクトリを表します。これは W3C Directories and Systems の仕様書で定義されています。

プロパティー

注意: 以下の属性は W3C の仕様書によって定義されていますが、 Cordova では サポートされていません :

メソッド

以下のメソッドは DirectoryEntry オブジェクトから呼び出すことができます:

サポートされているプラットフォーム

getMetadata

ディレクトリのメタデータを取得します。

パラメーター:

使用例

function success(metadata) {
    console.log("最終更新日: " + metadata.modificationTime);
}

function fail(error) {
    alert(error.code);
}

// このエントリーの Metadata オブジェクトを取得
entry.getMetadata(success, fail);

moveTo

ディレクトリを、ファイルシステム内の別の場所に移動します。 以下のことを試みるとエラーが発生します:

ディレクトリをすでに存在するディレクトリの場所に移動する行為は、削除してディレクトリを置き換える行為となります。

パラメーター:

使用例

function success(entry) {
    console.log("新しいパス: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function moveDir(entry) {
    var parent = document.getElementById('parent').value,
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // ディレクトリを新しいディレクトリに移動し、名前付け替えます
    entry.moveTo(parentEntry, newName, success, fail);
}

copyTo

ディレクトリを、ファイルシステム内の別の場所にコピーします 以下のことを試みるとエラーが発生します:

ディレクトリーのコピーは常に再帰的で、ディレクトリ内の全ての中身がコピーされます。

パラメーター:

使用例

function win(entry) {
    console.log("新しいパス: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function copyDir(entry) {
    var parent = document.getElementById('parent').value,
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // ディレクトリを新しいディレクトリにコピーし、名前付け替えます
    entry.copyTo(parentEntry, newName, success, fail);
}

toURI

ディレクトリの位置特定に使用できる URI を返します。

使用例

// ディレクトリ URI の取得
var uri = entry.toURI();
console.log(uri);

remove

ディレクトリを削除します。 以下のことを試みるとエラーが発生します:

パラメーター:

使用例

function success(entry) {
    console.log("削除成功");
}

function fail(error) {
    alert('ディレクトリの削除中にエラーが発生しました: ' + error.code);
}

// ディレクトリを削除
entry.remove(success, fail);

getParent

そのディレクトリの親 DirectoryEntry を取得します。

パラメーター:

使用例

function success(parent) {
    console.log("親ディレクトリの名前: " + parent.name);
}

function fail(error) {
    alert('親ディレクトリの取得中にエラーが発生しました: ' + error.code);
}

// 親 DirectoryEntry を取得
entry.getParent(success, fail);

createReader

ディレクトリのエントリを読み込みするための DirectoryReader を作成します。

使用例

// directory reader の作成
var directoryReader = entry.createReader();

getDirectory

ディレクトリを取得または作成します。 以下のことを試みるとエラーが発生します:

パラメーター:

使用例

function success(parent) {
    console.log("親ディレクトリの名前: " + parent.name);
}

function fail(error) {
    alert("新しいディレクトリの作成中にエラーが発生しました: " + error.code);
}

// 既存のディレクトリを取得。存在しない場合は作成
entry.getDirectory("newDir", {create: true, exclusive: false}, success, fail);

getFile

ファイルを取得または作成します。 以下のことを試みるとエラーが発生します:

パラメーター:

使用例

function success(parent) {
    console.log("親ディレクトリの名前: " + parent.name);
}

function fail(error) {
    alert("ファイルの取得中にエラーが発生しました: " + error.code);
}

// 既存のファイルを取得。存在しない場合は作成
entry.getFile("newFile.txt", {create: true, exclusive: false}, success, fail);

removeRecursively

ディレクトリと、その中身をすべて削除します。 エラーが起きたとき (例: 削除できないファイルが含まれるディレクトリを削除しようとした場合) ディレクトリのコンテンツのいくつかは削除されている場合があります。 以下のことを試みるとエラーが発生します:

パラメーター:

使用例

function success(parent) {
    console.log("再帰的な削除成功");
}

function fail(error) {
    alert("ディレクトリまたはディレクトリの中身の削除中にエラーが発生しました: " + error.code);
}

// ディレクトリとディレクトリの中身を削除
entry.removeRecursively(success, fail);

DirectoryReader

ディレクトリの中のファイルとディレクトリをリストアップするオブジェクトです。これは W3C Directories and Systems の仕様書で定義されています。

メソッド

サポートされているプラットフォーム

readEntries

このディレクトリの中のエントリを読み込みます。

パラメーター:

使用例

function success(entries) {
    var i;
    for (i=0; i<entries.length; i++) {
        console.log(entries[i].name);
    }
}

function fail(error) {
    alert("コンテンツのリストアップ中にエラーが発生しました: " + error.code);
}

// directory readerの取得
var directoryReader = dirEntry.createReader();

// ディレクトリの中のすべてのエントリのリストを取得
directoryReader.readEntries(success,fail);

FileTransfer

FileTransfer オブジェクトはファイルをサーバーにアップロードまたはサーバからダウンロードする際に使用します。

プロパティー

なし

メソッド

詳細

FileTransfer オブジェクトは HTTP マルチパート POST リクエストを使ってファイルをサーバーにアップロードする機能を提供します。このメソッドは HTTP と HTTPS の両方のプロトコルをサポートします。 upload メソッドに FileUploadOptions オブジェクトを渡すことで、任意のパラメーターを追加できます。アップロードが成功した場合 FileUploadResult オブジェクトとともに success コールバック関数が呼ばれます。エラーが発生した場合は FileTransferError オブジェクトとともに error コールバック関数が呼ばれます。 また、サーバーからファイルをダウンロードし保存することもできます (iOS と Android のみ) 。

サポートされているプラットフォーム

upload

パラメーター:

使用例

// !! fileURI の値は有効なデバイス内の有効なテキストファイルの URI であるとみなします

var win = function(r) {
    console.log("コード = " + r.responseCode);
    console.log("結果 = " + r.response);
    console.log("送信バイト数 = " + r.bytesSent);
}

var fail = function(error) {
    alert("エラーが発生しました: Code = " + error.code);
    console.log("upload error source " + error.source);
    console.log("upload error target " + error.target);
}

var options = new FileUploadOptions();
options.fileKey="file";
options.fileName=fileURI.substr(fileURI.lastIndexOf('/')+1);
options.mimeType="text/plain";

var params = new Object();
params.value1 = "test";
params.value2 = "param";

options.params = params;

var ft = new FileTransfer();
ft.upload(fileURI, "http://some.server.com/upload.php", win, fail, options);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>File Transfer の使用例</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.7.0.js"></script>
    <script type="text/javascript" charset="utf-8">

        // Cordova の読み込み完了まで待機
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // Cordova 準備完了
        //
        function onDeviceReady() {

            // 写真をファイル URI として取得する場合
            navigator.camera.getPicture(uploadPhoto,
                                        function(message) { alert('写真の取得に失敗しました'); },
                                        { quality: 50,
                                        destinationType: navigator.camera.DestinationType.FILE_URI,
                                        sourceType: navigator.camera.PictureSourceType.PHOTOLIBRARY }
                                        );

        }

        function uploadPhoto(imageURI) {
            var options = new FileUploadOptions();
            options.fileKey="file";
            options.fileName=imageURI.substr(imageURI.lastIndexOf('/')+1);
            options.mimeType="image/jpeg";

            var params = new Object();
            params.value1 = "test";
            params.value2 = "param";

            options.params = params;

            var ft = new FileTransfer();
            ft.upload(imageURI, "http://some.server.com/upload.php", win, fail, options);
        }

        function win(r) {
            console.log("コード = " + r.responseCode);
            console.log("結果 = " + r.response);
            console.log("送信バイト数 = " + r.bytesSent);
        }

        function fail(error) {
            alert("エラーが発生しました: Code = " + error.code);
            console.log("upload error source " + error.source);
            console.log("upload error target " + error.target);
        }

     </script>
   </head>
   <body>
     <h1>使用例</h1>
     <p>ファイルアップロード</p>
   </body>
</html>

download

パラメーター:

使用例

// !! url はサーバー内の有効なファイルを指すことと filePath がデバイス内の有効な値であるとみなします

var fileTransfer = new FileTransfer();

fileTransfer.download(
    url,
    filePath,
    function(entry) {
        console.log("ダウンロード完了: " + entry.fullPath);
    },
    function(error) {
        console.log("download error source " + error.source);
        console.log("download error target " + error.target);
        console.log("upload error code" + error.code);
    }
);

FileUploadOptions

FileUploadOptions オブジェクトは upload メソッドを実行する際に FileTransfer オブジェクトに渡して、追加のパラメーターとして設定する場合に使用します。

プロパティー

概要

FileUploadOptions オブジェクトは upload メソッドを実行する際に FileTransfer オブジェクトに渡して、追加のパラメーターとして設定する場合に使用します。

iOS に関する注意点

WP7 に関する注意点

FileUploadResult

FileUploadResult オブジェクトは、 FileTransfer の upload メソッドの呼び出しが成功した時に、成功コールバック関数に渡されるオブジェクトです。

プロパティー

概要

FileUploadResult オブジェクトは、 FileTransfer の upload メソッドの呼び出しが成功した時に、成功コールバック関数に渡されるオブジェクトです。

iOS に関する注意点

Flags

このオブジェクトは、 DirectoryEntry の getFile メソッドと getDirectory メソッド (ファイルやディレクトリを取得または作成するメソッド) に渡される引数として使われます。

プロパティー

サポートされているプラットフォーム

使用例

// data ディレクトリを取得します。もし存在しない場合は、作成します
dataDir = fileSystem.root.getDirectory("data", {create: true});

// lockfile.txt ファイルを、存在しない場合のみ作成します
lockFile = dataDir.getFile("lockfile.txt", {create: true, exclusive: true});

LocalFileSystem

このオブジェクトは、ファイルシステムのルートの取得方法を提供します。

メソッド

定数

詳細

LocalFileSystem オブジェクトのメソッドは window オブジェクトに定義されています。

サポートされているプラットフォーム

Request File Systemの使用例

function onSuccess(fileSystem) {
    console.log(fileSystem.name);
}

// ファイルシステムをリクエスト
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, onError);

Resolve Local File System URIの使用例

function onSuccess(fileEntry) {
    console.log(fileEntry.name);
}

window.resolveLocalFileSystemURI("file:///example.txt", onSuccess, onError);

詳細な使用例

<!DOCTYPE html>
<html>
  <head>
    <title>Local File System の使用例</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.7.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Cordova の読み込み完了まで待機
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova 準備完了
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onFileSystemSuccess, fail);
        window.resolveLocalFileSystemURI("file:///example.txt", onResolveSuccess, fail);
    }

    function onFileSystemSuccess(fileSystem) {
        console.log(fileSystem.name);
    }

    function onResolveSuccess(fileEntry) {
        console.log(fileEntry.name);
    }

    function fail(evt) {
        console.log(evt.target.error.code);
    }

    </script>
  </head>
  <body>
    <h1>使用例</h1>
    <p>Local File System</p>
  </body>
</html>

Metadata

ファイルやディレクトリの状態を提供します。

プロパティー

詳細

Metadata オブジェクトは、ファイルやディレクトリの状態を表します。 DirectoryEntry または FileEntry の getMetadata メソッドを呼び出すことで、 Metadata オブジェクトが取得できます。

サポートされているプラットフォーム

使用例

function win(metadata) {
    console.log("最終更新日: " + metadata.modificationTime);
}

// このエントリーの Metadata オブジェクトを取得
entry.getMetadata(win, null);

FileError

FileError オブジェクトはエラーが発生した際に File API のメソッドに渡されます。

プロパティー

定数

概要

FileError オブジェクトは File API のあらゆるエラーコールバック関数への唯一のパラメーターです。開発者はエラーのタイプを特定するために、 code プロパティーを確認する必要があります。

FileTransferError

FileTransferError オブジェクトは、エラーが発生したときエラーコールバック関数に渡されます。

プロパティー

定数

概要

FileTransferError オブジェクトは、ファイルアップロード時にエラーが発生したときエラーコールバック関数に渡されます。