# `Magpie.Files`
[🔗](https://github.com/alexcassol/magpie/blob/v0.3.1/lib/magpie/files.ex#L1)

This module contains endpoints and data types
for basic file operations.

# `copy`

Copy a file or folder to a different location in the user's Dropbox.
If the source path is a folder all its contents will be copied.

## Example

  Magpie.Files.copy(client, "/Temp/first", "/Tmp/second")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-copy_v2

# `create_folder`

```elixir
@spec create_folder(Magpie.Client.t(), binary()) :: any()
```

Create folder returns map

## Example

  Magpie.Files.create_folder client, "/Path"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-create_folder

# `create_folder_to_struct`

```elixir
@spec create_folder_to_struct(Magpie.Client.t(), binary()) ::
  {:ok, Magpie.Folder.t()} | {:error, Magpie.Error.t()}
```

Same as `create_folder/2` but returns `{:ok, %Magpie.Folder{}}`.

## Example

  Magpie.Files.create_folder_to_struct client, "/Path"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-create_folder

# `delete_folder`

Delete the file or folder at a given path.
If the path is a folder, all its contents will be deleted too.
A successful response indicates that the file or folder was deleted.
The returned metadata will be the corresponding FileMetadata
or FolderMetadata for the item at time of deletion, and not a DeletedMetadata object.

## Example

   Magpie.Files.delete_folder client, "/Homework/math/Prime_Numbers.txt"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-delete_v2

# `delete_folder_to_struct`

```elixir
@spec delete_folder_to_struct(Magpie.Client.t(), binary()) ::
  {:ok, Magpie.Folder.t()} | {:error, Magpie.Error.t()}
```

Same as `delete_folder/2` but returns `{:ok, %Magpie.Folder{}}`.

## Example

  Magpie.Files.delete_folder_to_struct client, "/Path"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-delete_v2

# `download`

Download a file from a user's Dropbox.

## Example

  Magpie.Files.download client, "/mypdf.pdf"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-download

# `download_zip`

Download a folder from the user's Dropbox as a zip file.

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-download_zip

# `export`

Export a file from the user's Dropbox to a portable format (for files that
cannot be downloaded directly, e.g. Paper docs). `opts` accepts
`"export_format"`.

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-export

# `get_metadata`

Returns the metadata for a file or folder.

## Example

  Magpie.Files.get_metadata client, "/mypdf.pdf"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_metadata

# `get_preview`

Get a preview for a file.

## Example

  Magpie.Files.get_preview client, "/mypdf.pdf"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_preview

# `get_temporary_link`

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. Content-Type of the link is determined automatically by the file's mime type.

## Example

  Magpie.Files.get_temporary_link client, "/video.mp4"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_preview

# `get_temporary_upload_link`

Get a one-time-use temporary upload link for a direct binary upload.
`commit_info` takes the `/files/upload` argument fields, e.g.
`%{"path" => "/a.txt", "mode" => "add"}`; `duration` is in seconds.

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_temporary_upload_link

# `get_thumbnail`

Get a thumbnail for an image.

## Example

  Magpie.Files.get_thumbnail client, "/image.jpg"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_thumbnail

# `get_thumbnail_batch`

Get thumbnails for a list of images. We allow up to 25 thumbnails in a single batch.

## Example
  batch = %{ "path" => "/image.jpg", "format" => "jpeg", "size" => "w64h64"}
  entries = [batch]
  Magpie.Files.get_thumbnail_batch client, entries

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_thumbnail_batch

# `get_thumbnail_v2`

Get a thumbnail for an image or document, addressed by path or shared link.
`resource` is `%{".tag" => "path", "path" => ...}` or
`%{".tag" => "link", "url" => ...}`; `opts` accepts `"format"`, `"size"`
and `"mode"`.

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_thumbnail_v2

# `move`

Move a file or folder to a different location in the user's Dropbox.
If the source path is a folder all its contents will be moved.

## Example

  Magpie.Files.move(client, "/Homework/math", "/Homework/algebra")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-move_v2

# `permanently_delete`

Permanently delete the file or folder at a given path. Requires a Dropbox
Business account with Advanced or Enterprise plan. `opts` accepts
`"parent_rev"`.

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-permanently_delete

# `restore`

Restore a file to a specific revision.

## Example

  Magpie.Files.restore(client, "/root/word.docx", "a1c10ce0dd78")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-restore

# `search`

Searches for files and folders.

`options` accepts the `SearchOptions` fields, e.g.
`%{"path" => "/Photos", "max_results" => 100, "filename_only" => true}`.

## Example

  Magpie.Files.search(client, "word.docx", %{"path" => "/root"})

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-search_v2

# `search_continue`

Fetches the next page of search results returned from `search/3`.

## Example

  Magpie.Files.search_continue(client, cursor)

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-search-continue_v2

# `search_stream`

Returns a lazy `Stream` over **all** search matches, fetching pages
through `search/3` + `search_continue/2` on demand. Raises
`Magpie.Error` if a page request fails.

## Example

    client
    |> Magpie.Files.search_stream("report", %{"path" => "/Work"})
    |> Enum.take(50)

# `upload`

Create a new file with the contents provided in the request.

## Example

  Magpie.Files.upload client, "/mypdf.pdf", "/mypdf.pdf"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-upload

# `upload_file`

Uploads the local file at `local_path` to `path` in the user's Dropbox,
picking the right strategy automatically:

  * files up to `:session_threshold` bytes go through a single
    `/files/upload` call;
  * larger files are streamed through an upload session
    (`start` → `append_v2` × N → `finish`) in chunks of `:chunk_size`
    bytes, without ever loading the whole file into memory.

Returns `{:ok, file_metadata}` on success, `{:error, %Magpie.Error{}}` on
Dropbox errors, or `{:error, posix}` when the local file cannot be read.

## Options

  * `:chunk_size` — upload session chunk size in bytes (default 8 MiB)
  * `:session_threshold` — size above which an upload session is used
    (default 150 MiB, the Dropbox limit for single-request uploads)
  * `:mode` — `"add"` (default) or `"overwrite"`
  * `:autorename` — default `true`
  * `:mute` — default `false`

## Example

    {:ok, metadata} = Magpie.Files.upload_file(client, "/Backup/db.dump", "priv/db.dump")

---

*Consult [api-reference.md](api-reference.md) for complete listing*