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 './@ohos.base'; 17import { Permissions } from './permissions'; 18import type _Context from './application/Context'; 19import type _PermissionRequestResult from './security/PermissionRequestResult'; 20 21/** 22 * @namespace abilityAccessCtrl 23 * @syscap SystemCapability.Security.AccessToken 24 * @since 8 25 */ 26declare namespace abilityAccessCtrl { 27 /** 28 * Obtains the AtManager instance. 29 * 30 * @returns { AtManager } Returns the instance of the AtManager. 31 * @syscap SystemCapability.Security.AccessToken 32 * @since 8 33 */ 34 /** 35 * Obtains the AtManager instance. 36 * 37 * @returns { AtManager } returns the instance of the AtManager. 38 * @syscap SystemCapability.Security.AccessToken 39 * @crossplatform 40 * @since 10 41 */ 42 function createAtManager(): AtManager; 43 44 /** 45 * Provides methods for managing access_token. 46 * 47 * @interface AtManager 48 * @syscap SystemCapability.Security.AccessToken 49 * @since 8 50 */ 51 interface AtManager { 52 /** 53 * Checks whether a specified application has been granted the given permission. 54 * 55 * @param { number } tokenID - Token ID of the application. 56 * @param { string } permissionName - Name of the permission to be verified. 57 * @returns { Promise<GrantStatus> } Returns permission verify result. 58 * @syscap SystemCapability.Security.AccessToken 59 * @since 8 60 * @deprecated since 9 61 * @useinstead ohos.abilityAccessCtrl.AtManager#checkAccessToken 62 */ 63 verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus>; 64 65 /** 66 * Checks whether a specified application has been granted the given permission. 67 * 68 * @param { number } tokenID - Token ID of the application. 69 * @param { Permissions } permissionName - Name of the permission to be verified. The Permissions type supports only valid permission names. 70 * @returns { Promise<GrantStatus> } Returns permission verify result. 71 * @syscap SystemCapability.Security.AccessToken 72 * @since 9 73 */ 74 verifyAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>; 75 76 /** 77 * Checks whether a specified application has been granted the given permission synchronously. 78 * 79 * @param { number } tokenID - Token ID of the application. 80 * @param { Permissions } permissionName - Name of the permission to be verified. 81 * @returns { GrantStatus } Returns permission verify result. 82 * @throws { BusinessError } 401 - The parameter check failed. 83 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 84 * @syscap SystemCapability.Security.AccessToken 85 * @since 9 86 */ 87 verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus; 88 89 /** 90 * Checks whether a specified application has been granted the given permission. 91 * 92 * @param { number } tokenID - Token ID of the application. 93 * @param { Permissions } permissionName - Name of the permission to be verified. 94 * @returns { Promise<GrantStatus> } Returns permission verify result. 95 * @throws { BusinessError } 401 - The parameter check failed. 96 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 97 * @syscap SystemCapability.Security.AccessToken 98 * @since 9 99 */ 100 /** 101 * Checks whether a specified application has been granted the given permission. 102 * On the cross-platform, this function can be used to check the permission grant status for the current application only. 103 * 104 * @param { number } tokenID - Token ID of the application. 105 * @param { Permissions } permissionName - Name of the permission to be verified. 106 * @returns { Promise<GrantStatus> } Returns permission verify result. 107 * @throws { BusinessError } 401 - The parameter check failed. 108 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 109 * @syscap SystemCapability.Security.AccessToken 110 * @crossplatform 111 * @since 10 112 */ 113 checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus>; 114 115 /** 116 * Checks whether a specified application has been granted the given permission. 117 * On the cross-platform, this function can be used to check the permission grant status for the current application only. 118 * 119 * @param { number } tokenID - Token ID of the application. 120 * @param { Permissions } permissionName - Name of the permission to be verified. 121 * @returns { GrantStatus } Returns permission verify result. 122 * @throws { BusinessError } 401 - The parameter check failed. 123 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 124 * @syscap SystemCapability.Security.AccessToken 125 * @crossplatform 126 * @since 10 127 */ 128 checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus; 129 130 /** 131 * Requests certain permissions from the user. 132 * 133 * @param { Context } context - The context that initiates the permission request. 134 * @param { Array<Permissions> } permissionList - Indicates the list of permissions to be requested. This parameter cannot be null or empty. 135 * @param { AsyncCallback<PermissionRequestResult> } requestCallback Callback for the result from requesting permissions. 136 * @throws { BusinessError } 401 - The parameter check failed. 137 * @throws { BusinessError } 12100001 - The parameter is invalid. The context is invalid when it does not belong to the application itself. 138 * @syscap SystemCapability.Security.AccessToken 139 * @StageModelOnly 140 * @since 9 141 */ 142 /** 143 * Requests certain permissions from the user. 144 * 145 * @param { Context } context - The context that initiates the permission request. 146 * @param { Array<Permissions> } permissionList - Indicates the list of permissions to be requested. This parameter cannot be null or empty. 147 * @param { AsyncCallback<PermissionRequestResult> } requestCallback Callback for the result from requesting permissions. 148 * @throws { BusinessError } 401 - The parameter check failed. 149 * @throws { BusinessError } 12100001 - The parameter is invalid. The context is invalid when it does not belong to the application itself. 150 * @syscap SystemCapability.Security.AccessToken 151 * @StageModelOnly 152 * @crossplatform 153 * @since 10 154 */ 155 requestPermissionsFromUser( 156 context: Context, 157 permissionList: Array<Permissions>, 158 requestCallback: AsyncCallback<PermissionRequestResult> 159 ): void; 160 161 /** 162 * Requests certain permissions from the user. 163 * 164 * @param { Context } context - The context that initiates the permission request. 165 * @param { Array<Permissions> } permissionList - Indicates the list of permissions to be requested. This parameter cannot be null or empty. 166 * @returns { Promise<PermissionRequestResult> } Returns result of requesting permissions. 167 * @throws { BusinessError } 401 - The parameter check failed. 168 * @throws { BusinessError } 12100001 - The parameter is invalid. The context is invalid when it does not belong to the application itself. 169 * @syscap SystemCapability.Security.AccessToken 170 * @StageModelOnly 171 * @since 9 172 */ 173 /** 174 * Requests certain permissions from the user. 175 * 176 * @param { Context } context - The context that initiates the permission request. 177 * @param { Array<Permissions> } permissionList - Indicates the list of permissions to be requested. This parameter cannot be null or empty. 178 * @returns { Promise<PermissionRequestResult> } Returns result of requesting permissions. 179 * @throws { BusinessError } 401 - The parameter check failed. 180 * @throws { BusinessError } 12100001 - The parameter is invalid. The context is invalid when it does not belong to the application itself. 181 * @syscap SystemCapability.Security.AccessToken 182 * @StageModelOnly 183 * @crossplatform 184 * @since 10 185 */ 186 requestPermissionsFromUser(context: Context, permissionList: Array<Permissions>): Promise<PermissionRequestResult>; 187 188 /** 189 * Grants a specified user_grant permission to the given application. 190 * 191 * @permission ohos.permission.GRANT_SENSITIVE_PERMISSIONS 192 * @param { number } tokenID - Token ID of the application. 193 * @param { Permissions } permissionName - Name of the permission to be granted. 194 * @param { number } permissionFlags - Flags of permission state. 195 * @returns { Promise<void> } The promise returned by the function. 196 * @throws { BusinessError } 401 - The parameter check failed. 197 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS". 198 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 199 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, 200 * or the flags value is invalid. 201 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 202 * @throws { BusinessError } 12100003 - The specified permission does not exist. 203 * @throws { BusinessError } 12100006 - The application specified by the tokenID is not allowed to be granted with the specified permission. 204 * Either the application is a sandbox or the tokenID is from a remote device. 205 * @throws { BusinessError } 12100007 - Service is abnormal. 206 * @syscap SystemCapability.Security.AccessToken 207 * @systemapi 208 * @since 8 209 */ 210 grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>; 211 212 /** 213 * Grants a specified user_grant permission to the given application. 214 * 215 * @permission ohos.permission.GRANT_SENSITIVE_PERMISSIONS 216 * @param { number } tokenID - Token ID of the application. 217 * @param { Permissions } permissionName - Name of the permission to be granted. 218 * @param { number } permissionFlags - Flags of permission state. 219 * @param { AsyncCallback<void> } callback - Asynchronous callback interface. 220 * @throws { BusinessError } 401 - The parameter check failed. 221 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.GRANT_SENSITIVE_PERMISSIONS". 222 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 223 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, 224 * or the flags value is invalid. 225 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 226 * @throws { BusinessError } 12100003 - The specified permission does not exist. 227 * @throws { BusinessError } 12100006 - The application specified by the tokenID is not allowed to be granted with the specified permission. 228 * Either the application is a sandbox or the tokenID is from a remote device. 229 * @throws { BusinessError } 12100007 - Service is abnormal. 230 * @syscap SystemCapability.Security.AccessToken 231 * @systemapi 232 * @since 8 233 */ 234 grantUserGrantedPermission( 235 tokenID: number, 236 permissionName: Permissions, 237 permissionFlags: number, 238 callback: AsyncCallback<void> 239 ): void; 240 241 /** 242 * Revoke a specified user_grant permission to the given application. 243 * 244 * @permission ohos.permission.REVOKE_SENSITIVE_PERMISSIONS 245 * @param { number } tokenID - Token ID of the application. 246 * @param { Permissions } permissionName - Name of the permission to be revoked. 247 * @param { number } permissionFlags - Flags of permission state. 248 * @returns { Promise<void> } The promise returned by the function. 249 * @throws { BusinessError } 401 - The parameter check failed. 250 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS". 251 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 252 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, 253 * or the flags value is invalid. 254 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 255 * @throws { BusinessError } 12100003 - The specified permission does not exist. 256 * @throws { BusinessError } 12100006 - The application specified by the tokenID is not allowed to be revoked with the specified permission. 257 * Either the application is a sandbox or the tokenID is from a remote device. 258 * @throws { BusinessError } 12100007 - Service is abnormal. 259 * @syscap SystemCapability.Security.AccessToken 260 * @systemapi 261 * @since 8 262 */ 263 revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise<void>; 264 265 /** 266 * Revoke a specified user_grant permission to the given application. 267 * 268 * @permission ohos.permission.REVOKE_SENSITIVE_PERMISSIONS 269 * @param { number } tokenID - Token ID of the application. 270 * @param { Permissions } permissionName - Name of the permission to be revoked. 271 * @param { number } permissionFlags - Flags of permission state. 272 * @param { AsyncCallback<void> } callback - Asynchronous callback interface. 273 * @throws { BusinessError } 401 - The parameter check failed. 274 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.REVOKE_SENSITIVE_PERMISSIONS". 275 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 276 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, 277 * or the flags value is invalid. 278 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 279 * @throws { BusinessError } 12100003 - The specified permission does not exist. 280 * @throws { BusinessError } 12100006 - The application specified by the tokenID is not allowed to be revoked with the specified permission. 281 * Either the application is a sandbox or the tokenID is from a remote device. 282 * @throws { BusinessError } 12100007 - Service is abnormal. 283 * @syscap SystemCapability.Security.AccessToken 284 * @systemapi 285 * @since 8 286 */ 287 revokeUserGrantedPermission( 288 tokenID: number, 289 permissionName: Permissions, 290 permissionFlags: number, 291 callback: AsyncCallback<void> 292 ): void; 293 294 /** 295 * Queries specified permission flags of the given application. 296 * 297 * @permission ohos.permission.GET_SENSITIVE_PERMISSIONS or ohos.permission.GRANT_SENSITIVE_PERMISSIONS or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS 298 * @param { number } tokenID - Token ID of the application. 299 * @param { Permissions } permissionName - Name of the permission to be get. 300 * @returns { Promise<number> } Return permission flags. 301 * @throws { BusinessError } 401 - The parameter check failed. 302 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission specified below. 303 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 304 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 305 * @throws { BusinessError } 12100002 - The specified tokenID does not exist. 306 * @throws { BusinessError } 12100003 - The specified permission does not exist. 307 * @throws { BusinessError } 12100006 - The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device. 308 * @throws { BusinessError } 12100007 - Service is abnormal. 309 * @syscap SystemCapability.Security.AccessToken 310 * @systemapi 311 * @since 8 312 */ 313 getPermissionFlags(tokenID: number, permissionName: Permissions): Promise<number>; 314 315 /** 316 * Queries permission management version. 317 * 318 * @returns { Promise<number> } Return permission version. 319 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 320 * @syscap SystemCapability.Security.AccessToken 321 * @systemapi 322 * @since 9 323 */ 324 getVersion(): Promise<number>; 325 326 /** 327 * Registers a permission state callback so that the application can be notified upon specified permission state of specified applications changes. 328 * 329 * @permission ohos.permission.GET_SENSITIVE_PERMISSIONS 330 * @param { 'permissionStateChange' } type - Event type. 331 * @param { Array<number> } tokenIDList - A list of permissions that specify the permissions to be listened on. The value in the list can be: 332 * <ul> 333 * <li>{@code empty} - Indicates that the application can be notified if the specified permission state of any applications changes. 334 * </li> 335 * <li>{@code non-empty} - Indicates that the application can only be notified if the specified 336 * permission state of the specified applications change. 337 * </li> 338 * </ul> 339 * @param { Array<Permissions> } permissionList - A list of permissions that specify the permissions to be listened on. The value in the list can be: 340 * <ul> 341 * <li>{@code empty} - Indicates that the application can be notified if any permission state of the specified applications changes. 342 * </li> 343 * <li>{@code non-empty} - Indicates that the application can only be notified if the specified 344 * permission state of the specified applications changes. 345 * </li> 346 * </ul> 347 * @param { Callback<PermissionStateChangeInfo> } callback - Callback for the result from registering permissions. 348 * @throws { BusinessError } 401 - The parameter check failed. 349 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS". 350 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 351 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. 352 * @throws { BusinessError } 12100004 - The interface is called repeatedly with the same input. 353 * @throws { BusinessError } 12100005 - The registration time has exceeded the limitation. 354 * @throws { BusinessError } 12100007 - Service is abnormal. 355 * @throws { BusinessError } 12100008 - Out of memory. 356 * @syscap SystemCapability.Security.AccessToken 357 * @systemapi 358 * @since 9 359 */ 360 on( 361 type: 'permissionStateChange', 362 tokenIDList: Array<number>, 363 permissionList: Array<Permissions>, 364 callback: Callback<PermissionStateChangeInfo> 365 ): void; 366 367 /** 368 * Unregisters a permission state callback so that the specified applications cannot be notified upon specified permissions state changes anymore. 369 * 370 * @permission ohos.permission.GET_SENSITIVE_PERMISSIONS 371 * @param { 'permissionStateChange' } type - Event type. 372 * @param { Array<number> } tokenIDList - A list of permissions that specify the permissions to be listened on. 373 * It should correspond to the value registered by function of "on", whose type is "permissionStateChange". 374 * @param { Array<Permissions> } permissionList - A list of permissions that specify the permissions to be listened on. 375 * It should correspond to the value registered by function of "on", whose type is "permissionStateChange". 376 * @param { Callback<PermissionStateChangeInfo> } callback - Callback for the result from unregistering permissions. 377 * @throws { BusinessError } 401 - The parameter check failed. 378 * @throws { BusinessError } 201 - Permission denied. Interface caller does not have permission "ohos.permission.GET_SENSITIVE_PERMISSIONS". 379 * @throws { BusinessError } 202 - Not System App. Interface caller is not a system app. 380 * @throws { BusinessError } 12100001 - The parameter is invalid. The tokenIDs or permissionNames in the list are all invalid. 381 * @throws { BusinessError } 12100004 - The interface is not used together with "on". 382 * @throws { BusinessError } 12100007 - Service is abnormal. 383 * @throws { BusinessError } 12100008 - Out of memory. 384 * @syscap SystemCapability.Security.AccessToken 385 * @systemapi 386 * @since 9 387 */ 388 off( 389 type: 'permissionStateChange', 390 tokenIDList: Array<number>, 391 permissionList: Array<Permissions>, 392 callback?: Callback<PermissionStateChangeInfo> 393 ): void; 394 } 395 396 /** 397 * GrantStatus. 398 * 399 * @enum { number } 400 * @syscap SystemCapability.Security.AccessToken 401 * @since 8 402 */ 403 /** 404 * GrantStatus. 405 * 406 * @enum { number } 407 * @syscap SystemCapability.Security.AccessToken 408 * @crossplatform 409 * @since 10 410 */ 411 export enum GrantStatus { 412 /** 413 * access_token permission check fail 414 * 415 * @syscap SystemCapability.Security.AccessToken 416 * @since 8 417 */ 418 /** 419 * access_token permission check fail 420 * 421 * @syscap SystemCapability.Security.AccessToken 422 * @crossplatform 423 * @since 10 424 */ 425 PERMISSION_DENIED = -1, 426 /** 427 * access_token permission check success 428 * 429 * @syscap SystemCapability.Security.AccessToken 430 * @since 8 431 */ 432 /** 433 * access_token permission check success 434 * 435 * @syscap SystemCapability.Security.AccessToken 436 * @crossplatform 437 * @since 10 438 */ 439 PERMISSION_GRANTED = 0 440 } 441 442 /** 443 * Enum for permission state change type. 444 * 445 * @enum { number } 446 * @syscap SystemCapability.Security.AccessToken 447 * @systemapi 448 * @since 9 449 */ 450 export enum PermissionStateChangeType { 451 /** 452 * A granted user_grant permission is revoked. 453 * 454 * @syscap SystemCapability.Security.AccessToken 455 * @systemapi 456 * @since 9 457 */ 458 PERMISSION_REVOKED_OPER = 0, 459 /** 460 * A user_grant permission is granted. 461 * 462 * @syscap SystemCapability.Security.AccessToken 463 * @systemapi 464 * @since 9 465 */ 466 PERMISSION_GRANTED_OPER = 1 467 } 468 469 /** 470 * Indicates the information of permission state change. 471 * 472 * @interface PermissionStateChangeInfo 473 * @syscap SystemCapability.Security.AccessToken 474 * @systemapi 475 * @since 9 476 * @name PermissionStateChangeInfo 477 */ 478 interface PermissionStateChangeInfo { 479 /** 480 * Indicates the permission state change type. 481 * 482 * @type { PermissionStateChangeType } 483 * @syscap SystemCapability.Security.AccessToken 484 * @systemapi 485 * @since 9 486 */ 487 change: PermissionStateChangeType; 488 489 /** 490 * Indicates the application whose permission state has been changed. 491 * 492 * @type { number } 493 * @syscap SystemCapability.Security.AccessToken 494 * @systemapi 495 * @since 9 496 */ 497 tokenID: number; 498 499 /** 500 * Indicates the permission whose state has been changed. 501 * 502 * @type { Permissions } 503 * @syscap SystemCapability.Security.AccessToken 504 * @systemapi 505 * @since 9 506 */ 507 permissionName: Permissions; 508 } 509} 510 511export default abilityAccessCtrl; 512export { Permissions }; 513export type PermissionRequestResult = _PermissionRequestResult; 514export type Context = _Context; 515