浏览代码

bump to 0.6.0 and change README.md

Ben Hsieh 8 年前
父节点
当前提交
1d49a34f65
共有 3 个文件被更改,包括 77 次插入807 次删除
  1. 24
    435
      README.md
  2. 52
    371
      src/README.md
  3. 1
    1
      src/package.json

+ 24
- 435
README.md 查看文件

1
-# react-native-fetch-blob [![npm](https://img.shields.io/npm/v/react-native-fetch-blob.svg?style=flat-square)]() ![](https://img.shields.io/badge/PR-Welcome-brightgreen.svg?style=flat-square) [![npm](https://img.shields.io/npm/l/express.svg?maxAge=2592000&style=flat-square)]() 
1
+# react-native-fetch-blob [![npm](https://img.shields.io/npm/v/react-native-fetch-blob.svg?style=flat-square)]() ![](https://img.shields.io/badge/PR-Welcome-brightgreen.svg?style=flat-square) [![npm](https://img.shields.io/npm/l/express.svg?maxAge=2592000&style=flat-square)]()
2
 
2
 
3
 A module provides upload, download, and files access API. Supports file stream read/write for process large files.
3
 A module provides upload, download, and files access API. Supports file stream read/write for process large files.
4
 
4
 
27
  * [File stream](#user-content-file-stream)
27
  * [File stream](#user-content-file-stream)
28
  * [Manage cached files](#user-content-manage-cached-files)
28
  * [Manage cached files](#user-content-manage-cached-files)
29
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
29
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
30
-* [API](#user-content-api)
31
- * [config](#user-content-configoptionsrnfetchblobconfigfetch)
32
- * [fetch](#user-content-fetchmethod-url-headers-bodypromisefetchblobresponse)
33
- * [session](#user-content-sessionnamestringrnfetchblobsession)
34
- * [base64](#user-content-base64)
35
- * [fs](#user-content-fs)
30
+* [API References](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API)
36
 * [Development](#user-content-development)
31
 * [Development](#user-content-development)
37
 
32
 
38
 ## Installation
33
 ## Installation
70
 
65
 
71
 ```
66
 ```
72
 
67
 
68
+Also, if you're going to use `Android Download Manager` you have to add this to `AndroidManifetst.xml`
69
+
70
+```diff
71
+    <intent-filter>
72
+            <action android:name="android.intent.action.MAIN" />
73
+            <category android:name="android.intent.category.LAUNCHER" />
74
++           <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/>                          
75
+    </intent-filter>
76
+```
77
+
73
 **Grant Access Permission for Android 6.0**
78
 **Grant Access Permission for Android 6.0**
74
 
79
 
75
 Beginning in Android 6.0 (API level 23), users grant permissions to apps while the app is running, not when they install the app. So adding permissions in `AndroidManifest.xml` won't work in Android 6.0 devices. To grant permissions in runtime, you might use modules like [react-native-android-permissions](https://github.com/lucasferreira/react-native-android-permissions).
80
 Beginning in Android 6.0 (API level 23), users grant permissions to apps while the app is running, not when they install the app. So adding permissions in `AndroidManifest.xml` won't work in Android 6.0 devices. To grant permissions in runtime, you might use modules like [react-native-android-permissions](https://github.com/lucasferreira/react-native-android-permissions).
331
 
336
 
332
 When download large files on Android it is recommended to use `Download Manager`, it supports lot of native features like progress bar, and notification, also the download task will be handled by OS, and more effective.
337
 When download large files on Android it is recommended to use `Download Manager`, it supports lot of native features like progress bar, and notification, also the download task will be handled by OS, and more effective.
333
 
338
 
339
+When using DownloadManager, `fileCache` and `path` properties in `config` will not take effect, because Android DownloadManager can only store files to external storage. When download complete, DownloadManager will generate a file path so that you can deal with it.
340
+
334
 ```js
341
 ```js
335
 RNFetchBlob
342
 RNFetchBlob
336
     .config({
343
     .config({
337
-        // Optional, if not specified, the file will download to system default path
338
-        path : DOWNLOAD_DEST,
339
         addAdnroidDownloads : {
344
         addAdnroidDownloads : {
340
             useDownloadManager : true, // <-- this is the only thing required
345
             useDownloadManager : true, // <-- this is the only thing required
341
             // Optional, override notification setting (default to true)
346
             // Optional, override notification setting (default to true)
347
         }
352
         }
348
     })
353
     })
349
     .fetch('GET', 'http://example.com/file/somefile')
354
     .fetch('GET', 'http://example.com/file/somefile')
355
+    .then((resp) => {
356
+      // the path of downloaded file
357
+      resp.path()
358
+    })
350
 ```
359
 ```
351
 
360
 
352
 
361
 
386
 
395
 
387
 - dirs
396
 - dirs
388
 - createFile
397
 - createFile
398
+- readFile
399
+- writeFile
400
+- appendFile
389
 - readStream
401
 - readStream
390
 - writeStream
402
 - writeStream
391
 - unlink
403
 - unlink
399
 - stat
411
 - stat
400
 - scanFile (Android Only)
412
 - scanFile (Android Only)
401
 
413
 
402
-See [fs chapter](#user-content-fs) for more information
414
+See [File API](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API) for more information
403
 
415
 
404
 #### File Stream
416
 #### File Stream
405
 
417
 
521
 })
533
 })
522
 ```
534
 ```
523
 
535
 
524
----
525
-
526
-## API
527
-
528
-### `config(options:RNFetchBlobConfig):fetch`
529
-
530
-`0.5.0`
531
-
532
-Config API was introduced in `v0.5.0` which provides some options for the `fetch` task.
533
-
534
-see [RNFetchBlobConfig](#user-content-configoptionsrnfetchblobconfigfetch)
535
-
536
-### `fetch(method, url, headers, body):Promise<FetchBlobResponse>`
537
-
538
-`legacy`
539
-
540
-Send a HTTP request uses given headers and body, and return a Promise.
541
-
542
-#### method:`string` Required
543
-HTTP request method, can be one of `get`, `post`, `delete`, and `put`, case-insensitive.
544
-#### url:`string` Required
545
-HTTP request destination url.
546
-#### headers:`object` (Optional)
547
-Headers of HTTP request, value of headers should be `stringified`, if you're uploading binary files, content-type should be `application/octet-stream` or `multipart/form-data`(see examples above).
548
-#### body:`string | Array<Object>` (Optional)
549
-Body of the HTTP request, body can either be a BASE64 string, or an array contains object elements, each element have 2  required property `name`, and `data`, and 1 optional property `filename`, once `filename` is set, content in `data` property will be consider as BASE64 string that will be converted into byte array later.
550
-When body is a base64 string , this string will be converted into byte array in native code, and the request body will be sent as `application/octet-stream`.
551
-
552
-### `fetch(...).progress(eventListener):Promise<FetchBlobResponse>`
553
-
554
-`0.4.2`
555
-
556
-Register on progress event handler for a fetch request.
557
-
558
-#### eventListener:`(sendOrReceivedBytes:number, totalBytes:number)`
559
-
560
-A function that triggers when there's data received/sent, first argument is the number of sent/received bytes, and second argument is expected total bytes number.
561
-
562
-### `wrap(path:string):string`
563
-
564
-Simply prepend `RNFetchBlob-file://` to a path, this make the file path becomes recognizable to native `fetch` method.
565
-
566
-### `session(name:string):RNFetchBlobSession`
567
-
568
-Session API helps managing cached files, the following code, will try to return an existing session object with the given `name`, if it does not exist, create one.
569
-
570
-```js
571
-RNFetchBlob.session('mysession')
572
-```
573
-see [Class RNFetchBlobSession](#user-content-rnfetchblobsession) for usage.
574
-
575
-### `base64`
576
-
577
-
578
-`0.4.2`
579
-
580
-A helper class simply uses [base-64](https://github.com/mathiasbynens/base64) for decode and encode BASE64 data.
581
-
582
-```js
583
-RNFetchBlob.base64.encode(data)
584
-RNFetchBlob.base64.decode(data)
585
-```
586
-
587
-### `fs`
588
-
589
-`0.5.0`
590
-
591
-#### dirs
592
-
593
-This constant is a hash map contains common used folders:
594
-- DocumentDir
595
-- CacheDir
596
-- DCIMDir (Android Only)
597
-- DownloadDir (Android Only)
598
-- MusicDir (Android Only)
599
-- PictureDir (Android Only)
600
-- MovieDir (Android Only)
601
-- RingtoneDir (Android Only)
602
-
603
-```js
604
-const dirs = RNFetchBlob.fs.dirs
605
-console.log(dirs.DocumentDir)
606
-console.log(dirs.CacheDir)
607
-console.log(dirs.DCIMDir)
608
-console.log(dirs.DownloadDir)
609
-```
610
-> If you're going to make downloaded file visible in Android `Downloads` app, please see [Show Downloaded File and Notification in Android Downloads App](#user-content-show-downloaded-file-and-notifiction-in-android-downloads-app).
611
-
612
-### createFile(path, data, encoding):Promise
613
-
614
-#### path:`string`
615
-The path which this new file will be created.
616
-#### data:`string` | `Array<number>`
617
-Content of the new file, when `encoding` is `ascii`, this argument shoud be an array contains number 0~255.
618
-#### encoding:`utf8` | `base64` | `ascii`
619
-Encoding of content.
620
-
621
-the following expressions are equivalent.
622
-
623
-```js
624
-const fs = RNFetchBlob.fs
625
-const base64 = RNFetchBlob.base64
626
-fs.createFile(NEW_FILE_PATH, 'foo', 'utf8')
627
-fs.createFile(NEW_FILE_PATH, [102, 111, 111], 'ascii')
628
-fs.createFile(NEW_FILE_PATH, base64.encode('foo'), 'base64')
629
-```
630
-
631
-### writeFile(path:string, content:string | Array<number>, encoding:string, append:boolean):Promise<WriteStream>
632
-
633
-`0.6.0`
634
-
635
-#### path:`string`
636
-The path of the file to write.
637
-#### content:`string` | `Array<number>`
638
-Data that write to the `path`, should be an utf8/base64 encoded string, or an array contains numbers between 0-255.
639
-#### encoding:`utf8` | `base64` | `ascii`
640
-Encoding of input data.
641
-#### append:`boolean`(optional, default to `false`)
642
-Will new data append after existing file or not.
643
-
644
-```js
645
-
646
-// write UTF8 data to file
647
-RNFetchBlob.fs.writeFile(PATH_TO_WRITE, 'foo', 'utf8', false)
648
-              .then(()=>{ ... })
649
-// write bytes to file
650
-RNFetchBlob.fs.writeFile(PATH_TO_WRITE, [102,111,111], 'ascii', true)
651
-              .then(()=>{ ... })
652
-// write base64 data to file
653
-RNFetchBlob.fs.writeFile(PATH_TO_WRITE, RNFetchBlob.base64.encode('foo'), 'base64', true)
654
-              .then(()=>{ ... })
655
-
656
-// the file should have content like this
657
-// foofoofoo
658
-
659
-```
660
-
661
-### writeStream(path:string, encoding:string, append:boolean):Promise<WriteStream>
662
-
663
-`0.5.0`
664
-
665
-#### path:`string`
666
-The path to the file the stream is writing to.
667
-#### encoding:`utf8` | `base64` | `ascii`
668
-Encoding of input data.
669
-#### append:`boolean`(optional, default to `false`)
670
-Will new data append after existing file or not.
671
-
672
-Calling `writeStream` method will returns a Promise, which resolves a `RNFetchBlobWriteSteam` instance when stream opened successfully.
673
-
674
-```js
675
-// write utf8 data
676
-RNFetchBlob.fs.writeStream(PATH_TO_WRITE, 'utf8')
677
-    .then((stream) => {
678
-        stream.write('foo')
679
-        return stream.close()
680
-    })
681
-// write ASCII data
682
-RNFetchBlob.fs.writeStream(PATH_TO_WRITE, 'ascii')
683
-    .then((stream) => {
684
-        // write char `f`
685
-        stream.write([102])
686
-        // write char `o`, `o`
687
-        stream.write([111,111])
688
-        return stream.close()
689
-    })
690
-// write BASE64
691
-RNFetchBlob.fs.writeStream(PATH_TO_WRITE, 'base64')
692
-    .then((stream) => {
693
-        stream.write(RNFetchBlob.base64.encode('foo'))
694
-        return stream.close()
695
-    })
696
-
697
-```
698
-
699
-#### readFile(path, encoding):Promise<ReadStream>
700
-
701
-`0.6.0`
702
-
703
-##### path:`string`
704
-Path of the file to file.
705
-##### encoding:`string`
706
-Decoder to decode the file data, should be one of `base64`, `ascii`, and `utf8`, it uses `utf8` by default.
707
-
708
-Read the file from the given path, if the file is large, you should consider use `readStream` instead.
709
-
710
-```js
711
-RNFetchBlob.fs.readFile(PATH_TO_READ, 'base64')
712
-.then((data) => {
713
-  // handle the data ..
714
-})
715
-```
716
-
717
-
718
-
719
-#### readStream(path, encoding, bufferSize):Promise<ReadStream>
720
-
721
-`0.5.0`
722
-
723
-##### path:`string`
724
-The path to the file the stream is reading from.
725
-##### encoding:`string`
726
-Encoding of the data.
727
-##### bufferSize:`number`(optional)
728
-Buffer size of read stream, default to `4096` and `4095`(when encoding is `base64`)
729
-
730
-`readStream` returns a promise which will resolve `RNFetchBlobReadStream`.
731
-
732
-```js
733
-RNFetchBlob.fs.readStream(PATH_TO_READ, 'utf8')
734
-    .then((stream) => {
735
-        let data = ''
736
-        stream.open()
737
-        stream.onData((chunk) => {
738
-            chunk += data
739
-        })
740
-        stream.onEnd(() => {
741
-            console.log(data)
742
-        })
743
-    })
744
-```
745
-
746
-#### mkdir(path:string):Promise
747
-
748
-`0.5.0`
749
-
750
-Create a directory named `path`
751
-
752
-```js
753
-RNFetchBlob.fs.mkdir(PATH_TO_CREATE)
754
-.then(() => { ... })
755
-.catch((err) => { ... })
756
-```
757
-
758
-#### ls(path:string):Promise<Array<String>>
759
-
760
-`0.5.0`
761
-
762
-List files and directories in a `path`
763
-
764
-```js
765
-RNFetchBlob.fs.ls(PATH_TO_LIST)
766
-    // files will an array contains filenames
767
-    .then((files) => {
768
-        console.log(files)
769
-    })
770
-```
771
-
772
-#### mv(from:string, to:string):Promise
773
-
774
-`0.5.0`
775
-
776
-Move a file's location
777
-
778
-```js
779
-RNFetchBlob.fs.mv(FROM_PATH, TO_PATH)
780
-.then(() => { ... })
781
-.catch(() => { ... })
782
-```
783
-
784
-#### cp(src:string, dest:string):Promise
785
-
786
-Copy a file.
787
-
788
-```js
789
-RNFetchBlob.fs.mv(SRC_PATH, DEST_PATH)
790
-.then(() => { ... })
791
-.catch(() => { ... })
792
-```
793
-
794
-#### exists(path:string):Promise<boolean>
795
-
796
-`0.5.0`
797
-
798
-Check if a file exist at `path`
799
-
800
-```js
801
-RNFetchBlob.fs.exists(PATH_OF_FILE)
802
-.then((exist) => {
803
-    console.log(`file ${exist ? '' : 'not'} exists`)
804
-})
805
-.catch(() => { ... })
806
-```
807
-
808
-#### isDir(path:string):Promise<boolean>
809
-
810
-Check the file at `path` is a directory or not. Resolves with `false` when the path is not a directory, or it does not exists.
811
-
812
-```js
813
-RNFetchBlob.fs.exists(PATH_OF_FILE)
814
-.then((isDir) => {
815
-    console.log(`file is ${isDir ? '' : 'not'} a directory`)
816
-})
817
-```
818
-
819
-#### unlink(path:string):Promise<boolean>
820
-
821
-`0.5.0`
822
-
823
-Delete a file at `path`
824
-
825
-```js
826
-RNFetchBlob.fs.unlink(path)
827
-.then(() => { ... })
828
-.catch((err) => { ... })
829
-```
830
-
831
-#### lstat(path:string):Promise<RNFetchBlobStat>
832
-
833
-`0.5.0`
834
-
835
-Get statistic data of files in a directory, the result data will be an array of [RNFetchBlobStat](#user-content-rnfetchblobstat).
836
-
837
-```js
838
-RNFetchBlob.fs.lstat(PATH_OF_A_FOLDER)
839
-    .then((stats) => {})
840
-    .catch((err) => {})
841
-```
842
-
843
-#### stat(path:string):Promise<RNFetchBlobStat>
844
-
845
-`0.5.0`
846
-
847
-Similar get statistic a data or a directory. the result data will be a [RNFetchBlobStat](#user-content-rnfetchblobstat).
848
-
849
-```js
850
-RNFetchBlob.fs.stat(PATH_OF_THE_TARGET)
851
-    .then((stats) => {})
852
-    .catch((err) => {})
853
-```
854
-
855
-#### scanFile(path:string):Promise (Androi Only)
856
-
857
-Connect `Media Scanner` and scan the file. see [Android Media Scanner, and Downloads App Support](#user-content-android-media-scanner-and-downloads-app-support) chapter for more information.
858
-
859
----
860
-
861
-## Types
862
-
863
-### RNFetchBlobConfig
864
-
865
-A set of configurations that will be injected into a `fetch` method, with the following properties.
866
-
867
-#### indicator:boolean
868
-  `0.5.6`
869
-  Set this property to `true` to display a network indicator on status bar, this feature is only supported on IOS.
870
-
871
-#### trusty:boolean
872
-  `0.5.3`
873
-  Set this property to `true` will allow the request create connection with server have self-signed SSL certification. This is not recommended to use in production.
874
-
875
-#### fileCache:boolean
876
-  Set this property to `true` will makes response data of the `fetch` stored in a temp file, by default the temp file will stored in App's own root folder with file name template `RNFetchBlob_tmp${timestamp}`.
877
-#### appendExt:string
878
-  Set this property to change temp file extension that created by `fetch` response data.
879
-#### path:string
880
-  When this property has value, `fetch` API will try to store response data in the path ignoring `fileCache` and `appendExt` property.
881
-#### addAndroidDownloads:object (Android only)
882
-  This is an Android only property, it should be an object with the following properties :
883
-  - useDownloadManager : download file using Android download manager or not.
884
-  - title : title of the file
885
-  - description : File description of the file.
886
-  - mime : MIME type of the file. By default is `text/plain`
887
-  - mediaScannable : A `boolean` value, see [Officail Document](https://developer.android.com/reference/android/app/DownloadManager.html#addCompletedDownload(java.lang.String, java.lang.String, boolean, java.lang.String, java.lang.String, long, boolean))
888
-  - notification : A `boolean` value decide whether show a notification when download complete.
889
-
890
-### RNFetchBlobResponse
891
-
892
-When `fetch` success, it resolve a `FetchBlobResponse` object as first argument. `FetchBlobResponse` object has the following methods (these method are synchronous, so you might take quite a performance impact if the file is big)
893
-
894
-#### base64():string
895
-  returns base64 string of response data (done in native context)
896
-#### json():object
897
-  returns json parsed object (done in js context)
898
-#### text():string
899
-  returns decoded base64 string (done in js context)
900
-#### path():string
901
-  returns file path if the response data is cached in file
902
-#### readFile(encoding:string):Promise
903
-  return a promise that resolves response data when possible.
904
-#### readStream(encoding:string, bufferSize:number):Promise<RNFetchBlobSession>
905
-  return a promise that resolves a `readStream` object when possible.
906
-#### session(name:string):RNFetchBlobSession
907
-  when the response data is cached in a file, this method adds the file into the session. The following usages are equivalent.
908
-```js
909
-RNFetchBlob.session('session-name').add(resp.path())
910
-// or
911
-resp.session('session-name')
912
-```
913
-
914
-### RNFetchBlobStat
915
-
916
-Statistic data of a file, see the following sample object.
917
-
918
-```js
919
-{
920
-    // file name
921
-    filename : 'foo.png',
922
-    // folder of the file or the folder itself
923
-    path : '/path/to/the/file/wihout/file/name/',
924
-    // size in byte
925
-    size : 4901,
926
-    // `file` or `directory`
927
-    type : 'file',
928
-    // last modified timestamp
929
-    lastModified : 141323298
930
-}
931
-```
932
-
933
-
934
-### RNFetchBlobSession
935
-
936
-A `session` is an object that helps you manage files. It simply maintains a list of file path and let you use `dispose()`to delete files in this session once and for all.
937
-
938
-#### add(path:string):RNFetchBlobSession
939
-  Add a file path to this session.
940
-#### remove(path:string):RNFetchBlobSession
941
-  Remove a file path from this session (not delete the file).
942
-#### list():Array<String>
943
-  Returns an array contains file paths in this session.
944
-#### dispose():Promise
945
-  Delete all files according to paths in the session.
946
-
947
-## Major Changes
536
+## Changes
948
 
537
 
949
 | Version | |
538
 | Version | |
950
 |---|---|
539
 |---|---|
958
 | 0.5.2 | Fix improper url params bug [#26](https://github.com/wkh237/react-native-fetch-blob/issues/26) and change IOS HTTP implementation from NSURLConnection to NSURLSession |
547
 | 0.5.2 | Fix improper url params bug [#26](https://github.com/wkh237/react-native-fetch-blob/issues/26) and change IOS HTTP implementation from NSURLConnection to NSURLSession |
959
 | 0.5.0 | Upload/download with direct access to file storage, and also added file access APIs |
548
 | 0.5.0 | Upload/download with direct access to file storage, and also added file access APIs |
960
 | 0.4.2 | Supports upload/download progress |
549
 | 0.4.2 | Supports upload/download progress |
961
-| 0.4.1 | Fixe upload form-data missing file extension problem on Android |
550
+| 0.4.1 | Fix upload form-data missing file extension problem on Android |
962
 | 0.4.0 | Add base-64 encode/decode library and API |
551
 | 0.4.0 | Add base-64 encode/decode library and API |
963
 | ~0.3.0 | Upload/Download octet-stream and form-data |
552
 | ~0.3.0 | Upload/Download octet-stream and form-data |
964
 
553
 

+ 52
- 371
src/README.md 查看文件

1
-# react-native-fetch-blob [![npm version](https://img.shields.io/badge/npm package-0.5.8-brightgreen.svg)](https://badge.fury.io/js/react-native-fetch-blob) ![](https://img.shields.io/badge/PR-Welcome-brightgreen.svg) ![](https://img.shields.io/badge/in progress-0.6.0-yellow.svg)
1
+# react-native-fetch-blob [![npm](https://img.shields.io/npm/v/react-native-fetch-blob.svg?style=flat-square)]() ![](https://img.shields.io/badge/PR-Welcome-brightgreen.svg?style=flat-square) [![npm](https://img.shields.io/npm/l/express.svg?maxAge=2592000&style=flat-square)]()
2
 
2
 
3
 A module provides upload, download, and files access API. Supports file stream read/write for process large files.
3
 A module provides upload, download, and files access API. Supports file stream read/write for process large files.
4
 
4
 
22
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
22
  * [Upload file](#user-content-upload-example--dropbox-files-upload-api)
23
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
23
  * [Multipart/form upload](#user-content-multipartform-data-example--post-form-data-with-file-and-data)
24
  * [Upload/Download progress](#user-content-uploaaddownload-progress)
24
  * [Upload/Download progress](#user-content-uploaaddownload-progress)
25
- * [Android Media Scanner, and Downloads App Support](#user-content-android-media-scanner-and-downloads-app-support)
25
+ * [Android Media Scanner, and Download Manager Support](#user-content-android-media-scanner-and-downloads-app-support)
26
  * [File access](#user-content-file-access)
26
  * [File access](#user-content-file-access)
27
  * [File stream](#user-content-file-stream)
27
  * [File stream](#user-content-file-stream)
28
  * [Manage cached files](#user-content-manage-cached-files)
28
  * [Manage cached files](#user-content-manage-cached-files)
29
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
29
  * [Self-Signed SSL Server](#user-content-self-signed-ssl-server)
30
-* [API](#user-content-api)
31
- * [config](#user-content-configoptionsrnfetchblobconfigfetch)
32
- * [fetch](#user-content-fetchmethod-url-headers-bodypromisefetchblobresponse)
33
- * [session](#user-content-sessionnamestringrnfetchblobsession)
34
- * [base64](#user-content-base64)
35
- * [fs](#user-content-fs)
30
+* [API References](https://github.com/wkh237/react-native-fetch-blob/wiki/Fetch-API)
36
 * [Development](#user-content-development)
31
 * [Development](#user-content-development)
37
 
32
 
38
 ## Installation
33
 ## Installation
70
 
65
 
71
 ```
66
 ```
72
 
67
 
68
+Also, if you're going to use `Android Download Manager` you have to add this to `AndroidManifetst.xml`
69
+
70
+```diff
71
+    <intent-filter>
72
+            <action android:name="android.intent.action.MAIN" />
73
+            <category android:name="android.intent.category.LAUNCHER" />
74
++           <action android:name="android.intent.action.DOWNLOAD_COMPLETE"/>                          
75
+    </intent-filter>
76
+```
77
+
73
 **Grant Access Permission for Android 6.0**
78
 **Grant Access Permission for Android 6.0**
74
 
79
 
75
 Beginning in Android 6.0 (API level 23), users grant permissions to apps while the app is running, not when they install the app. So adding permissions in `AndroidManifest.xml` won't work in Android 6.0 devices. To grant permissions in runtime, you might use modules like [react-native-android-permissions](https://github.com/lucasferreira/react-native-android-permissions).
80
 Beginning in Android 6.0 (API level 23), users grant permissions to apps while the app is running, not when they install the app. So adding permissions in `AndroidManifest.xml` won't work in Android 6.0 devices. To grant permissions in runtime, you might use modules like [react-native-android-permissions](https://github.com/lucasferreira/react-native-android-permissions).
302
     })
307
     })
303
 ```
308
 ```
304
 
309
 
305
-#### Android Media Scanner, and Downloads App Support
310
+#### Android Media Scanner, and Download Manager Support
311
+
312
+If you want to make a file in `External Storage` becomes visible in Picture, Downloads, or other built-in apps, you will have to use `Media Scanner` or `Download Manager`.
306
 
313
 
307
-If you want to make a file in `External Storage` becomes visible in Picture, Music, or other built-in apps, you will have to use `Media Scanner`. To make this happend, use `scanFile` method in `fs`.
314
+**Media Scanner**
308
 
315
 
316
+Media scanner scan the file and categorize by given MIME type, if MIME type not specified, it will try to resolve the file using its file extension.
309
 
317
 
310
 ```js
318
 ```js
311
 
319
 
312
-RNFetchBlog
320
+RNFetchBlob
313
     .config({
321
     .config({
314
         // DCIMDir is in external storage
322
         // DCIMDir is in external storage
315
         path : dirs.DCIMDir + '/music.mp3'
323
         path : dirs.DCIMDir + '/music.mp3'
324
     })
332
     })
325
 ```
333
 ```
326
 
334
 
327
-If mime is null or undefined, then the mime type will be inferred from the file extension.
335
+**Download Manager**
336
+
337
+When download large files on Android it is recommended to use `Download Manager`, it supports lot of native features like progress bar, and notification, also the download task will be handled by OS, and more effective.
338
+
339
+When using DownloadManager, `fileCache` and `path` properties in `config` will not take effect, because Android DownloadManager can only store files to external storage. When download complete, DownloadManager will generate a file path so that you can deal with it.
340
+
341
+```js
342
+RNFetchBlob
343
+    .config({
344
+        addAdnroidDownloads : {
345
+            useDownloadManager : true, // <-- this is the only thing required
346
+            // Optional, override notification setting (default to true)
347
+            notification : false,
348
+            // Optional, but recommended since android DownloadManager will fail when
349
+            // the url does not contains a file extension, by default the mime type will be text/plain
350
+            mime : 'text/plain',
351
+            description : 'File downloaded by download manager.'
352
+        }
353
+    })
354
+    .fetch('GET', 'http://example.com/file/somefile')
355
+    .then((resp) => {
356
+      // the path of downloaded file
357
+      resp.path()
358
+    })
359
+```
360
+
328
 
361
 
329
 **Download Notification and Visibiliy in Download App (Android Only)**
362
 **Download Notification and Visibiliy in Download App (Android Only)**
330
 
363
 
362
 
395
 
363
 - dirs
396
 - dirs
364
 - createFile
397
 - createFile
398
+- readFile
399
+- writeFile
400
+- appendFile
365
 - readStream
401
 - readStream
366
 - writeStream
402
 - writeStream
367
 - unlink
403
 - unlink
375
 - stat
411
 - stat
376
 - scanFile (Android Only)
412
 - scanFile (Android Only)
377
 
413
 
378
-See [fs chapter](#user-content-fs) for more information
414
+See [File API](https://github.com/wkh237/react-native-fetch-blob/wiki/File-System-Access-API) for more information
379
 
415
 
380
 #### File Stream
416
 #### File Stream
381
 
417
 
497
 })
533
 })
498
 ```
534
 ```
499
 
535
 
500
----
501
-
502
-## API
503
-
504
-### `config(options:RNFetchBlobConfig):fetch`
505
-
506
-`0.5.0`
507
-
508
-Config API was introduced in `v0.5.0` which provides some options for the `fetch` task.
509
-
510
-see [RNFetchBlobConfig](#user-content-configoptionsrnfetchblobconfigfetch)
511
-
512
-### `fetch(method, url, headers, body):Promise<FetchBlobResponse>`
513
-
514
-`legacy`
515
-
516
-Send a HTTP request uses given headers and body, and return a Promise.
517
-
518
-#### method:`string` Required
519
-HTTP request method, can be one of `get`, `post`, `delete`, and `put`, case-insensitive.
520
-#### url:`string` Required
521
-HTTP request destination url.
522
-#### headers:`object` (Optional)
523
-Headers of HTTP request, value of headers should be `stringified`, if you're uploading binary files, content-type should be `application/octet-stream` or `multipart/form-data`(see examples above).
524
-#### body:`string | Array<Object>` (Optional)
525
-Body of the HTTP request, body can either be a BASE64 string, or an array contains object elements, each element have 2  required property `name`, and `data`, and 1 optional property `filename`, once `filename` is set, content in `data` property will be consider as BASE64 string that will be converted into byte array later.
526
-When body is a base64 string , this string will be converted into byte array in native code, and the request body will be sent as `application/octet-stream`.
527
-
528
-### `fetch(...).progress(eventListener):Promise<FetchBlobResponse>`
529
-
530
-`0.4.2`
531
-
532
-Register on progress event handler for a fetch request.
533
-
534
-#### eventListener:`(sendOrReceivedBytes:number, totalBytes:number)`
535
-
536
-A function that triggers when there's data received/sent, first argument is the number of sent/received bytes, and second argument is expected total bytes number.
537
-
538
-### `wrap(path:string):string`
539
-
540
-Simply prepend `RNFetchBlob-file://` to a path, this make the file path becomes recognizable to native `fetch` method.
541
-
542
-### `session(name:string):RNFetchBlobSession`
543
-
544
-Session API helps managing cached files, the following code, will try to return an existing session object with the given `name`, if it does not exist, create one.
545
-
546
-```js
547
-RNFetchBlob.session('mysession')
548
-```
549
-see [Class RNFetchBlobSession](#user-content-rnfetchblobsession) for usage.
550
-
551
-### `base64`
552
-
553
-
554
-`0.4.2`
555
-
556
-A helper class simply uses [base-64](https://github.com/mathiasbynens/base64) for decode and encode BASE64 data.
557
-
558
-```js
559
-RNFetchBlob.base64.encode(data)
560
-RNFetchBlob.base64.decode(data)
561
-```
562
-
563
-### `fs`
564
-
565
-`0.5.0`
566
-
567
-#### dirs
568
-
569
-This constant is a hash map contains common used folders:
570
-- DocumentDir
571
-- CacheDir
572
-- DCIMDir (Android Only)
573
-- DownloadDir (Android Only)
574
-- MusicDir (Android Only)
575
-- PictureDir (Android Only)
576
-- MovieDir (Android Only)
577
-- RingtoneDir (Android Only)
578
-
579
-```js
580
-const dirs = RNFetchBlob.fs.dirs
581
-console.log(dirs.DocumentDir)
582
-console.log(dirs.CacheDir)
583
-console.log(dirs.DCIMDir)
584
-console.log(dirs.DownloadDir)
585
-```
586
-> If you're going to make downloaded file visible in Android `Downloads` app, please see [Show Downloaded File and Notification in Android Downloads App](#user-content-show-downloaded-file-and-notifiction-in-android-downloads-app).
587
-
588
-### createFile(path, data, encoding):Promise
589
-
590
-#### path:`string`
591
-The path which this new file will be created.
592
-#### data:`string` | `Array<number>`
593
-Content of the new file, when `encoding` is `ascii`, this argument shoud be an array contains number 0~255.
594
-#### encoding:`utf8` | `base64` | `ascii`
595
-Encoding of content.
596
-
597
-the following expressions are equivalent.
598
-
599
-```js
600
-const fs = RNFetchBlob.fs
601
-const base64 = RNFetchBlob.base64
602
-fs.createFile(NEW_FILE_PATH, 'foo', 'utf8')
603
-fs.createFile(NEW_FILE_PATH, [102, 111, 111], 'ascii')
604
-fs.createFile(NEW_FILE_PATH, base64.encode('foo'), 'base64')
605
-```
606
-
607
-### writeStream(path:string, encoding:string, append:boolean):Promise<WriteStream>
608
-
609
-#### path:`string`
610
-The path to the file the stream is writing to.
611
-#### encoding:`utf8` | `base64` | `ascii`
612
-Encoding of input data.
613
-#### append:`boolean`(optional, default to `false`)
614
-Will new data append after existing file or not.
615
-
616
-Calling `writeStream` method will returns a Promise, which resolves a `RNFetchBlobWriteSteam` instance when stream opened successfully.
617
-
618
-```js
619
-// write utf8 data
620
-RNFetchBlob.fs.writeStream(PATH_TO_WRITE, 'utf8')
621
-    .then((stream) => {
622
-        stream.write('foo')
623
-        return stream.close()
624
-    })
625
-// write ASCII data
626
-RNFetchBlob.fs.writeStream(PATH_TO_WRITE, 'ascii')
627
-    .then((stream) => {
628
-        // write char `f`
629
-        stream.write([102])
630
-        // write char `o`, `o`
631
-        stream.write([111,111])
632
-        return stream.close()
633
-    })
634
-// write BASE64
635
-RNFetchBlob.fs.writeStream(PATH_TO_WRITE, 'base64')
636
-    .then((stream) => {
637
-        stream.write(RNFetchBlob.base64.encode('foo'))
638
-        return stream.close()
639
-    })
640
-
641
-```
642
-
643
-#### readStream(path, encoding, bufferSize):Promise<ReadStream>
644
-
645
-##### path:`string`
646
-The path to the file the stream is reading from.
647
-##### encoding:`string`
648
-Encoding of the data.
649
-##### bufferSize:`number`(optional)
650
-Buffer size of read stream, default to `4096` and `4095`(when encoding is `base64`)
651
-
652
-`readStream` returns a promise which will resolve `RNFetchBlobReadStream`.
653
-
654
-```js
655
-RNFetchBlob.fs.readStream(PATH_TO_READ, 'utf8')
656
-    .then((stream) => {
657
-        let data = ''
658
-        stream.open()
659
-        stream.onData((chunk) => {
660
-            chunk += data
661
-        })
662
-        stream.onEnd(() => {
663
-            console.log(data)
664
-        })
665
-    })
666
-```
667
-
668
-#### mkdir(path:string):Promise
669
-
670
-Create a directory named `path`
671
-
672
-```js
673
-RNFetchBlob.fs.mkdir(PATH_TO_CREATE)
674
-.then(() => { ... })
675
-.catch((err) => { ... })
676
-```
677
-
678
-#### ls(path:string):Promise<Array<String>>
679
-
680
-List files and directories in a `path`
681
-
682
-```js
683
-RNFetchBlob.fs.ls(PATH_TO_LIST)
684
-    // files will an array contains filenames
685
-    .then((files) => {
686
-        console.log(files)
687
-    })
688
-```
689
-
690
-#### mv(from:string, to:string):Promise
691
-
692
-Move a file's location
693
-
694
-```js
695
-RNFetchBlob.fs.mv(FROM_PATH, TO_PATH)
696
-.then(() => { ... })
697
-.catch(() => { ... })
698
-```
699
-
700
-#### cp(src:string, dest:string):Promise
701
-
702
-Copy a file.
703
-
704
-```js
705
-RNFetchBlob.fs.mv(SRC_PATH, DEST_PATH)
706
-.then(() => { ... })
707
-.catch(() => { ... })
708
-```
709
-
710
-#### exists(path:string):Promise<boolean>
711
-
712
-Check if a file exist at `path`
713
-
714
-```js
715
-RNFetchBlob.fs.exists(PATH_OF_FILE)
716
-.then((exist) => {
717
-    console.log(`file ${exist ? '' : 'not'} exists`)
718
-})
719
-.catch(() => { ... })
720
-```
721
-
722
-#### isDir(path:string):Promise<boolean>
723
-
724
-Check the file at `path` is a directory or not. Resolves with `false` when the path is not a directory, or it does not exists.
725
-
726
-```js
727
-RNFetchBlob.fs.exists(PATH_OF_FILE)
728
-.then((isDir) => {
729
-    console.log(`file is ${isDir ? '' : 'not'} a directory`)
730
-})
731
-```
732
-
733
-#### unlink(path:string):Promise<boolean>
734
-
735
-Delete a file at `path`
736
-
737
-```js
738
-RNFetchBlob.fs.unlink(path)
739
-.then(() => { ... })
740
-.catch((err) => { ... })
741
-```
742
-
743
-#### lstat(path:string):Promise<RNFetchBlobStat>
744
-
745
-Get statistic data of files in a directory, the result data will be an array of [RNFetchBlobStat](#user-content-rnfetchblobstat).
746
-
747
-```js
748
-RNFetchBlob.fs.lstat(PATH_OF_A_FOLDER)
749
-    .then((stats) => {})
750
-    .catch((err) => {})
751
-```
752
-
753
-#### stat(path:string):Promise<RNFetchBlobStat>
754
-
755
-Similar get statistic a data or a directory. the result data will be a [RNFetchBlobStat](#user-content-rnfetchblobstat).
756
-
757
-```js
758
-RNFetchBlob.fs.stat(PATH_OF_THE_TARGET)
759
-    .then((stats) => {})
760
-    .catch((err) => {})
761
-```
762
-
763
-#### scanFile(path:string):Promise (Androi Only)
764
-
765
-Connect `Media Scanner` and scan the file. see [Android Media Scanner, and Downloads App Support](#user-content-android-media-scanner-and-downloads-app-support) chapter for more information.
766
-
767
----
768
-
769
-## Types
770
-
771
-### RNFetchBlobConfig
772
-
773
-A set of configurations that will be injected into a `fetch` method, with the following properties.
774
-
775
-#### indicator:boolean
776
-  `0.5.6`
777
-  Set this property to `true` to display a network indicator on status bar, this feature is only supported on IOS.
778
-
779
-#### trusty:boolean
780
-  `0.5.3`
781
-  Set this property to `true` will allow the request create connection with server have self-signed SSL certification. This is not recommended to use in production.
782
-
783
-#### fileCache:boolean
784
-  Set this property to `true` will makes response data of the `fetch` stored in a temp file, by default the temp file will stored in App's own root folder with file name template `RNFetchBlob_tmp${timestamp}`.
785
-#### appendExt:string
786
-  Set this property to change temp file extension that created by `fetch` response data.
787
-#### path:string
788
-  When this property has value, `fetch` API will try to store response data in the path ignoring `fileCache` and `appendExt` property.
789
-#### addAndroidDownloads:object (Android only)
790
-  This is an Android only property, it should be an object with the following properties :
791
-  - title : title of the file
792
-  - description : File description of the file.
793
-  - mime : MIME type of the file. By default is `text/plain`
794
-  - mediaScannable : A `boolean` value, see [Officail Document](https://developer.android.com/reference/android/app/DownloadManager.html#addCompletedDownload(java.lang.String, java.lang.String, boolean, java.lang.String, java.lang.String, long, boolean))
795
-  - notification : A `boolean` value decide whether show a notification when download complete.
796
-
797
-### RNFetchBlobResponse
798
-
799
-When `fetch` success, it resolve a `FetchBlobResponse` object as first argument. `FetchBlobResponse` object has the following methods (these method are synchronous, so you might take quite a performance impact if the file is big)
800
-
801
-#### base64():string
802
-  returns base64 string of response data (done in native context)
803
-#### json():object
804
-  returns json parsed object (done in js context)
805
-#### text():string
806
-  returns decoded base64 string (done in js context)
807
-#### path():string
808
-  returns file path if the response data is cached in file
809
-#### session(name:string):RNFetchBlobSession
810
-  when the response data is cached in a file, this method adds the file into the session. The following usages are equivalent.
811
-```js
812
-RNFetchBlob.session('session-name').add(resp.path())
813
-// or
814
-resp.session('session-name')
815
-```
816
-
817
-### RNFetchBlobStat
818
-
819
-Statistic data of a file, see the following sample object.
820
-
821
-```js
822
-{
823
-    // file name
824
-    filename : 'foo.png',
825
-    // folder of the file or the folder itself
826
-    path : '/path/to/the/file/wihout/file/name/',
827
-    // size in byte
828
-    size : 4901,
829
-    // `file` or `directory`
830
-    type : 'file',
831
-    // last modified timestamp
832
-    lastModified : 141323298
833
-}
834
-```
835
-
836
-
837
-### RNFetchBlobSession
838
-
839
-A `session` is an object that helps you manage files. It simply maintains a list of file path and let you use `dispose()`to delete files in this session once and for all.
840
-
841
-#### add(path:string):RNFetchBlobSession
842
-  Add a file path to this session.
843
-#### remove(path:string):RNFetchBlobSession
844
-  Remove a file path from this session (not delete the file).
845
-#### list():Array<String>
846
-  Returns an array contains file paths in this session.
847
-#### dispose():Promise
848
-  Delete all files according to paths in the session.
849
-
850
-## Major Changes
536
+## Changes
851
 
537
 
852
 | Version | |
538
 | Version | |
853
 |---|---|
539
 |---|---|
540
+| 0.6.0 | Add readFile and writeFile API for easier file access, also added Android download manager support. |
854
 | 0.5.8 | Fix #33 PUT request will always be sent as POST on Android |
541
 | 0.5.8 | Fix #33 PUT request will always be sent as POST on Android |
855
 | 0.5.7 | Fix #31 #30 Xcode pre 7.3 build error |
542
 | 0.5.7 | Fix #31 #30 Xcode pre 7.3 build error |
856
 | 0.5.6 | Add support for IOS network status indicator. Fix file stream ASCII reader bug. |
543
 | 0.5.6 | Add support for IOS network status indicator. Fix file stream ASCII reader bug. |
860
 | 0.5.2 | Fix improper url params bug [#26](https://github.com/wkh237/react-native-fetch-blob/issues/26) and change IOS HTTP implementation from NSURLConnection to NSURLSession |
547
 | 0.5.2 | Fix improper url params bug [#26](https://github.com/wkh237/react-native-fetch-blob/issues/26) and change IOS HTTP implementation from NSURLConnection to NSURLSession |
861
 | 0.5.0 | Upload/download with direct access to file storage, and also added file access APIs |
548
 | 0.5.0 | Upload/download with direct access to file storage, and also added file access APIs |
862
 | 0.4.2 | Supports upload/download progress |
549
 | 0.4.2 | Supports upload/download progress |
863
-| 0.4.1 | Fixe upload form-data missing file extension problem on Android |
550
+| 0.4.1 | Fix upload form-data missing file extension problem on Android |
864
 | 0.4.0 | Add base-64 encode/decode library and API |
551
 | 0.4.0 | Add base-64 encode/decode library and API |
865
 | ~0.3.0 | Upload/Download octet-stream and form-data |
552
 | ~0.3.0 | Upload/Download octet-stream and form-data |
866
 
553
 
867
-### In Progress (v0.6.0)
868
-
869
-* Add `readFile` and `WriteFile` API to `fs`
870
-* Add file access API for direct access RNFetchBlobResponse when the response is a file path
871
-* Android Download Manager file download API
872
-
873
 ### Development
554
 ### Development
874
 
555
 
875
 If you're interested in hacking this module, check our [development guide](https://github.com/wkh237/react-native-fetch-blob/wiki/Home), there might be some helpful information.
556
 If you're interested in hacking this module, check our [development guide](https://github.com/wkh237/react-native-fetch-blob/wiki/Home), there might be some helpful information.

+ 1
- 1
src/package.json 查看文件

1
 {
1
 {
2
   "name": "react-native-fetch-blob",
2
   "name": "react-native-fetch-blob",
3
-  "version": "0.5.8",
3
+  "version": "0.6.0",
4
   "description": "A module provides upload, download, and files access API. Supports file stream read/write for process large files.",
4
   "description": "A module provides upload, download, and files access API. Supports file stream read/write for process large files.",
5
   "main": "index.js",
5
   "main": "index.js",
6
   "scripts": {
6
   "scripts": {