`OctoPrintClient.files`

OctoPrintClient.files.get(location, filename, opts)

Retrieves information about the file filename at location.

See Retrieve a specific file’s information for more details.

Arguments:

location (string()) – The location of the file
filename (string()) – The name of the file
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.list(recursively, opts)

Retrieves a list of all files from the server.

The response from the server will be preprocessed such that all contained entries (recursively) will be guaranteed to have a parent, size and date property set at least with a value of undefined.

For folders, all children will have their parent property set to the folder entry.

Example:

var recursivelyPrintNames = function(entry, depth) {
    depth = depth || 0;

    var isFolder = entry.type == "folder";
    var name = (isFolder ? "+ " + entry.name : entry.name);
    console.log(_.repeat("| ", depth - 1) + (depth ? "|-" : "") + name);

    if (isFolder) {
        _.each(entry.children, function(child) {
            recursivelyPrintNames(child, depth + 1);
        });
    }
};

OctoPrint.files.list(true)
    .done(function(response) {
        console.log("### Files:");
        _.each(response.files, function(entry) {
            recursivelyPrintNames(entry);
        });
    });

See Retrieve all files for more details.

Arguments:

recursively (boolean()) – Whether to list the files recursively (including all sub folders, true) or not (false, default)
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.listForLocation(location, recursively, opts)

Retrieves a list of all files stored at the specified location from the server.

The response from the server will be preprocessed such that all contained entries (recursively) will be guaranteed to have a parent, size and date property set at least with a value of undefined.

For folders, all children will have their parent property set to the folder entry.

See Retrieve files from specific location for more details.

Arguments:

location (string()) – The location for which to retrieve the list
recursively (boolean()) – Whether to list the files recursively (including all sub folders, true) or not (false, default)
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.select(location, path, print, opts)

Selects a file at location named filename for printing. If print is supplied and truthy, also starts printing the file immediately.

See the select command in Issue a file command for more details.

Arguments:

location (string()) – The location of the file to select
path (string()) – The name of the file to select
print (boolean()) – Whether to print the file after selection (true) or not (false, default)
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.slice(location, path, parameters, opts)

Slices a file at location called filename, using the supplied slice command parameters.

See the slice command in Issue a file command for more details.

Arguments:

location (string()) – The location of the file to slice
path (string()) – The path of the file to slice
parameters (object()) – Additional parameters for the slice command
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.delete(location, path, opts)

Deletes the file or folder at location and path.

See Delete file for more details.

Arguments:

location (string()) – The location of the file to delete
path (string()) – The path of the file to delete
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.copy(location, path, destination, opts)

Copies file or folder path on location to new parent folder destination on location.

destination must already exist.

Example:

OctoPrint.files.copy("local", "some/file.gco", "other/folder");

See Issue a file command for more details.

Arguments:

location (string()) – The location of the file to copy, currently only “local” is supported
path (string()) – The path of the file or folder to copy
destination (string()) – The path of the parent to which to copy the file or folder
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.move(location, filename, destination, opts)

Moves file or folder path on location to new parent folder destination on location.

destination must already exist.

Example:

OctoPrint.files.move("local", "some/file.gco", "other/folder");

See Issue a file command for more details.

Arguments:

location (string()) – The location of the file to move, currently only “local” is supported
path (string()) – The path of the file or folder to move
destination (string()) – The path of the parent to which to copy the file or folder
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.createFolder(location, name, path, opts)

Creates a new folder name on location. If path is provided and not empty the folder will be created as a new child of it.

Example:

// creates new folder "folder" in the root of "local"
OctoPrint.files.createFolder("local", "folder");

// creates new folder "subfolder" in parent "some/existing/folder" on "local"
OctoPrint.files.createFolder("local", "subfolder", "some/existing/folder");

See Upload file or create folder for more details on the folder creation API.

Arguments:

location (string()) – The location to create the folder on (currently only “local” is supported)
name (string()) – The name of the new folder
path (string()) – The path to the parent folder in which to create the new folder. May be left unset in which case the folder will be created in the root directory of location.
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.upload(location, file, data)

Uploads a file to the specified location.

Additional command data may be provided. Supported properties are:

filename: A string value, the filename to assign to the uploaded file. Optional, if not provided the filename will be taken from the provided file object’s name property.
select: A boolean value, specifies whether to immediately select the uploaded file for printing once the upload completes (true) or not (false, default)
print: A boolean value, specifies whether to immediately start printing the file after the upload completes (true) or not (false, default)
userdata: An optional object or a serialized JSON string of additional user supplied data to associate with the uploaded file.

See Upload file or create folder for more details on the file upload API and OctoPrint.upload() for more details on the underlying library upload mechanism, including what values are accepted for the file parameter.

Arguments:

location (string()) – The location to upload the file to
file (object or string()) – The file to upload, see OctoPrint.upload() for more details

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.download(location, path, opts)

Downloads the file at path in location.

The downloaded file will be returned as response body in the completed Promise. Note that not all locations support downloading of files (sdcard for example doesn’t).

Example:

OctoPrint.files.download("local", "somefile.gco")
    .done(function(response) {
        var contents = response;
        // do something with the file contents
    });

Arguments:

location (string()) – The location of the file to download
path (string()) – The path of the file to download
opts (object()) – Additional options for the request

Returns Promise:

A jQuery Promise for the request’s response

OctoPrintClient.files.pathForEntry(entry)

Utility function to retrieve the path within its location for a given entry.

Use this if you already have a full list of entries and need the path to one.

Example

OctoPrint.files.listForLocation("local", True)
    .done(function(entries) {
        var entry = OctoPrint.files.entryForPath("some/funny/entry", entries.files);
        var path = OctoPrint.files.pathForEntry(entry);
        console.log(path); // will log some/funny/entry
    });

Arguments:

entry (object()) – The entry object for which to retrieve the path

Returns string:

The path of the entry within its location

OctoPrintClient.files.entryForPath(path, root)

Utility function to retrieve an entry by its path based on an entry tree provided by its root.

Use this if you already have a full list of entries and are looking for a specified entry within.

Example

var somePathsToFind = ["some/funny/entry",
                       "another/entry",
                       "this/does/not/exist"];

OctoPrint.files.listForLocation("local", True)
    .done(function(entries) {
        // will log two entries and one undefined
        _.each(somePathsToFind, function(path) {
            console.log(OctoPrint.files.entryForPath(path, entries.files));
        });
    });

Arguments:

path (string()) – The path of the entry to retrieve
root (object()) – The root of the tree in which to resolve the entry by its path, either a list of entries or an entry element with children

Returns object or undefined:

The retrieved entry, or undefined if the path could not be resolved

OctoPrintClient.files

`OctoPrintClient.files`