1/* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16import { AsyncCallback, Callback } from './basic'; 17import { Permissions } from './permissions'; 18import Context from "./application/Context"; 19import PermissionRequestResult from "./security/PermissionRequestResult"; 20 21/** 22 * @syscap SystemCapability.Security.AccessToken 23 */ 24 declare namespace abilityAccessCtrl { 25 /** 26 * Obtains the AtManager instance. 27 * @returns returns the instance of the AtManager. 28 * @since 8 29 */ 30 function createAtManager(): AtManager; 31 32 /** 33 * Provides methods for managing access_token. 34 * @name AtManager 35 */ 36 interface AtManager { 37 /** 38 * Checks whether a specified application has been granted the given permission. 39 * @param tokenID The tokenId of specified application. 40 * @param permissionName The permission name to be verified. 41 * @returns Returns permission verify result. 42 * @since 8 43 * @deprecated since 9 44 * @useinstead ohos.abilityAccessCtrl.AtManager#checkAccessToken 45 */ 46 verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus>; 47 48 /** 49 * Checks whether a specified application has been granted the given permission. 50 * @param tokenID The tokenId of specified application. 51 * @param permissionName The permission name to be verified. Permissions type only support the valid permission name. 52 * @returns Returns permission verify result. 53 * @since 9 54 */ 55 verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>; 56 57 /** 58 * Checks whether a specified application has been granted the given permission synchronously. 59 * @param tokenID The tokenId of specified application. 60 * @param permissionName The permission name to be verified. 61 * @throws { BusinessError } 401 - The parameter check failed. 62 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 63 * @returns Returns permission verify result. 64 * @since 9 65 */ 66 verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus; 67 68 /** 69 * Checks whether a specified application has been granted the given permission. 70 * @param tokenID The tokenId of specified application. 71 * @param permissionName The permission name to be verified. 72 * @throws { BusinessError } 401 - The parameter check failed. 73 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 74 * @returns Returns permission verify result. 75 * @since 9 76 */ 77 checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>; 78 79 /** 80 * Requests certain permissions from the user. 81 * 82 * @param context The context that initiates the permission request. 83 * @param permissionList Indicates the list of permissions to be requested. This parameter cannot be null or empty. 84 * @returns Returns the {@link PermissionRequestResult}. 85 * @throws { BusinessError } 401 - The parameter check failed. 86 * @throws { BusinessError } 12100001 - The parameter is invalid. The context is invalid when it does not belong to the application itself. 87 * @since 9 88 * @StageModelOnly 89 */ 90 requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>, requestCallback: AsyncCallback<PermissionRequestResult>) : void; 91 requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>) : Promise<PermissionRequestResult>; 92 93 /** 94 * Grants a specified user_grant permission to the given application. 95 * @param tokenID The tokenId of specified application. 96 * @param permissionName The permission name to be granted. 97 * @param permissionFlags Flags of permission state. 98 * @returns { void | Promise<void> } No callback return Promise otherwise return void. 99 * @throws { BusinessError } 401 - The parameter check failed. 100 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS". 101 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. 102 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 103 * @throws { BusinessError } 12100003 - The specified permission does not exist. 104 * @throws { BusinessError } 12100006 - The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. 105 * @throws { BusinessError } 12100007 - Service is abnormal. 106 * @permission ohos.permission.GRANT_SENSITIVE_PERMISSIONS 107 * @systemapi 108 * @since 8 109 */ 110 grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>; 111 grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void; 112 113 /** 114 * Revoke a specified user_grant permission to the given application. 115 * @param tokenID The tokenId of specified application. 116 * @param permissionName The permission name to be revoked. 117 * @param permissionFlags Flags of permission state. 118 * @returns { void | Promise<void> } No callback return Promise otherwise return void. 119 * @throws { BusinessError } 401 - The parameter check failed. 120 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS". 121 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. 122 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 123 * @throws { BusinessError } 12100003 - The specified permission does not exist. 124 * @throws { BusinessError } 12100006 - The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. 125 * @throws { BusinessError } 12100007 - Service is abnormal. 126 * @permission ohos.permission.REVOKE_SENSITIVE_PERMISSIONS 127 * @systemapi 128 * @since 8 129 */ 130 revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>; 131 revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback<void>): void; 132 133 /** 134 * Queries specified permission flags of the given application. 135 * @param tokenID The tokenId of specified application. 136 * @param permissionName The permission name to be granted. 137 * @returns Return permission flags. 138 * @throws { BusinessError } 401 - The parameter check failed. 139 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission specified below. 140 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 141 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 142 * @throws { BusinessError } 12100003 - The specified permission does not exist. 143 * @throws { BusinessError } 12100006 - The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device. 144 * @throws { BusinessError } 12100007 - Service is abnormal. 145 * @permission ohos.permission.GET_SENSITIVE_PERMISSIONS or ohos.permission.GRANT_SENSITIVE_PERMISSIONS or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS 146 * @systemapi 147 * @since 8 148 */ 149 getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number>; 150 151 /** 152 * Queries permission management version. 153 * @returns Return permission version. 154 * @systemapi 155 * @since 9 156 */ 157 getVersion(): Promise<number>; 158 159 /** 160 * Registers a permission state callback so that the application can be notified upon specified permission state of specified applications changes. 161 * @param tokenIDList A list of tokenIds that specifies the applications to be listened on. The value in the list can be: 162 * <ul> 163 * <li>{@code empty} - Indicates that the application can be notified if the specified permission state of any applications changes. 164 * </li> 165 * <li>{@code non-empty} - Indicates that the application can only be notified if the specified permission state of the specified applications change. 166 * </li> 167 * </ul> 168 * @param permissionList A list of permissions that specifies the permissions to be listened on. The value in the list can be: 169 * <ul> 170 * <li>{@code empty} - Indicates that the application can be notified if any permission state of the specified applications changes. 171 * </li> 172 * <li>{@code non-empty} - Indicates that the application can only be notified if the specified permission state of the specified applications changes. 173 * </li> 174 * </ul> 175 * @param callback Callback used to listen for the permission state changed event. 176 * @throws { BusinessError } 401 - The parameter check failed. 177 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS". 178 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 179 * @throws { BusinessError } 12100004 - The interface is called repeatedly with the same input. 180 * @throws { BusinessError } 12100005 - The registration time has exceeded the limitation. 181 * @throws { BusinessError } 12100007 - Service is abnormal. 182 * @throws { BusinessError } 12100008 - Out of memory. 183 * @permission ohos.permission.GET_SENSITIVE_PERMISSIONS 184 * @systemapi 185 * @since 9 186 */ 187 on(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback: Callback<PermissionStateChangeInfo>): void; 188 189 /** 190 * Unregisters a permission state callback so that the specified applications cannot be notified upon specified permissions state changes anymore. 191 * @param tokenIDList A list of tokenIds that specifies the applications being listened on. it should correspond to the value registered by function of "on", whose type is "permissionStateChange". 192 * @param permissionList A list of permissions that specifies the permissions being listened on. it should correspond to the value registered by function of "on", whose type is "permissionStateChange". 193 * @param callback Callback used to listen for the permission state changed event. 194 * @throws { BusinessError } 401 - The parameter check failed. 195 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS". 196 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID in list is all invalid, or the permissionName in list is all invalid. 197 * @throws { BusinessError } 12100004 - The interface is not used together with "on". 198 * @throws { BusinessError } 12100007 - Service is abnormal. 199 * @throws { BusinessError } 12100008 - Out of memory. 200 * @permission ohos.permission.GET_SENSITIVE_PERMISSIONS 201 * @systemapi 202 * @since 9 203 */ 204 off(type: 'permissionStateChange', tokenIDList: Array<number>, permissionList: Array<Permissions>, callback?: Callback<PermissionStateChangeInfo>): void; 205 } 206 207 /** 208 * GrantStatus. 209 * @since 8 210 */ 211 export enum GrantStatus { 212 /** 213 * access_token permission check fail 214 */ 215 PERMISSION_DENIED = -1, 216 /** 217 * access_token permission check success 218 */ 219 PERMISSION_GRANTED = 0, 220 } 221 222 /** 223 * Enum for permission state change type. 224 * @systemapi 225 * @since 9 226 */ 227 export enum PermissionStateChangeType { 228 /** 229 * A granted user_grant permission is revoked. 230 */ 231 PERMISSION_REVOKED_OPER = 0, 232 /** 233 * A user_grant permission is granted. 234 */ 235 PERMISSION_GRANTED_OPER = 1, 236 } 237 238 /** 239 * Indicates the information of permission state change. 240 * @name PermissionStateChangeInfo 241 * @systemapi 242 * @since 9 243 */ 244 interface PermissionStateChangeInfo { 245 /** 246 * Indicates the permission state change type. 247 */ 248 change: PermissionStateChangeType; 249 250 /** 251 * Indicates the application whose permission state has been changed. 252 */ 253 tokenID: number; 254 255 /** 256 * Indicates the permission whose state has been changed. 257 */ 258 permissionName: Permissions; 259 } 260 } 261 262 export default abilityAccessCtrl; 263 export { Permissions };