ucare/
conversion.rs

1//! Holds all primitives and logic related to file conversion.
2//!
3//! Uploadcare allows converting documents to the following target formats:
4//! DOC, DOCX, XLS, XLSX, ODT, ODS, RTF, TXT, PDF, JPG, PNG.
5
6use std::collections::HashMap;
7use std::fmt::Debug;
8
9use reqwest::Method;
10use serde::{self, Deserialize, Serialize};
11
12use crate::ucare::{encode_json, rest::Client, Result};
13
14/// Service is used to make calls to conversion API.
15pub struct Service<'a> {
16    client: &'a Client,
17}
18
19/// creates an instance of the conversion service
20pub fn new_svc(client: &Client) -> Service {
21    Service { client }
22}
23
24impl Service<'_> {
25    /// Starts document conversion job
26    pub fn document(&self, params: JobParams) -> Result<JobResult> {
27        let json = encode_json(&params)?;
28        self.client.call::<String, Vec<u8>, JobResult>(
29            Method::POST,
30            format!("/convert/document/"),
31            None,
32            Some(json),
33        )
34    }
35
36    /// Gets document conversion job status
37    pub fn document_status(&self, token: i32) -> Result<StatusResult> {
38        self.client.call::<String, String, StatusResult>(
39            Method::GET,
40            format!("/convert/document/status/{}/", token),
41            None,
42            None,
43        )
44    }
45
46    /// Starts video conversion job
47    pub fn video(&self, params: JobParams) -> Result<JobResult> {
48        let json = encode_json(&params)?;
49        self.client.call::<String, Vec<u8>, JobResult>(
50            Method::POST,
51            format!("/convert/video"),
52            None,
53            Some(json),
54        )
55    }
56
57    /// Gets video conversion job status
58    pub fn video_status(&self, token: i32) -> Result<StatusResult> {
59        self.client.call::<String, String, StatusResult>(
60            Method::POST,
61            format!("convert/video/status/{}/", token),
62            None,
63            None,
64        )
65    }
66}
67
68/// Conversion job params
69#[derive(Debug, Serialize)]
70pub struct JobParams {
71    /// paths is an array of IDs (UUIDs) of your source documents to convert
72    /// together with the specified target format.
73    /// Here is how it should be specified:
74    ///   :uuid/document/-/format/:target-format/
75    ///
76    /// You can also provide a complete CDN URL. It can then be used as an
77    /// alias to your converted file ID (UUID):
78    ///   https://ucarecdn.com/:uuid/document/-/format/:target-format/
79    ///
80    /// :uuid identifies the source file you want to convert, it should be
81    /// followed by /document/, otherwise, your request will return an error.
82    /// /-/ is a necessary delimiter that helps our API tell file identifiers
83    /// from processing operations.
84    ///
85    /// The following operations are available during conversion:
86    ///   /format/:target-format/ defines the target format you want a source
87    /// file converted to. The supported values for :target-format are: doc,
88    /// docx, xls, xlsx, odt, ods, rtf, txt, pdf (default), jpg, png. In case
89    /// the /format/ operation was not found, your input document will be
90    /// converted to pdf. Note, when converting multi-page documents to image
91    /// formats (jpg or png), your output will be a zip archive holding a
92    /// number of images corresponding to the input page count.
93    ///   /page/:number/ converts a single page of a multi-paged document to
94    /// either jpg or png. The method will not work for any other target
95    /// formats. :number stands for the one-based number of a page to convert.
96    pub paths: Vec<String>,
97    /// Flag indicating if we should store your outputs.
98    pub store: Option<ToStore>,
99}
100
101/// MUST be either true or false
102#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize)]
103pub enum ToStore {
104    /// True
105    #[serde(rename = "true")]
106    True,
107    /// False
108    #[serde(rename = "false")]
109    False,
110}
111
112/// Conversion job request result
113#[derive(Debug, Deserialize)]
114pub struct JobResult {
115    /// Problems related to your processing job, if any. Key is the path you requested.
116    pub problems: Option<HashMap<String, String>>,
117    /// Result for each requested path, in case of no errors for that path.
118    pub result: Option<Vec<JobInfo>>,
119}
120
121/// Conversion job info
122#[derive(Debug, Deserialize)]
123pub struct JobInfo {
124    /// UUID of your converted document
125    pub uuid: String,
126    /// UUID of a file group with thumbnails for an output video,
127    /// based on the `thumbs` operation parameters
128    pub thumbnails_group_id: Option<String>,
129    /// Source file identifier including a target format, if present
130    pub original_source: Option<String>,
131    /// Conversion job token that can be used to get a job status
132    pub token: Option<i32>,
133}
134
135/// Conversion job status request result
136#[derive(Debug, Deserialize)]
137pub struct StatusResult {
138    /// Status holds conversion job status, can be one of the following:
139    /// pending    — a source file is being prepared for conversion.
140    /// processing — conversion is in progress.
141    /// finished   — the conversion is finished.
142    /// failed     — we failed to convert the source, see error for details.
143    /// canceled   — the conversion was canceled.
144    pub status: String,
145    /// Conversion error if we were unable to handle your file
146    pub error: Option<String>,
147    /// Result repeats the contents of your processing output
148    pub result: JobInfo,
149}
ucare/conversion.rs

ucare/
conversion.rs
