Skip to content

Commit 40ab3bc

Browse files
sgnyMoOx
sgny
authored and
MoOx
committed
PermissionsAndroid: Add documentation (#549)
1 parent 2fbfea4 commit 40ab3bc

3 files changed

Lines changed: 103 additions & 120 deletions

File tree

‎reason-react-native/src/apis/PermissionsAndroid.md‎

Lines changed: 101 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,138 @@
11
---
22
id: apis/PermissionsAndroid
33
title: PermissionsAndroid
4-
wip: true
4+
officialDoc: https://facebook.github.io/react-native/docs/permissionsandroid
55
---
66

7-
```reason
8-
module Permission: {
9-
type t;
10-
11-
[@bs.module "react-native"]
12-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
13-
external readCalendar: t = "READ_CALENDAR";
14-
15-
[@bs.module "react-native"]
16-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
17-
external writeCalendar: t = "WRITE_CALENDAR";
18-
19-
[@bs.module "react-native"]
20-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
21-
external camera: t = "CAMERA";
22-
23-
[@bs.module "react-native"]
24-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
25-
external readContacts: t = "READ_CONTACTS";
7+
Only for projects supporting Native Code. Requires the project to have been
8+
created using `react-native init` or ejected afterwards if created using
9+
`expo init` or `create-react-native-app`.
2610

27-
[@bs.module "react-native"]
28-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
29-
external writeContacts: t = "WRITE_CONTACTS";
11+
`PermissionsAndroid` provides access to the permissions model avaiable since
12+
`Android M`. While certain permissions are granted by default as long as they
13+
are listed in `AndroidManifest.xml`, _dangerous_ permissions require a dialog.
14+
This API will allow you to manage such permissions.
3015

31-
[@bs.module "react-native"]
32-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
33-
external getAccounts: t = "GET_ACCOUNTS";
16+
## Types
3417

35-
[@bs.module "react-native"]
36-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
37-
external accessFineLocation: t = "ACCESS_FINE_LOCATION";
18+
### `Permission.t`
3819

39-
[@bs.module "react-native"]
40-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
41-
external accessCoarseLocation: t = "ACCESS_COARSE_LOCATION";
20+
Type for permissions that may be granted to the app. Available permissions are:
4221

43-
[@bs.module "react-native"]
44-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
45-
external recordAudio: t = "RECORD_AUDIO";
46-
47-
[@bs.module "react-native"]
48-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
49-
external readPhoneState: t = "READ_PHONE_STATE";
22+
```reason
23+
Permission.readCalendar
24+
Permission.writeCalendar
25+
Permission.camera
26+
Permission.readContacts
27+
Permission.writeContacts
28+
Permission.getAccounts
29+
Permission.accessFineLocation
30+
Permission.accessCoarseLocation
31+
Permission.recordAudio
32+
Permission.readPhoneState
33+
Permission.callPhone
34+
Permission.readCallLog
35+
Permission.writeCallLog
36+
Permission.addVoicemail
37+
Permission.useSip
38+
Permission.processOutgoingCalls
39+
Permission.bodySensors
40+
Permission.sendSms
41+
Permission.receiveSms
42+
Permission.readSms
43+
Permission.receiveWapPush
44+
Permission.receiveMms
45+
Permission.readExternalStorage
46+
Permission.writeExternalStorage
47+
```
5048

51-
[@bs.module "react-native"]
52-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
53-
external callPhone: t = "CALL_PHONE";
49+
### `Result.t`
5450

55-
[@bs.module "react-native"]
56-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
57-
external readCallLog: t = "READ_CALL_LOG";
51+
Type for the result of a request for some permission. Possible results are:
5852

59-
[@bs.module "react-native"]
60-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
61-
external writeCallLog: t = "WRITE_CALL_LOG";
53+
```reason
54+
Result.granted
55+
Result.denied
56+
Result.neverAskAgain
57+
```
6258

63-
[@bs.module "react-native"]
64-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
65-
external addVoicemail: t = "ADD_VOICEMAIL";
59+
### `rationale`
6660

67-
[@bs.module "react-native"]
68-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
69-
external useSip: t = "USE_SIP";
61+
To be used with the [`requestWithRationale`](#requestwithrationale) method. May
62+
be created by the constructor of the same name.
7063

71-
[@bs.module "react-native"]
72-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
73-
external processOutgoingCalls: t = "PROCESS_OUTGOING_CALLS";
64+
```reason
65+
rationale:
66+
(
67+
~title: string,
68+
~message: string,
69+
~buttonPositive: string,
70+
~buttonNegative: string=?,
71+
~buttonNeutral: string=?,
72+
unit
73+
) =>
74+
rationale
75+
```
7476

75-
[@bs.module "react-native"]
76-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
77-
external bodySensors: t = "BODY_SENSORS";
77+
where
7878

79-
[@bs.module "react-native"]
80-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
81-
external sendSms: t = "SEND_SMS";
79+
- `title` is the title of the dialog,
80+
- `message` is the message of the dialog,
81+
- `buttonPositive` is the text of the positive button,
82+
- `buttonNegative` is the text of the negative button (optional), and
83+
- `buttonNeutral` is the text of the neutral button (optional).
8284

83-
[@bs.module "react-native"]
84-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
85-
external receiveSms: t = "RECEIVE_SMS";
85+
### `dict`
8686

87-
[@bs.module "react-native"]
88-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
89-
external readSms: t = "READ_SMS";
87+
An extension of the `Js.Dict.t` type to allow keys of type `Permission.t`.
88+
Values of keys may be accessed by the [`get`](#get) method.
9089

91-
[@bs.module "react-native"]
92-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
93-
external receiveWapPush: t = "RECEIVE_WAP_PUSH";
90+
## Methods
9491

95-
[@bs.module "react-native"]
96-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
97-
external receiveMms: t = "RECEIVE_MMS";
92+
### `check`
9893

99-
[@bs.module "react-native"]
100-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
101-
external readExternalStorage: t = "READ_EXTERNAL_STORAGE";
94+
Method to check whether the specified permission has been granted to the app,
95+
returns a `bool` wrapped in a promise.
10296

103-
[@bs.module "react-native"]
104-
[@bs.scope ("PermissionsAndroid", "PERMISSIONS")]
105-
external writeExternalStorage: t = "WRITE_EXTERNAL_STORAGE";
106-
};
97+
```reason
98+
check: Permission.t => Js.Promise.t(bool)
99+
```
107100

108-
module Result: {
109-
type t;
101+
### `request`
110102

111-
[@bs.module "react-native"] [@bs.scope ("PermissionsAndroid", "RESULTS")]
112-
external granted: t = "GRANTED";
103+
Method to request the specified permission, returns `Result.t` wrapped in a
104+
promise.
113105

114-
[@bs.module "react-native"] [@bs.scope ("PermissionsAndroid", "RESULTS")]
115-
external denied: t = "DENIED";
106+
```reason
107+
request: Permission.t => Js.Promise.t(Result.t)
108+
```
116109

117-
[@bs.module "react-native"] [@bs.scope ("PermissionsAndroid", "RESULTS")]
118-
external neverAskAgain: t = "NEVER_ASK_AGAIN";
119-
};
110+
### `requestWithRationale`
120111

121-
type rationale;
122-
[@bs.obj]
123-
external rationale:
124-
(
125-
~title: string,
126-
~message: string,
127-
~buttonPositive: string,
128-
~buttonNegative: string=?,
129-
~buttonNeutral: string=?,
130-
unit
131-
) =>
132-
rationale =
133-
"";
112+
Method to request the specified permission with a rationale, returns `Result.t`
113+
wrapped in a promise. It is advised to provide a rationale if users have
114+
previously turned off the permission. Rationale will be presented to the user
115+
only when necessary. For further information, please refer to the
116+
[official Android documentation](https://developer.android.com/training/permissions/requesting.html#explain).
134117

135-
type dict;
118+
```reason
119+
requestWithRationale: (Permission.t, rationale) => Js.Promise.t(Result.t)
120+
```
136121

137-
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]
138-
external check: Permission.t => Js.Promise.t(bool) = "check";
122+
### `requestMultiple`
139123

140-
// multiple externals
141-
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]
142-
external request: Permission.t => Js.Promise.t(Result.t) = "";
124+
Method to request multiple permissions within the same dialog prompted to the
125+
user, returns [`dict`](#dict) wrapped in a promise.
143126

144-
// multiple externals
145-
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]
146-
external requestWithRationale:
147-
(Permission.t, rationale) => Js.Promise.t(Result.t) =
148-
"request";
127+
```reason
128+
requestMultiple: array(Permission.t) => Js.Promise.t(dict)
129+
```
149130

150-
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]
151-
external requestMultiple: array(Permission.t) => Js.Promise.t(dict) = "";
131+
### `get`
152132

153-
[@bs.get_index] external get: (dict, Permission.t) => option(Result.t) = "";
133+
Getter method to access value of the specified permission in the [`dict`](#dict)
134+
object returned by the `requestMultiple` method.
154135

136+
```reason
137+
get: (dict, Permission.t) => option(Result.t)
155138
```

‎reason-react-native/src/apis/PermissionsAndroid.re‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ external rationale:
128128
type dict = Js.Dict.t(Result.t);
129129

130130
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]
131-
external check: Permission.t => Js.Promise.t(bool) = "check";
131+
external check: Permission.t => Js.Promise.t(bool) = "";
132132

133133
// multiple externals
134134
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]

‎reason-react-native/src/apis/PermissionsAndroid.rei‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ external rationale:
128128
type dict;
129129

130130
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]
131-
external check: Permission.t => Js.Promise.t(bool) = "check";
131+
external check: Permission.t => Js.Promise.t(bool) = "";
132132

133133
// multiple externals
134134
[@bs.scope "PermissionsAndroid"] [@bs.module "react-native"]

0 commit comments

Comments
 (0)