OctoPrintClient.files
- OctoPrintClient.files.get(location, filename, opts)
Retrieves information about the file
filename
atlocation
.See Retrieve a specific file’s information for more details.
- Arguments
location (
string()
) – The location of the filefilename (
string()
) – The name of the fileopts (
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
anddate
property set at least with a value ofundefined
.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
anddate
property set at least with a value ofundefined
.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 listrecursively (
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
namedfilename
for printing. Ifprint
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 selectpath (
string()
) – The name of the file to selectprint (
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
calledfilename
, using the supplied slice commandparameters
.See the
slice
command in Issue a file command for more details.- Arguments
location (
string()
) – The location of the file to slicepath (
string()
) – The path of the file to sliceparameters (
object()
) – Additional parameters for theslice
commandopts (
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
andpath
.See Delete file for more details.
- Arguments
location (
string()
) – The location of the file to deletepath (
string()
) – The path of the file to deleteopts (
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
onlocation
to new parent folderdestination
onlocation
.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 supportedpath (
string()
) – The path of the file or folder to copydestination (
string()
) – The path of the parent to which to copy the file or folderopts (
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
onlocation
to new parent folderdestination
onlocation
.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 supportedpath (
string()
) – The path of the file or folder to movedestination (
string()
) – The path of the parent to which to copy the file or folderopts (
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
onlocation
. Ifpath
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 folderpath (
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 oflocation
.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 specifiedlocation
.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’sname
property.- select
A boolean value, specifies whether to immediately select the uploaded file for printing once the upload completes (true) or not (false, default)
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 thefile
parameter.- Arguments
location (
string()
) – The location to upload the file tofile (
object or string()
) – The file to upload, seeOctoPrint.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
inlocation
.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 downloadpath (
string()
) – The path of the file to downloadopts (
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 itsroot
.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 retrieveroot (
object()
) – The root of the tree in which to resolve the entry by its path, either a list of entries or an entry element withchildren
- Returns object or undefined
The retrieved entry, or
undefined
if thepath
could not be resolved