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