DirectoryEntry

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

プロパティー

• isFile: 常に false を表します (boolean)
• isDirectory: 常に true を表します (boolean)
• name: パスを除いた DirectoryEntry の名前を表します (DOMString)
• fullPath: ルートから DirectoryEntry への絶対パスを表します (DOMString)

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

• filesystem: DirectoryEntry が属するファイルシステムを表します (FileSystem)

メソッド

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

• getMetadata: ディレクトリのメタデータを取得します
• setMetadata: ディレクトリのメタデータをセットします
• moveTo: ディレクトリを、ファイルシステム内の別の場所に移動します
• copyTo: ディレクトリを、ファイルシステム内の別の場所にコピーします
• toURL: ディレクトリの位置特定に使用できる URL を返します
• remove: ディレクトリを削除します。ディレクトリは空である必要があります
• getParent: 親ディレクトリを取得します
• createReader: ディレクトリからエントリを読み込みできる DirectoryReader を作成します
• getDirectory: ディレクトリを取得または作成します
• getFile: ファイルを取得または作成します
• removeRecursively: ディレクトリと、その中身をすべて削除します

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

• Android
• BlackBerry WebWorks (OS 5.0 以上)
• iOS
• Windows Phone 7 (Mango)

getMetadata

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

パラメーター:

• successCallback - Metadata オブジェクトを伴って呼び出されるコールバック関数を表します (Function)
• errorCallback - Metadata の取得時にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

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

setMetadata

ディレクトリのメタデータをセットします。 現在 iOS のみ対応しています - ディレクトリの拡張属性をセットします。

パラメーター:

• successCallback - Metadata が正常にセットされたときに呼び出されるコールバック関数を表します (Function)
• errorCallback - Metadata のセット時にエラーが起きた場合に呼び出されるコールバック関数を表します (Function)
• metadataObject - Metadata のキーと値が格納されているオブジェクトを表します (Object)

使用例

function success() {
    console.log("メタデータが正常にセットされました。");
}

function fail() {
    alert("メタデータ作成中にエラーが発生しました。");
}

// メタデータをセット
entry.setMetadata(success, fail, { "com.apple.MobileBackup": 1});

iOS に関する注意点

• "com.apple.MobileBackup" 拡張属性のみサポートされています。値を 1 とセットすることで、ディレクトリを iCloud でバックアップされない設定とします。値を 0 とセットすることで、再度ディレクトリを iCloud でバックアップされる設定とします。

moveTo

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

• ディレクトリをそれ自体、またはその子ディレクトリに移動する場合
• もし移動先親ディレクトリが移動元と同じで、移動先ディレクトリ名も移動元と同じである場合
• もし移動先のディレクトリ名がファイルである場合
• もし移動先のディレクトリが空でないディレクトリである場合

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

パラメーター:

• parent - ディレクトリの移動先の親ディレクトリを表します (DirectoryEntry)
• newName - ディレクトリの新しい名前を表します。 もし指定されていない場合は、デフォルトで現在の名前となります (DOMString)
• successCallback - 新しいディレクトリの DirectoryEntry を伴って呼び出されるコールバック関数を表します (Function)
• errorCallback - ディレクトリの移動中にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

function moveDir(entry) {
    var parent = document.getElementById('parent').value,
        parentName = parent.substring(parent.lastIndexOf('/')+1),
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry(parentName, parent);

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

copyTo

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

• ディレクトリをそれ自体、またはその子ディレクトリにコピーする場合
• もしコピー先親ディレクトリがコピー元と同じで、コピー先ディレクトリ名もコピー元と同じである場合

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

パラメーター:

• parent - ディレクトリのコピー先の親ディレクトリを表します (DirectoryEntry)
• newName - ディレクトリの新しい名前を表します。 もし指定されていない場合は、デフォルトで現在の名前となります (DOMString)
• successCallback - 新しいディレクトリの DirectoryEntry を伴って呼び出されるコールバック関数を表します (Function)
• errorCallback - ディレクトリのコピー中にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

function copyDir(entry) {
    var parent = document.getElementById('parent').value,
        parentName = parent.substring(parent.lastIndexOf('/')+1),
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry(parentName, parent);

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

toURL

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

使用例

// ディレクトリ URL の取得
var dirURL = entry.toURL();
console.log(dirURL);

remove

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

• 空でないディレクトリを削除する場合
• ファイルシステムのルートディレクトリを削除する場合

パラメーター:

• successCallback - ディレクトリが削除されたときに呼び出されるコールバック関数を表します。パラメーターなしで呼び出されます (Function)
• errorCallback - ディレクトリのコピー中にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

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

getParent

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

パラメーター:

• successCallback - ディレクトリの親 DirectoryEntry を伴って呼び出されるコールバック関数を表します (Function)
• errorCallback - ファイルの親 DirectoryEntry の取得中にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

• 親ディレクトリが存在しないディレクトリを作る場合

パラメーター:

• path - 取得または作成したいディレクトリまでのパスを表します。 この DirectoryEntry からの絶対パスまたは相対パスを指定します (DOMString)
• options - もしディレクトリが存在しない場合、作成するかどうかを指定するオプションを表します (Flags)
• successCallback - DirectoryEntry を伴って呼び出されるコールバック関数を表します (Function)
• errorCallback - ディレクトリの取得または作成中にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

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

getFile

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

• 親ディレクトリが存在しないファイルを作る場合

パラメーター:

• path - 取得または作成したいファイルまでのパスを表します。 この DirectoryEntry からの絶対パスまたは相対パスを指定します (DOMString)
• options - もしファイルが存在しない場合、作成するかどうかを指定するオプションを表します (Flags)
• successCallback - FileEntry を伴って呼び出されるコールバック関数を表します (Function)
• errorCallback - ファイルの取得または作成中にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

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

removeRecursively

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

• ファイルシステムのルートディレクトリを削除する場合

パラメーター:

• successCallback - DirectoryEntry が削除されたときに呼び出されるコールバック関数を表します。 パラメーターなしで呼び出されます (Function)
• errorCallback - DirectoryEntry の削除中にエラーが起きた場合に呼び出されるコールバック関数を表します。 FileError オブジェクトを伴って呼び出されます (Function)

使用例

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

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

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