UNPKG

7.02 kBTypeScriptView Raw
1import { IonicNativePlugin } from '@ionic-native/core';
2export interface FileUploadOptions {
3 /**
4 * The name of the form element.
5 * Defaults to 'file'.
6 */
7 fileKey?: string;
8 /**
9 * The file name to use when saving the file on the server.
10 * Defaults to 'image.jpg'.
11 */
12 fileName?: string;
13 /**
14 * The HTTP method to use - either PUT or POST.
15 * Defaults to POST.
16 */
17 httpMethod?: string;
18 /**
19 * The mime type of the data to upload.
20 * Defaults to image/jpeg.
21 */
22 mimeType?: string;
23 /**
24 * A set of optional key/value pairs to pass in the HTTP request.
25 */
26 params?: {
27 [s: string]: any;
28 };
29 /**
30 * Whether to upload the data in chunked streaming mode.
31 * Defaults to true.
32 */
33 chunkedMode?: boolean;
34 /**
35 * A map of header name/header values. Use an array to specify more
36 * than one value. On iOS, FireOS, and Android, if a header named
37 * Content-Type is present, multipart form data will NOT be used.
38 */
39 headers?: {
40 [s: string]: any;
41 };
42}
43export interface FileUploadResult {
44 /**
45 * The number of bytes sent to the server as part of the upload.
46 */
47 bytesSent: number;
48 /**
49 * The HTTP response code returned by the server.
50 */
51 responseCode: number;
52 /**
53 * The HTTP response returned by the server.
54 */
55 response: string;
56 /**
57 * The HTTP response headers by the server.
58 */
59 headers: {
60 [s: string]: any;
61 };
62}
63export interface FileTransferError {
64 /**
65 * One of the predefined error codes listed below.
66 */
67 code: number;
68 /**
69 * URL to the source.
70 */
71 source: string;
72 /**
73 * URL to the target.
74 */
75 target: string;
76 /**
77 * HTTP status code. This attribute is only available when a response
78 * code is received from the HTTP connection.
79 */
80 http_status: number;
81 /**
82 * Response body. This attribute is only available when a response is received from the HTTP connection.
83 */
84 body: string;
85 /**
86 * Either e.getMessage or e.toString.
87 */
88 exception: string;
89}
90/**
91 * @name File Transfer
92 *
93 * @description
94 * This plugin allows you to upload and download files.
95 *
96 * @usage
97 * ```typescript
98 * import { FileTransfer, FileUploadOptions, FileTransferObject } from '@ionic-native/file-transfer/ngx';
99 * import { File } from '@ionic-native/file';
100 *
101 * constructor(private transfer: FileTransfer, private file: File) { }
102 *
103 * ...
104 *
105 * const fileTransfer: FileTransferObject = this.transfer.create();
106 *
107 * // Upload a file:
108 * fileTransfer.upload(..).then(..).catch(..);
109 *
110 * // Download a file:
111 * fileTransfer.download(..).then(..).catch(..);
112 *
113 * // Abort active transfer:
114 * fileTransfer.abort();
115 *
116 * // full example
117 * upload() {
118 * let options: FileUploadOptions = {
119 * fileKey: 'file',
120 * fileName: 'name.jpg',
121 * headers: {}
122 * .....
123 * }
124 *
125 * fileTransfer.upload('<file path>', '<api endpoint>', options)
126 * .then((data) => {
127 * // success
128 * }, (err) => {
129 * // error
130 * })
131 * }
132 *
133 * download() {
134 * const url = 'http://www.example.com/file.pdf';
135 * fileTransfer.download(url, this.file.dataDirectory + 'file.pdf').then((entry) => {
136 * console.log('download complete: ' + entry.toURL());
137 * }, (error) => {
138 * // handle error
139 * });
140 * }
141 *
142 * ```
143 *
144 * To store files in a different/publicly accessible directory, please refer to the following link
145 * https://github.com/apache/cordova-plugin-file#where-to-store-files
146 *
147 * @interfaces
148 * FileUploadOptions
149 * FileUploadResult
150 * FileTransferError
151 * @classes
152 * FileTransferObject
153 */
154export declare class FileTransfer extends IonicNativePlugin {
155 /**
156 * Error code rejected from upload with FileTransferError
157 * Defined in FileTransferError.
158 * FILE_NOT_FOUND_ERR: 1 Return when file was not found
159 * INVALID_URL_ERR: 2, Return when url was invalid
160 * CONNECTION_ERR: 3, Return on connection error
161 * ABORT_ERR: 4, Return on aborting
162 * NOT_MODIFIED_ERR: 5 Return on '304 Not Modified' HTTP response
163 * @enum {number}
164 */
165 FileTransferErrorCode: {
166 FILE_NOT_FOUND_ERR: number;
167 INVALID_URL_ERR: number;
168 CONNECTION_ERR: number;
169 ABORT_ERR: number;
170 NOT_MODIFIED_ERR: number;
171 };
172 /**
173 * Creates a new FileTransfer object
174 * @return {FileTransferObject}
175 */
176 create(): FileTransferObject;
177}
178/**
179 * @hidden
180 */
181export declare class FileTransferObject {
182 private _objectInstance;
183 constructor();
184 /**
185 * Sends a file to a server.
186 *
187 * @param {string} fileUrl Filesystem URL representing the file on the device or a data URI. For backwards compatibility, this can also be the full path of the file on the device.
188 * @param {string} url URL of the server to receive the file, as encoded by encodeURI().
189 * @param {FileUploadOptions} [options] Optional parameters.
190 * @param {boolean} [trustAllHosts] Optional parameter, defaults to false. If set to true, it accepts all security certificates. This is useful since Android rejects self-signed security certificates. Not recommended for production use. Supported on Android and iOS.
191 * @returns {Promise<FileUploadResult>} Returns a Promise that resolves to a FileUploadResult and rejects with FileTransferError.
192 */
193 upload(fileUrl: string, url: string, options?: FileUploadOptions, trustAllHosts?: boolean): Promise<FileUploadResult>;
194 /**
195 * Downloads a file from server.
196 *
197 * @param {string} source URL of the server to download the file, as encoded by encodeURI().
198 * @param {string} target Filesystem url representing the file on the device. For backwards compatibility, this can also be the full path of the file on the device.
199 * @param {boolean} [trustAllHosts] Optional parameter, defaults to false. If set to true, it accepts all security certificates. This is useful because Android rejects self-signed security certificates. Not recommended for production use. Supported on Android and iOS.
200 * @param {object} [Optional] parameters, currently only supports headers (such as Authorization (Basic Authentication), etc).
201 * @returns {Promise<any>} Returns a Promise that resolves to a FileEntry object.
202 */
203 download(source: string, target: string, trustAllHosts?: boolean, options?: {
204 [s: string]: any;
205 }): Promise<any>;
206 /**
207 * Registers a listener that gets called whenever a new chunk of data is transferred.
208 * @param {Function} listener Listener that takes a progress event.
209 */
210 onProgress(listener: (event: ProgressEvent) => any): void;
211 /**
212 * Aborts an in-progress transfer. The onerror callback is passed a FileTransferError
213 * object which has an error code of FileTransferError.ABORT_ERR.
214 */
215 abort(): void;
216}