Browse Source

Update README.md

wkh237 8 years ago
parent
commit
edc2887eab
1 changed files with 51 additions and 16 deletions
  1. 51
    16
      README.md

+ 51
- 16
README.md View File

20
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
20
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
21
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
21
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
22
  * [Upload/Download progress](#user-content-uploaaddownload-progress)
22
  * [Upload/Download progress](#user-content-uploaaddownload-progress)
23
+ * [File access](#user-content-file-access)
23
  * [File stream](#user-content-file-stream)
24
  * [File stream](#user-content-file-stream)
24
  * [Manage cached files](#user-content-manage-cached-files)
25
  * [Manage cached files](#user-content-manage-cached-files)
25
 * [API](#user-content-api)
26
 * [API](#user-content-api)
93
 
94
 
94
 #### Download to storage directly
95
 #### Download to storage directly
95
 
96
 
96
-The simplest way is give a `fileCach` option to config, and set it to `true`. This will let the incoming response data stored in a temporary path **wihout** any file extension.
97
+The simplest way is give a `fileCach` option to config, and set it to `true`. This will let the incoming response data stored in a temporary path **wihout** any file extension. 
98
+
99
+**These files won't be removed automatically, please refer to [Cache File Management](#user-content-cache-file-management)**
97
 
100
 
98
 ```js
101
 ```js
99
 RNFetchBlob
102
 RNFetchBlob
113
 
116
 
114
 **Set Temp File Extension**
117
 **Set Temp File Extension**
115
 
118
 
116
-But in some cases, you might need a file extension even the file is temporary cached. For instance, when use the file path as source of `Image` element the path should end with something like .png or .jpg, you can do this by put one more option in to `config`.
119
+Sometimes you might need a file extension for some reason. For instance, when using file path as source of `Image` component, the path should end with something like .png or .jpg, you can do this by add `appendExt` option to `config`.
117
 
120
 
118
 ```js
121
 ```js
119
 RNFetchBlob
122
 RNFetchBlob
133
     imageView = <Image source={{ uri : Platform.OS === 'android' ? 'file://' : '' + res.path() }}/>
136
     imageView = <Image source={{ uri : Platform.OS === 'android' ? 'file://' : '' + res.path() }}/>
134
   })
137
   })
135
 ```
138
 ```
139
+
136
 **Use Specific File Path**
140
 **Use Specific File Path**
137
 
141
 
138
-What's more, if you prefer a specific path, rather a random generated path, you can use `path` option. We've added a [getSystemDirs](#user-content-getsysdirs) API in v0.5.0 that lists several common used directories.
142
+If you prefer a specific path rather than random generated one, you can use `path` option. We've added a [getSystemDirs](#user-content-getsysdirs) API in v0.5.0 that lists several common used directories.
139
 
143
 
140
 ```js
144
 ```js
141
 RNFetchBlob.getSystemDirs().then((dirs) => {
145
 RNFetchBlob.getSystemDirs().then((dirs) => {
142
   RNFetchBlob
146
   RNFetchBlob
143
     .config({
147
     .config({
144
       // response data will be saved to this path if it has access right.
148
       // response data will be saved to this path if it has access right.
145
-      path : dirs.DocumentDir + 'path-to-file.anything'
149
+      path : dirs.DocumentDir + '/path-to-file.anything'
146
     })
150
     })
147
     .fetch('GET', 'http://www.example.com/file/example.zip', {
151
     .fetch('GET', 'http://www.example.com/file/example.zip', {
148
       //some headers ..
152
       //some headers ..
154
 })
158
 })
155
 ```
159
 ```
156
 
160
 
161
+**These files won't be removed automatically, please refer to [Cache File Management](#user-content-cache-file-management)**
162
+
157
 ####  Upload example : Dropbox [files-upload](https://www.dropbox.com/developers/documentation/http/documentation#files-upload) API
163
 ####  Upload example : Dropbox [files-upload](https://www.dropbox.com/developers/documentation/http/documentation#files-upload) API
158
 
164
 
159
 `react-native-fetch-blob` will convert the base64 string in `body` to binary format using native API, this process will be  done in a new thread, so it's async.
165
 `react-native-fetch-blob` will convert the base64 string in `body` to binary format using native API, this process will be  done in a new thread, so it's async.
169
       mute : false
175
       mute : false
170
     }),
176
     }),
171
     'Content-Type' : 'application/octet-stream',
177
     'Content-Type' : 'application/octet-stream',
178
+    // here's the body you're going to send, should be a BASE64 encoded string 
179
+    // (you can use "base64" APIs to make one). 
180
+    // The data will be converted to "byte array"(say, blob) before request sent.  
172
   }, base64ImageString)
181
   }, base64ImageString)
173
   .then((res) => {
182
   .then((res) => {
174
     console.log(res.text())
183
     console.log(res.text())
180
 
189
 
181
 #### Upload a file from storage
190
 #### Upload a file from storage
182
 
191
 
183
-If you're going to use a `file` in file system as request body, just push the path with prefix `RNFetchBlob-file://`.
192
+If you're going to use a `file` request body, just push the path with prefix `RNFetchBlob-file://`. (We're planning to add an API to customize this prefix)
184
 
193
 
185
 ```js
194
 ```js
186
 RNFetchBlob.fetch('POST', 'https://content.dropboxapi.com/2/files/upload', {
195
 RNFetchBlob.fetch('POST', 'https://content.dropboxapi.com/2/files/upload', {
196
+    // dropbox upload headers
187
     Authorization : "Bearer access-token...",
197
     Authorization : "Bearer access-token...",
188
     'Dropbox-API-Arg': JSON.stringify({
198
     'Dropbox-API-Arg': JSON.stringify({
189
       path : '/img-from-react-native.png',
199
       path : '/img-from-react-native.png',
192
       mute : false
202
       mute : false
193
     }),
203
     }),
194
     'Content-Type' : 'application/octet-stream',
204
     'Content-Type' : 'application/octet-stream',
195
-    // Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://` when the data comes from a file
205
+    // Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://` when the data comes from a file.
196
   }, 'RNFetchBlob-file://' + PATH_TO_THE_FILE)
206
   }, 'RNFetchBlob-file://' + PATH_TO_THE_FILE)
197
   .then((res) => {
207
   .then((res) => {
198
     console.log(res.text())
208
     console.log(res.text())
204
 
214
 
205
 #### Multipart/form-data example : Post form data with file and data
215
 #### Multipart/form-data example : Post form data with file and data
206
 
216
 
207
-In `version >= 0.3.0` you can also post files with form data,  just put an array in `body`, with object elements with property `name`, `data`, and `filename`(optional).
217
+In `version >= 0.3.0` you can also post files with form data, just put an array in `body`, with elements have property `name`, `data`, and `filename`(optional).
208
 
218
 
209
 Elements have property `filename` will be transformed into binary format, otherwise it turns into utf8 string.
219
 Elements have property `filename` will be transformed into binary format, otherwise it turns into utf8 string.
210
 
220
 
230
   })
240
   })
231
 ```
241
 ```
232
 
242
 
233
-What if some fields contains a file in file storage ? Just like [upload a file from storage](#user-content-upload-a-file-from-storage) example, change the `data` to path of the file with a prefix `RNFetchBlob-file://`
243
+What if you want to upload a file in some field ? Just like [upload a file from storage](#user-content-upload-a-file-from-storage) example, change `data` to path of the file with a prefix `RNFetchBlob-file://` (this feature is only available for `version >= v0.5.0`)
234
 
244
 
235
 ```js
245
 ```js
236
 
246
 
237
   RNFetchBlob.fetch('POST', 'http://www.example.com/upload-form', {
247
   RNFetchBlob.fetch('POST', 'http://www.example.com/upload-form', {
238
     Authorization : "Bearer access-token",
248
     Authorization : "Bearer access-token",
239
     otherHeader : "foo",
249
     otherHeader : "foo",
250
+    // this is required, otherwise it won't be process as a multipart/form-data request
240
     'Content-Type' : 'multipart/form-data',
251
     'Content-Type' : 'multipart/form-data',
241
   }, [
252
   }, [
242
     // append field data from file path
253
     // append field data from file path
243
-    { name : 'avatar',
254
+    { 
255
+      name : 'avatar',
244
       filename : 'avatar.png',
256
       filename : 'avatar.png',
245
-      // Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://` when the data comes from a file
257
+      // Change BASE64 encoded data to a file path with prefix `RNFetchBlob-file://` when the data comes from a file path
246
       data: 'RNFetchBlob-file://' + PATH_TO_THE_FILE
258
       data: 'RNFetchBlob-file://' + PATH_TO_THE_FILE
247
     },
259
     },
248
     // elements without property `filename` will be sent as plain text
260
     // elements without property `filename` will be sent as plain text
278
     })
290
     })
279
 ```
291
 ```
280
 
292
 
281
-#### Handle files in storage
293
+#### File Access
294
+
295
+File access APIs were made when developing `v0.5.0`, which helping us write tests, and was not planned to be a part of this module. However I realized that, it's hard to find a great solution to manage cached files, every one who use this moudle may need those APIs for there cases. 
296
+
297
+Here's the list of `fs` APIs
298
+
299
+- getSystemDirs
300
+- createFile
301
+- readStream
302
+- writeStream
303
+- unlink
304
+- mkdir
305
+- ls
306
+- mv
307
+- cp
308
+- exists
309
+- isDir
310
+
311
+
312
+
313
+
314
+#### File Stream
315
+
316
+In `v0.5.0` we've added  `writeStream` and `readStream` in `fs`, which allows you read/write data from file path. This API creates a file stream, rather than a BASE64 encoded data of the file, it's handy when deal with **large files**.
282
 
317
 
283
-In v0.5.0 we've added a `readStream` API, which allows you read data from file directly. This API creates a file stream, rather than a BASE64 encoded data of the file, so that you won't have to worry if large files explodes the memory.
318
+But there're some differences on usage of `readStream` and `writeStream`. When calling `readStream` method, the file stream is opened immediately, and start to read data. 
284
 
319
 
285
 ```js
320
 ```js
286
 let data = ''
321
 let data = ''
287
 let stream = RNFetchBlob.readStream(
322
 let stream = RNFetchBlob.readStream(
288
-    // encoding, should be one of `base64`, `utf8`, `ascii`
323
+    // encoding, should be one of `base64`, `utf8`
289
     'base64',
324
     'base64',
290
     // file path
325
     // file path
291
     PATH_TO_THE_FILE,
326
     PATH_TO_THE_FILE,
292
-    // (optional) buffer size, default to 4096 (4098 for BASE64 encoded data)
327
+    // (optional) buffer size, default to 4096 (4095 for BASE64 encoded data)
293
     // when reading file in BASE64 encoding, buffer size must be multiples of 3.
328
     // when reading file in BASE64 encoding, buffer size must be multiples of 3.
294
-    4098)
329
+    4095)
295
 stream.onData((chunk) => {
330
 stream.onData((chunk) => {
296
   data += chunk
331
   data += chunk
297
 })
332
 })
303
 })
338
 })
304
 ```
339
 ```
305
 
340
 
306
-#### Release cache files
341
+#### Cache File Management
307
 
342
 
308
 When using `fileCache` or `path` options along with `fetch` API, response data will automatically stored into file system. The files will **NOT** removed unless you `unlink` it. There're several ways to remove the files
343
 When using `fileCache` or `path` options along with `fetch` API, response data will automatically stored into file system. The files will **NOT** removed unless you `unlink` it. There're several ways to remove the files
309
 
344