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