1/* 2 * Copyright (c) 2022-2023 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 16/** 17 * @file 18 * @kit AbilityKit 19 */ 20 21import { AsyncCallback, Callback } from './@ohos.base'; 22import Want from './@ohos.app.ability.Want'; 23import { WantAgentInfo as _WantAgentInfo } from './wantAgent/wantAgentInfo'; 24import { TriggerInfo as _TriggerInfo } from './wantAgent/triggerInfo'; 25 26/** 27 * Provide the method obtain trigger, cancel, and compare and to obtain 28 * the bundle name, UID of an {@link WantAgent} object. 29 * 30 * @namespace wantAgent 31 * @syscap SystemCapability.Ability.AbilityRuntime.Core 32 * @since 9 33 */ 34declare namespace wantAgent { 35 /** 36 * Obtains the bundle name of a WantAgent. 37 * 38 * @param { WantAgent } agent - Indicates the WantAgent. 39 * @param { AsyncCallback<string> } callback - The callback is used to return the bundle name. 40 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 41 * 2. Incorrect parameter types. 42 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 43 * @throws { BusinessError } 16000151 - Invalid wantagent object. 44 * @syscap SystemCapability.Ability.AbilityRuntime.Core 45 * @since 9 46 */ 47 function getBundleName(agent: WantAgent, callback: AsyncCallback<string>): void; 48 49 /** 50 * Obtains the bundle name of a WantAgent. 51 * 52 * @param { WantAgent } agent - Indicates the WantAgent. 53 * @returns { Promise<string> } Returns the bundle name. 54 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 55 * 2. Incorrect parameter types. 56 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 57 * @throws { BusinessError } 16000151 - Invalid wantagent object. 58 * @syscap SystemCapability.Ability.AbilityRuntime.Core 59 * @since 9 60 */ 61 function getBundleName(agent: WantAgent): Promise<string>; 62 63 /** 64 * Obtains the UID of a WantAgent. 65 * 66 * @param { WantAgent } agent - Indicates the WantAgent. 67 * @param { AsyncCallback<number> } callback - The callback is used to return the UID. 68 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 69 * 2. Incorrect parameter types. 70 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 71 * @throws { BusinessError } 16000151 - Invalid wantagent object. 72 * @syscap SystemCapability.Ability.AbilityRuntime.Core 73 * @since 9 74 */ 75 function getUid(agent: WantAgent, callback: AsyncCallback<number>): void; 76 77 /** 78 * Obtains the UID of a WantAgent. 79 * 80 * @param { WantAgent } agent - Indicates the WantAgent. 81 * @returns { Promise<number> } Returns the UID. 82 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 83 * 2. Incorrect parameter types. 84 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 85 * @throws { BusinessError } 16000151 - Invalid wantagent object. 86 * @syscap SystemCapability.Ability.AbilityRuntime.Core 87 * @since 9 88 */ 89 function getUid(agent: WantAgent): Promise<number>; 90 91 /** 92 * Obtains the {@link Want} of an {@link WantAgent}. 93 * 94 * @param { WantAgent } agent - Indicates the WantAgent. 95 * @param { AsyncCallback<Want> } callback - The callback is used to return the Want. 96 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 97 * 2. Incorrect parameter types. 98 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 99 * @throws { BusinessError } 16000015 - Service timeout. 100 * @throws { BusinessError } 16000151 - Invalid wantagent object. 101 * @syscap SystemCapability.Ability.AbilityRuntime.Core 102 * @systemapi 103 * @since 9 104 */ 105 function getWant(agent: WantAgent, callback: AsyncCallback<Want>): void; 106 107 /** 108 * Obtains the {@link Want} of an {@link WantAgent}. 109 * 110 * @param { WantAgent } agent - Indicates the WantAgent. 111 * @returns { Promise<Want> } Returns the Want. 112 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 113 * 2. Incorrect parameter types. 114 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 115 * @throws { BusinessError } 16000015 - Service timeout. 116 * @throws { BusinessError } 16000151 - Invalid wantagent object. 117 * @syscap SystemCapability.Ability.AbilityRuntime.Core 118 * @systemapi 119 * @since 9 120 */ 121 function getWant(agent: WantAgent): Promise<Want>; 122 123 /** 124 * Cancel a WantAgent. Only the application that creates the WantAgent can cancel it. 125 * 126 * @param { WantAgent } agent - Indicates the WantAgent. 127 * @param { AsyncCallback<void> } callback - The callback of cancel. 128 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 129 * 2. Incorrect parameter types. 130 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 131 * @throws { BusinessError } 16000151 - Invalid wantagent object. 132 * @syscap SystemCapability.Ability.AbilityRuntime.Core 133 * @since 9 134 */ 135 function cancel(agent: WantAgent, callback: AsyncCallback<void>): void; 136 137 /** 138 * Cancel a WantAgent. Only the application that creates the WantAgent can cancel it. 139 * 140 * @param { WantAgent } agent - Indicates the WantAgent. 141 * @returns { Promise<void> } The promise returned by the function. 142 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 143 * 2. Incorrect parameter types. 144 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 145 * @throws { BusinessError } 16000151 - Invalid wantagent object. 146 * @syscap SystemCapability.Ability.AbilityRuntime.Core 147 * @since 9 148 */ 149 function cancel(agent: WantAgent): Promise<void>; 150 151 /** 152 * Triggers a WantAgent. 153 * 154 * @param { WantAgent } agent - Indicates the WantAgent. 155 * @param { TriggerInfo } triggerInfo - Indicates the information required for triggering a WantAgent. 156 * @param { AsyncCallback<CompleteData> } [callback] - The callback is used to return the CompleteData. 157 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 158 * 2. Incorrect parameter types. 159 * @syscap SystemCapability.Ability.AbilityRuntime.Core 160 * @since 9 161 */ 162 function trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: AsyncCallback<CompleteData>): void; 163 164 /** 165 * Checks whether two WantAgent objects are equal. 166 * 167 * @param { WantAgent } agent - Indicates the WantAgent. 168 * @param { WantAgent } otherAgent - Indicates the other WantAgent. 169 * @param { AsyncCallback<boolean> } callback - Returns true if the two WantAgents are the same. 170 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 171 * 2. Incorrect parameter types. 172 * @syscap SystemCapability.Ability.AbilityRuntime.Core 173 * @since 9 174 */ 175 function equal(agent: WantAgent, otherAgent: WantAgent, callback: AsyncCallback<boolean>): void; 176 177 /** 178 * Checks whether two WantAgent objects are equal. 179 * 180 * @param { WantAgent } agent - Indicates the WantAgent. 181 * @param { WantAgent } otherAgent - Indicates the other WantAgent. 182 * @returns { Promise<boolean> } Returns true if the two WantAgents are the same. 183 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 184 * 2. Incorrect parameter types. 185 * @syscap SystemCapability.Ability.AbilityRuntime.Core 186 * @since 9 187 */ 188 function equal(agent: WantAgent, otherAgent: WantAgent): Promise<boolean>; 189 190 /** 191 * Obtains a WantAgent object. 192 * 193 * @param { WantAgentInfo } info - Information about the WantAgent object to obtain. 194 * @param { AsyncCallback<WantAgent> } callback - The callback is used to return the created WantAgent. 195 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 196 * 2. Incorrect parameter types. 197 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 198 * @throws { BusinessError } 16000151 - Invalid wantagent object. 199 * @syscap SystemCapability.Ability.AbilityRuntime.Core 200 * @since 9 201 */ 202 function getWantAgent(info: WantAgentInfo, callback: AsyncCallback<WantAgent>): void; 203 204 /** 205 * Obtains a WantAgent object. 206 * 207 * @param { WantAgentInfo } info - Information about the WantAgent object to obtain. 208 * @returns { Promise<WantAgent> } Returns the created WantAgent. 209 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 210 * 2. Incorrect parameter types. 211 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 212 * @throws { BusinessError } 16000151 - Invalid wantagent object. 213 * @syscap SystemCapability.Ability.AbilityRuntime.Core 214 * @since 9 215 */ 216 function getWantAgent(info: WantAgentInfo): Promise<WantAgent>; 217 218 /** 219 * Obtains the {@link OperationType} of a {@link WantAgent}. 220 * 221 * @param { WantAgent } agent - Indicates the WantAgent. 222 * @param { AsyncCallback<number> } callback - The callback is used to return the OperationType of the WantAgent. 223 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 224 * 2. Incorrect parameter types. 225 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 226 * @throws { BusinessError } 16000015 - Service timeout. 227 * @throws { BusinessError } 16000151 - Invalid wantagent object. 228 * @syscap SystemCapability.Ability.AbilityRuntime.Core 229 * @since 9 230 */ 231 function getOperationType(agent: WantAgent, callback: AsyncCallback<number>): void; 232 233 /** 234 * Obtains the {@link OperationType} of a {@link WantAgent}. 235 * 236 * @param { WantAgent } agent - Indicates the WantAgent. 237 * @returns { Promise<number> } Returns the OperationType of the WantAgent. 238 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 239 * 2. Incorrect parameter types. 240 * @throws { BusinessError } 16000007 - Service busy, there are concurrent tasks, waiting for retry. 241 * @throws { BusinessError } 16000015 - Service timeout. 242 * @throws { BusinessError } 16000151 - Invalid wantagent object. 243 * @syscap SystemCapability.Ability.AbilityRuntime.Core 244 * @since 9 245 */ 246 function getOperationType(agent: WantAgent): Promise<number>; 247 248 /** 249 * Enumerates flags for using a WantAgent. 250 * 251 * @enum { number } 252 * @syscap SystemCapability.Ability.AbilityRuntime.Core 253 * @since 9 254 */ 255 export enum WantAgentFlags { 256 /** 257 * Indicates that the WantAgent can be used only once. 258 * This flag is valid only when OperationType is set to START_ABILITY, START_SERVICE, or SEND_COMMON_EVENT. 259 * 260 * @syscap SystemCapability.Ability.AbilityRuntime.Core 261 * @since 9 262 */ 263 ONE_TIME_FLAG = 0, 264 265 /** 266 * Indicates that null is returned if the WantAgent does not exist. 267 * This flag is valid only when OperationType is set to START_ABILITY, START_SERVICE, or SEND_COMMON_EVENT. 268 * 269 * @syscap SystemCapability.Ability.AbilityRuntime.Core 270 * @since 9 271 */ 272 NO_BUILD_FLAG, 273 274 /** 275 * Indicates that the existing WantAgent should be canceled before a new object is generated. 276 * This flag is valid only when OperationType is set to START_ABILITY, START_SERVICE, or SEND_COMMON_EVENT. 277 * 278 * @syscap SystemCapability.Ability.AbilityRuntime.Core 279 * @since 9 280 */ 281 CANCEL_PRESENT_FLAG, 282 283 /** 284 * Indicates that the system only replaces the extra data of the existing WantAgent with that of the new object. 285 * This flag is valid only when OperationType is set to START_ABILITY, START_SERVICE, or SEND_COMMON_EVENT. 286 * 287 * @syscap SystemCapability.Ability.AbilityRuntime.Core 288 * @since 9 289 */ 290 UPDATE_PRESENT_FLAG, 291 292 /** 293 * Indicates that the created WantAgent should be immutable. 294 * 295 * @syscap SystemCapability.Ability.AbilityRuntime.Core 296 * @since 9 297 */ 298 CONSTANT_FLAG, 299 300 /** 301 * Indicates that the current value of element can be replaced when the WantAgent is triggered. 302 * 303 * @syscap SystemCapability.Ability.AbilityRuntime.Core 304 * @since 9 305 */ 306 REPLACE_ELEMENT, 307 308 /** 309 * Indicates that the current value of action can be replaced when the WantAgent is triggered. 310 * 311 * @syscap SystemCapability.Ability.AbilityRuntime.Core 312 * @since 9 313 */ 314 REPLACE_ACTION, 315 316 /** 317 * Indicates that the current value of uri can be replaced when the WantAgent is triggered. 318 * 319 * @syscap SystemCapability.Ability.AbilityRuntime.Core 320 * @since 9 321 */ 322 REPLACE_URI, 323 324 /** 325 * Indicates that the current value of entities can be replaced when the WantAgent is triggered. 326 * 327 * @syscap SystemCapability.Ability.AbilityRuntime.Core 328 * @since 9 329 */ 330 REPLACE_ENTITIES, 331 332 /** 333 * Indicates that the current value of packageName can be replaced when the WantAgent is triggered. 334 * 335 * @syscap SystemCapability.Ability.AbilityRuntime.Core 336 * @since 9 337 */ 338 REPLACE_BUNDLE 339 } 340 341 /** 342 * Identifies the operation for using a WantAgent, such as starting an ability or sending a common event. 343 * 344 * @enum { number } 345 * @syscap SystemCapability.Ability.AbilityRuntime.Core 346 * @since 9 347 */ 348 export enum OperationType { 349 /** 350 * Unknown operation. 351 * 352 * @syscap SystemCapability.Ability.AbilityRuntime.Core 353 * @since 9 354 */ 355 UNKNOWN_TYPE = 0, 356 357 /** 358 * Starts an ability with a UI. 359 * 360 * @syscap SystemCapability.Ability.AbilityRuntime.Core 361 * @since 9 362 */ 363 START_ABILITY, 364 365 /** 366 * Starts multiple abilities with a UI. 367 * 368 * @syscap SystemCapability.Ability.AbilityRuntime.Core 369 * @since 9 370 */ 371 START_ABILITIES, 372 373 /** 374 * Starts an ability without a UI. 375 * 376 * @syscap SystemCapability.Ability.AbilityRuntime.Core 377 * @since 9 378 */ 379 START_SERVICE, 380 381 /** 382 * Sends a common event. 383 * 384 * @syscap SystemCapability.Ability.AbilityRuntime.Core 385 * @since 9 386 */ 387 SEND_COMMON_EVENT 388 } 389 390 /** 391 * Describes the data returned by after wantAgent.trigger is called. 392 * 393 * @typedef CompleteData 394 * @syscap SystemCapability.Ability.AbilityRuntime.Core 395 * @since 9 396 */ 397 export interface CompleteData { 398 /** 399 * Triggered WantAgent. 400 * 401 * @type { WantAgent } 402 * @syscap SystemCapability.Ability.AbilityRuntime.Core 403 * @since 9 404 */ 405 info: WantAgent; 406 407 /** 408 * Existing Want that is triggered. 409 * 410 * @type { Want } 411 * @syscap SystemCapability.Ability.AbilityRuntime.Core 412 * @since 9 413 */ 414 want: Want; 415 416 /** 417 * Request code used to trigger the WantAgent. 418 * 419 * @type { number } 420 * @syscap SystemCapability.Ability.AbilityRuntime.Core 421 * @since 9 422 */ 423 finalCode: number; 424 425 /** 426 * Final data collected by the common event. 427 * 428 * @type { string } 429 * @syscap SystemCapability.Ability.AbilityRuntime.Core 430 * @since 9 431 */ 432 finalData: string; 433 434 /** 435 * Extra data collected by the common event. 436 * 437 * @type { ?object } 438 * @syscap SystemCapability.Ability.AbilityRuntime.Core 439 * @since 9 440 */ 441 /** 442 * Extra data collected by the common event. 443 * 444 * @type { ?Record<string, Object> } 445 * @syscap SystemCapability.Ability.AbilityRuntime.Core 446 * @since 11 447 */ 448 extraInfo?: Record<string, Object>; 449 } 450 451 /** 452 * Provides the information required for triggering a WantAgent. 453 * 454 * @syscap SystemCapability.Ability.AbilityRuntime.Core 455 * @since 9 456 */ 457 export type TriggerInfo = _TriggerInfo; 458 459 /** 460 * Provides the information required for triggering a WantAgent. 461 * 462 * @syscap SystemCapability.Ability.AbilityRuntime.Core 463 * @since 9 464 */ 465 export type WantAgentInfo = _WantAgentInfo; 466} 467 468/** 469 * WantAgent object. 470 * 471 * @syscap SystemCapability.Ability.AbilityRuntime.Core 472 * @since 9 473 */ 474export type WantAgent = object; 475 476export default wantAgent; 477