.. _sec-jsclientlib-files: :mod:`OctoPrintClient.files` ---------------------------- .. js:function:: OctoPrintClient.files.get(location, filename, opts) Retrieves information about the file ``filename`` at ``location``. See :ref:`Retrieve a specific file's information ` for more details. :param string location: The location of the file :param string filename: The name of the file :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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:** .. code-block:: javascript 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 :ref:`Retrieve all files ` for more details. :param boolean recursively: Whether to list the files recursively (including all sub folders, true) or not (false, default) :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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 :ref:`Retrieve files from specific location ` for more details. :param string location: The location for which to retrieve the list :param boolean recursively: Whether to list the files recursively (including all sub folders, true) or not (false, default) :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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 :ref:`Issue a file command ` for more details. :param string location: The location of the file to select :param string path: The name of the file to select :param boolean print: Whether to print the file after selection (true) or not (false, default) :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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 :ref:`Issue a file command ` for more details. :param string location: The location of the file to slice :param string path: The path of the file to slice :param object parameters: Additional parameters for the ``slice`` command :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: OctoPrintClient.files.delete(location, path, opts) Deletes the file or folder at ``location`` and ``path``. See :ref:`Delete file ` for more details. :param string location: The location of the file to delete :param string path: The path of the file to delete :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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:** .. code-block:: javascript OctoPrint.files.copy("local", "some/file.gco", "other/folder"); See :ref:`Issue a file command ` for more details. :param string location: The location of the file to copy, currently only "local" is supported :param string path: The path of the file or folder to copy :param string destination: The path of the parent to which to copy the file or folder :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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:** .. code-block:: javascript OctoPrint.files.move("local", "some/file.gco", "other/folder"); See :ref:`Issue a file command ` for more details. :param string location: The location of the file to move, currently only "local" is supported :param string path: The path of the file or folder to move :param string destination: The path of the parent to which to copy the file or folder :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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:** .. code-block:: javascript // 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 :ref:`Upload file or create folder ` for more details on the folder creation API. :param string location: The location to create the folder on (currently only "local" is supported) :param string name: The name of the new folder :param string path: 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``. :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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 :ref:`Upload file or create folder ` for more details on the file upload API and :js:func:`OctoPrint.upload` for more details on the underlying library upload mechanism, including what values are accepted for the ``file`` parameter. :param string location: The location to upload the file to :param object or string file: The file to upload, see :js:func:`OctoPrint.upload` for more details :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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:** .. code-block:: javascript OctoPrint.files.download("local", "somefile.gco") .done(function(response) { var contents = response; // do something with the file contents }); :param string location: The location of the file to download :param string path: The path of the file to download :param object opts: Additional options for the request :returns Promise: A `jQuery Promise `_ for the request's response .. js:function:: 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** .. code-block:: javascript 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 }); :param object entry: The entry object for which to retrieve the path :returns string: The path of the entry within its location .. js:function:: 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** .. code-block:: javascript 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)); }); }); :param string path: The path of the entry to retrieve :param object root: 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