PhoneGap(Cordova) FileAPI を読む

PhoneGap Cordova

まあ公式ドキュメント嫁

はい

参考

技評の連載。CameraとFileAPIを使ってる::もっと使おうPhoneGap／Cordova 2.0.0｜gihyo.jp … 技術評論社
公式ドキュメント::Apache Cordova API Documentation
現在のバージョンは 2.1.0

とりあえずサンプルコードを熟読する

実際にデバッガ仕込んでどうとかするより基本的に公式ドキュメントを熟読して動作を確認するのが Cordova の場合よさそうというのは前回学んだ。というか JS 部分に debugger 仕込んだりしても weinre でもブレークしてくれないし、地道に console.dir() 相当のことをするのは骨が折れるので、開発で詰まってからそこらへんは調べればいい。
XML でのパーミッションを許可しましょうとかは先にやっておきましょう。

Read

公式のまんまです

// Wait for Cordova to load
//
function onLoad() {
    document.addEventListener("deviceready", onDeviceReady, false);
}

// Cordova is ready
//
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("Read as data URL");
        console.log(evt.target.result);
    };
    reader.readAsDataURL(file);
}

function readAsText(file) {
    var reader = new FileReader();
    reader.onloadend = function(evt) {
        console.log("Read as text");
        console.log(evt.target.result);
    };
    reader.readAsText(file);
}

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

で、引数とかもそのままのかたちで公式ドキュメントに載ってるので適宜見ましょう。という話なのだがまあかいつまんで自分の理解を書いておく。

  • まずは deviceready で Listen しておく
  • window.requestFileSystem メソッドが使えるので LocalFileSystem.PERSISTENT か LocalFileSystem.TEMPORARY で静的な場所か一時的な場所かを選択して成功コールバックと失敗コールバックを登録する。第2引数の 0 についてはなんか載ってないよくわからない
  • fileSystem をとってきたのでそこで fileSystem.root.getFile か getDirectory でファイルオブジェクトをつかめる
    • 引数は path, オプション、成功コールバック、失敗コールバックとなってる。
    • オプションとしては create というのと exclusive というのがとれる。 create は get_object_or_create みたいな感じか。exclusive ってのは create したときに既に存在している場合はなんかつくられるフラグらしい
  • gotFileEntry(サンプルコード) でおそらくファイルの代理(翻訳そのまま)をとってこれる。 fileEntry では各種プロパティでファイルであるか(boolean)、ディレクトリであるか(boolean)、名前などとれたり、ファイルオブジェクトとしての(ちょっとメタ的な？)操作ができる
    • 実際にファイルを read write する場合は file メソッドをつかう。引数は成功コールバックと失敗コールバック
  • new FileReader() でインスタンスを作成(といってもJSだからプロトタイプではあるのだけど)、その reader インスタンスにいろいろイベントが割り当ててある
    • 具体的には onload, onloadend, onabort... など。あるイベントが完全に終わるかまで面倒をみてくれる
    • メソッドとしては readAsDataURL readAsText として中身や data スキームがとれる

write

公式のまんまです

// Wait for Cordova to load
//
document.addEventListener("deviceready", onDeviceReady, false);

// Cordova is ready
//
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("contents of file now 'some sample text'");
        writer.truncate(11);
        writer.onwriteend = function(evt) {
            console.log("contents of file now 'some sample'");
            writer.seek(4);
            writer.write(" different text");
            writer.onwriteend = function(evt){
                console.log("contents of file now 'some different text'");
            }
        };
    };
    writer.write("some sample text");
}

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

最初らへんは共通ですね

  • fileEntry をとってきたときに createWriter メソッドで fileWrite オブジェクトを生成して、そこで実際にファイルの中身を write できるっぽい。
    • ちなみにエンコーディングはデフォルトで UTF-8 になってます
  • createWriter したときの仮引数 write がファイルオブジェクトのインスタンスみたいな感じ。で、この仮引数 write 自体にも read と同じでいろいろイベントやメソッドが生えている
    • 具体的にはイベントは onwritestart, onwrite, onabort, onwriteend... など。各種リクエストがきたときにいろいろイベントを発火させることができるという意味では read と同じ
    • メソッドとしては abort, seek, truncate, write の4つ。まあ主に使うのは write でしょうか。追記するときは seek してからなのかな。そこはまだ調べきれてない

気になったこと

onload と onloadend や onwrite と onwriteend が区別されていること。on...end だとどうもリクエストが完了したということそのもの(request has completed)なので、リクエストが正常に完了した場合は onwrite, onload のようですね

まあ

とりあえず軽く調査した感じだとそれほど複雑ではなさそうですね。あとは適宜使いながらやらないとどうともいえないというか。