diff options
Diffstat (limited to 'plugins/org.apache.cordova.file/docs/fileentry/fileentry.md')
| -rw-r--r-- | plugins/org.apache.cordova.file/docs/fileentry/fileentry.md | 323 |
1 files changed, 0 insertions, 323 deletions
diff --git a/plugins/org.apache.cordova.file/docs/fileentry/fileentry.md b/plugins/org.apache.cordova.file/docs/fileentry/fileentry.md deleted file mode 100644 index f362833c..00000000 --- a/plugins/org.apache.cordova.file/docs/fileentry/fileentry.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -license: Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. ---- - -FileEntry -========== - -Represents a file on a file system, as defined in the -[W3C Directories and Systems](http://www.w3.org/TR/file-system-api/) -specification. - -Properties ----------- - -- __isFile__: Always true. _(boolean)_ -- __isDirectory__: Always false. _(boolean)_ -- __name__: The name of the `FileEntry`, excluding the path leading to it. _(DOMString)_ -- __fullPath__: The full absolute path from the root to the `FileEntry`. _(DOMString)_ - -__NOTE:__ The following attribute is defined by the W3C specification, -but is _not_ supported: - -- __filesystem__: The file system on which the `FileEntry` resides. _(FileSystem)_ - -Methods -------- - -- __getMetadata__: Look up metadata about a file. -- __setMetadata__: Set metadata on a file. -- __moveTo__: Move a file to a different location on the file system. -- __copyTo__: Copy a file to a different location on the file system. -- __toURL__: Return a URL that can be used to locate a file. -- __remove__: Delete a file. -- __getParent__: Look up the parent directory. -- __createWriter__: Creates a `FileWriter` object that can be used to write to a file. -- __file__: Creates a `File` object containing file properties. - -Supported Platforms -------------------- - -- Android -- BlackBerry WebWorks (OS 5.0 and higher) -- iOS -- Windows Phone 7 and 8 -- Windows 8 - -getMetadata ----------------- - -Look up metadata about a file. - -__Parameters:__ - -- __successCallback__: A callback that is passed a `Metadata` object. _(Function)_ -- __errorCallback__: A callback that executes if an error occurs when retrieving the `Metadata`. Invoked with a `FileError` object. _(Function)_ - -__Quick Example__ - - function success(metadata) { - console.log("Last Modified: " + metadata.modificationTime); - } - - function fail(error) { - alert(error.code); - } - - // Request the metadata object for this entry - entry.getMetadata(success, fail); - -setMetadata ----------------- - -Set metadata on a file. - -__Currently works only on iOS.__ -- this will set the extended attributes of a file. - -__Parameters:__ - -- __successCallback__: A callback that executes when the metadata is set. _(Function)_ -- __errorCallback__: A callback that executes when the metadata is not successfully set. _(Function)_ -- __metadataObject__: An object that contains the metadata's keys and values. _(Object)_ - -__Quick Example__ - - function success() { - console.log("The metadata was successfully set."); - } - - function fail() { - alert("There was an error in setting the metadata"); - } - - // Set the metadata - entry.setMetadata(success, fail, { "com.apple.MobileBackup": 1}); - -__iOS Quirk__ - -- Only the `com.apple.MobileBackup` extended attribute is supported. Set the value to `1` to prevent the file from being backed up to iCloud. Set the value to `0` to re-enable the file to be backed up to iCloud. - -__Quick Example__ - - function setFileMetadata(localFileSystem, filePath, metadataKey, metadataValue) - { - var onSetMetadataWin = function() { - console.log("success setting metadata") - } - var onSetMetadataFail = function() { - console.log("error setting metadata") - } - - var onGetFileWin = function(parent) { - var data = {}; - data[metadataKey] = metadataValue; - parent.setMetadata(onSetMetadataWin, onSetMetadataFail, data); - } - var onGetFileFail = function() { - console.log("error getting file") - } - - var onFSWin = function(fileSystem) { - fileSystem.root.getFile(filePath, {create: true, exclusive: false}, onGetFileWin, onGetFileFail); - } - - var onFSFail = function(evt) { - console.log(evt.target.error.code); - } - - window.requestFileSystem(localFileSystem, 0, onFSWin, onFSFail); - } - - setFileMetadata(LocalFileSystem.PERSISTENT, "Backups/sqlite.db", "com.apple.MobileBackup", 1); - -moveTo ------- - -Move a file to a different location on the file system. An error -results if the app attempts to: - -- move a file into its parent if a name different from its current one isn't provided; -- move a file to a path occupied by a directory; - -In addition, moving a file on top of an existing file attempts to -delete and replace that file. - -__Parameters:__ - -- __parent__: The parent directory to which to move the file. _(DirectoryEntry)_ -- __newName__: The new name of the file. Defaults to the current name if unspecified. _(DOMString)_ -- __successCallback__: A callback that is passed the new files `FileEntry` object. _(Function)_ -- __errorCallback__: A callback that executes if an error occurs when attempting to move the file. Invoked with a `FileError` object. _(Function)_ - -__Quick Example__ - - function success(entry) { - console.log("New Path: " + entry.fullPath); - } - - function fail(error) { - alert(error.code); - } - - function moveFile(entry) { - var parent = document.getElementById('parent').value, - parentName = parent.substring(parent.lastIndexOf('/')+1), - parentEntry = new DirectoryEntry(parentName, parent); - - // move the file to a new directory and rename it - entry.moveTo(parentEntry, "newFile.txt", success, fail); - } - -copyTo ------- - -Copy a file to a new location on the file system. An error results if -the app attempts to: - -- copy a file into its parent if a name different from its current one is not provided. - -__Parameters:__ - -- __parent__: The parent directory to which to copy the file. _(DirectoryEntry)_ -- __newName__: The new name of the file. Defaults to the current name if unspecified. _(DOMString)_ -- __successCallback__: A callback that is passed the new file's `FileEntry` object. _(Function)_ -- __errorCallback__: A callback that executes if an error occurs when attempting to copy the file. Invoked with a `FileError` object. _(Function)_ - -__Quick Example__ - - function win(entry) { - console.log("New Path: " + entry.fullPath); - } - - function fail(error) { - alert(error.code); - } - - function copyFile(entry) { - var parent = document.getElementById('parent').value, - parentName = parent.substring(parent.lastIndexOf('/')+1), - parentEntry = new DirectoryEntry(parentName, parent); - - // copy the file to a new directory and rename it - entry.copyTo(parentEntry, "file.copy", success, fail); - } - -toURL ------ - -Returns a URL that can be used to locate the file. - -__Quick Example__ - - // Request the URL for this entry - var fileURL = entry.toURL(); - console.log(fileURL); - -remove ------- - -Deletes a file. - -__Parameters:__ - -- __successCallback__: A callback that executes after the file has been deleted. Invoked with no parameters. _(Function)_ -- __errorCallback__: A callback that executes if an error occurs when attempting to delete the file. Invoked with a `FileError` object. _(Function)_ - -__Quick Example__ - - function success(entry) { - console.log("Removal succeeded"); - } - - function fail(error) { - alert('Error removing file: ' + error.code); - } - - // remove the file - entry.remove(success, fail); - -getParent ---------- - -Look up the parent `DirectoryEntry` containing the file. - -__Parameters:__ - -- __successCallback__: A callback that is passed the file's parent `DirectoryEntry`. _(Function)_ -- __errorCallback__: A callback that executes if an error occurs when attempting to retrieve the parent `DirectoryEntry`. Invoked with a `FileError` object. _(Function)_ - -__Quick Example__ - - function success(parent) { - console.log("Parent Name: " + parent.name); - } - - function fail(error) { - alert(error.code); - } - - // Get the parent DirectoryEntry - entry.getParent(success, fail); - -createWriter ------------- - -Create a `FileWriter` object associated with the file represented by the `FileEntry`. - -__Parameters:__ - -- __successCallback__: A callback that is passed a `FileWriter` object. _(Function)_ -- __errorCallback__: A callback that executes if an error occurs while attempting to create the FileWriter. Invoked with a `FileError` object. _(Function)_ - -__Quick Example__ - - function success(writer) { - writer.write("Some text to the file"); - } - - function fail(error) { - alert(error.code); - } - - // create a FileWriter to write to the file - entry.createWriter(success, fail); - -file ----- - -Return a `File` object that represents the current state of the file -that this `FileEntry` represents. - -__Parameters:__ - -- __successCallback__: A callback that is passed a `File` object. _(Function)_ -- __errorCallback__: A callback that executes if an error occurs when creating the `File` object, such as when the file no longer exists. Invoked with a `FileError` object. _(Function)_ - -__Quick Example__ - - function success(file) { - console.log("File size: " + file.size); - } - - function fail(error) { - alert("Unable to retrieve file properties: " + error.code); - } - - // obtain properties of a file - entry.file(success, fail); |