• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2025 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 ConnectivityKit
19 */
20
21import type { Callback } from './@ohos.base';
22
23/**
24 * Provides methods to accessing bluetooth OPP(OBEX OBJECT PUSH Profile)-related capabilities.
25 *
26 * @namespace opp
27 * @syscap SystemCapability.Communication.Bluetooth.Core
28 * @since 16
29 */
30declare namespace opp {
31  /**
32   * create the instance of OPP server profile.
33   *
34   * @returns { OppServerProfile } Returns the instance of opp profile.
35   * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
36   * @throws { BusinessError } 801 - Capability not supported.
37   * @syscap SystemCapability.Communication.Bluetooth.Core
38   * @systemapi
39   * @since 16
40   */
41  function createOppServerProfile(): OppServerProfile;
42
43  /**
44   * Manager OPP server profile.
45   *
46   * @typedef OppServerProfile
47   * @syscap SystemCapability.Communication.Bluetooth.Core
48   * @since 16
49   */
50  interface OppServerProfile {
51    /**
52     * Subscribe the event reported when the file transfer status changes.
53     *
54     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
55     * @param { 'transferStateChange' } type - Type of transport state change event to listen for.
56     * @param { Callback<OppTransferInformation> } callback - Callback used to listen for event.
57     * @throws { BusinessError } 201 - Permission denied.
58     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
59     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
60     * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
61     * <br>2. Incorrect parameter types. 3. Parameter verification failed.
62     * @throws { BusinessError } 801 - Capability not supported.
63     * @throws { BusinessError } 2900001 - Service stopped.
64     * @throws { BusinessError } 2900003 - Bluetooth disabled.
65     * @throws { BusinessError } 2900004 - Profile not supported.
66     * @syscap SystemCapability.Communication.Bluetooth.Core
67     * @systemapi
68     * @since 16
69     */
70    on(type: 'transferStateChange', callback: Callback<OppTransferInformation>): void;
71
72    /**
73     * Unsubscribe the event reported when the file transfer status changes.
74     *
75     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
76     * @param { 'transferStateChange' } type - Type of transport state change event to listen for.
77     * @param { Callback<OppTransferInformation> } callback - Callback used to listen for event.
78     * @throws { BusinessError } 201 - Permission denied.
79     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
80     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
81     * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
82     * <br>2. Incorrect parameter types. 3. Parameter verification failed.
83     * @throws { BusinessError } 801 - Capability not supported.
84     * @throws { BusinessError } 2900001 - Service stopped.
85     * @throws { BusinessError } 2900003 - Bluetooth disabled.
86     * @throws { BusinessError } 2900004 - Profile not supported.
87     * @syscap SystemCapability.Communication.Bluetooth.Core
88     * @systemapi
89     * @since 16
90     */
91    off(type: 'transferStateChange', callback?: Callback<OppTransferInformation>): void;
92
93    /**
94     * Subscribe to the event of receiving a file transfer request.
95     *
96     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
97     * @param { 'receiveIncomingFile' } type - Type of the event for receiving a file request to listen for.
98     * @param { Callback<OppTransferInformation> } callback - Callback used to listen for event.
99     * @throws { BusinessError } 201 - Permission denied.
100     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
101     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
102     * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
103     * <br>2. Incorrect parameter types. 3. Parameter verification failed.
104     * @throws { BusinessError } 801 - Capability not supported.
105     * @throws { BusinessError } 2900001 - Service stopped.
106     * @throws { BusinessError } 2900003 - Bluetooth disabled.
107     * @throws { BusinessError } 2900004 - Profile not supported.
108     * @syscap SystemCapability.Communication.Bluetooth.Core
109     * @systemapi
110     * @since 16
111     */
112    on(type: 'receiveIncomingFile', callback: Callback<OppTransferInformation>): void;
113
114    /**
115     * Unsubscribe to the event of receiving a file transfer request.
116     *
117     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
118     * @param { 'receiveIncomingFile' } type - Type of the event for receiving a file request to listen for.
119     * @param { Callback<OppTransferInformation> } callback - Callback used to listen for event.
120     * @throws { BusinessError } 201 - Permission denied.
121     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
122     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
123     * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
124     * <br>2. Incorrect parameter types. 3. Parameter verification failed.
125     * @throws { BusinessError } 801 - Capability not supported.
126     * @throws { BusinessError } 2900001 - Service stopped.
127     * @throws { BusinessError } 2900003 - Bluetooth disabled.
128     * @throws { BusinessError } 2900004 - Profile not supported.
129     * @syscap SystemCapability.Communication.Bluetooth.Core
130     * @systemapi
131     * @since 16
132     */
133    off(type: 'receiveIncomingFile', callback?: Callback<OppTransferInformation>): void;
134
135    /**
136     * Send files to the remote device.
137     *
138     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
139     * @param { string } deviceId - Indicates device ID. For example, "11:22:33:AA:BB:FF".
140     * @param { Array<FileHolder> } fileHolds - Indicates the information about files to be sent.
141     * @returns { Promise<void> } Returns the promise object.
142     * @throws { BusinessError } 201 - Permission denied.
143     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
144     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
145     * @throws { BusinessError } 401 - Invalid parameter.
146     * @throws { BusinessError } 801 - Capability not supported.
147     * @throws { BusinessError } 2900001 - Service stopped.
148     * @throws { BusinessError } 2900003 - Bluetooth switch is off.
149     * @throws { BusinessError } 2900004 - Profile is not supported.
150     * @throws { BusinessError } 2900099 - Failed to send file.
151     * @throws { BusinessError } 2903001 - The file type is not supported.
152     * @throws { BusinessError } 2903002 - Current Transfer Information is busy.
153     * @throws { BusinessError } 2903003 - The file is not accessible.
154     * @syscap SystemCapability.Communication.Bluetooth.Core
155     * @systemapi
156     * @since 16
157     */
158    sendFile(deviceId: string, fileHolds: Array<FileHolder>): Promise<void>;
159
160    /**
161     * Set the user confirmation information for incoming files.
162     *
163     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
164     * @param { boolean } accept - Indicates whether to accept the incoming file, {@code true} indicates accept or {@code false} otherwise.
165     * @param { number } fileFd : the receive file fd to receive need contains open when accepting.
166     * @returns { Promise<void> } Returns the promise object.
167     * @throws { BusinessError } 201 - Permission denied.
168     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
169     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
170     * @throws { BusinessError } 401 - Invalid parameter.
171     * @throws { BusinessError } 801 - Capability not supported.
172     * @throws { BusinessError } 2900001 - Service stopped.
173     * @throws { BusinessError } 2900003 - Bluetooth switch is off.
174     * @throws { BusinessError } 2900004 - Profile is not supported.
175     * @throws { BusinessError } 2900099 - Failed to confirm the received file information.
176     * @throws { BusinessError } 2903002 - Current Transfer Information is busy.
177     * @throws { BusinessError } 2903003 - The file is not accessible.
178     * @syscap SystemCapability.Communication.Bluetooth.Core
179     * @systemapi
180     * @since 16
181     */
182    setIncomingFileConfirmation(accept: boolean, fileFd: number): Promise<void>;
183
184    /**
185     * cancel the current file transfer action.
186     *
187     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
188     * @returns { Promise<void> } Returns the promise object.
189     * @throws { BusinessError } 201 - Permission denied.
190     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
191     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
192     * @throws { BusinessError } 801 - Capability not supported.
193     * @throws { BusinessError } 2900001 - Service stopped.
194     * @throws { BusinessError } 2900003 - Bluetooth switch is off.
195     * @throws { BusinessError } 2900004 - Profile is not supported.
196     * @throws { BusinessError } 2900099 - Failed to cancel the current transfer.
197     * @throws { BusinessError } 2903002 - Current Transfer Information is busy.
198     * @syscap SystemCapability.Communication.Bluetooth.Core
199     * @systemapi
200     * @since 16
201     */
202    cancelTransfer(): Promise<void>;
203
204    /**
205     * Obtains the information about the file that is being transferred.
206     *
207     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
208     * @returns { Promise<OppTransferInformation> } Returns the promise object.
209     * @throws { BusinessError } 201 - Permission denied.
210     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
211     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
212     * @throws { BusinessError } 801 - Capability not supported.
213     * @throws { BusinessError } 2900001 - Service stopped.
214     * @throws { BusinessError } 2900003 - Bluetooth switch is off.
215     * @throws { BusinessError } 2900004 - Profile is not supported.
216     * @throws { BusinessError } 2900099 - Failed to obtain the current transmission information.
217     * @throws { BusinessError } 2903004 - Current Transfer Information is empty.
218     * @syscap SystemCapability.Communication.Bluetooth.Core
219     * @systemapi
220     * @since 16
221     */
222    getCurrentTransferInformation(): Promise<OppTransferInformation>;
223
224    /**
225     * Set the URI of the last received file.
226     *
227     * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH
228     * @param { string } uri - the uri of last received file.
229     * @returns { Promise<void> } Returns the promise object.
230     * @throws { BusinessError } 201 - Permission denied.
231     * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs.
232     * @throws { BusinessError } 203 - This function is prohibited by enterprise management policies.
233     * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified.
234     * <br>2. Incorrect parameter types. 3. Parameter verification failed.
235     * @throws { BusinessError } 801 - Capability not supported.
236     * @throws { BusinessError } 2900001 - Service stopped.
237     * @throws { BusinessError } 2900003 - Bluetooth disabled.
238     * @throws { BusinessError } 2900004 - Profile not supported.
239     * @throws { BusinessError } 2900099 - Failed to set the URI of the last file.
240     * @syscap SystemCapability.Communication.Bluetooth.Core
241     * @systemapi
242     * @since 16
243     */
244    setLastReceivedFileUri(uri: string): Promise<void>;
245  }
246
247  /**
248   * Enum for file transfer direction.
249   *
250   * @enum { number }
251   * @syscap SystemCapability.Communication.Bluetooth.Core
252   * @systemapi
253   * @since 16
254   */
255  enum DirectionType {
256    /**
257     * The file transfer direction to send.
258     *
259     * @syscap SystemCapability.Communication.Bluetooth.Core
260     * @systemapi
261     * @since 16
262     */
263    OUTBOUND = 0,
264
265    /**
266     * The file transfer direction to receive.
267     *
268     * @syscap SystemCapability.Communication.Bluetooth.Core
269     * @systemapi
270     * @since 16
271     */
272    INBOUND = 1
273  }
274
275  /**
276   * Enum for the file transfer status.
277   *
278   * @enum { number }
279   * @syscap SystemCapability.Communication.Bluetooth.Core
280   * @systemapi
281   * @since 16
282   */
283  enum TransferStatus {
284    /**
285     * The file is waiting next operate.
286     *
287     * @syscap SystemCapability.Communication.Bluetooth.Core
288     * @systemapi
289     * @since 16
290     */
291    PENDING = 0,
292
293    /**
294     * The file is transfering.
295     *
296     * @syscap SystemCapability.Communication.Bluetooth.Core
297     * @systemapi
298     * @since 16
299     */
300    RUNNING = 1,
301
302    /**
303     * The file is transfer finished.
304     *
305     * @syscap SystemCapability.Communication.Bluetooth.Core
306     * @systemapi
307     * @since 16
308     */
309    FINISH = 2
310  }
311
312  /**
313   * Enum for the file transfer result.
314   *
315   * @enum { number }
316   * @syscap SystemCapability.Communication.Bluetooth.Core
317   * @systemapi
318   * @since 16
319   */
320  enum TransferResult {
321    /**
322     * Success
323     *
324     * @syscap SystemCapability.Communication.Bluetooth.Core
325     * @systemapi
326     * @since 16
327     */
328    SUCCESS = 0,
329
330    /**
331     * The transfer file type is not supported.
332     *
333     * @syscap SystemCapability.Communication.Bluetooth.Core
334     * @systemapi
335     * @since 16
336     */
337    ERROR_UNSUPPORTED_TYPE = 1,
338
339    /**
340     * The peer device cannot process the request.
341     *
342     * @syscap SystemCapability.Communication.Bluetooth.Core
343     * @systemapi
344     * @since 16
345     */
346    ERROR_BAD_REQUEST = 2,
347
348    /**
349     * The peer device refuses to receive the file.
350     *
351     * @syscap SystemCapability.Communication.Bluetooth.Core
352     * @systemapi
353     * @since 16
354     */
355    ERROR_NOT_ACCEPTABLE = 3,
356
357
358    /**
359     * The peer device cancels the ongoing file transfer process.
360     *
361     * @syscap SystemCapability.Communication.Bluetooth.Core
362     * @systemapi
363     * @since 16
364     */
365    ERROR_CANCELED = 4,
366
367    /**
368     * Failed to connect to the peer device.
369     *
370     * @syscap SystemCapability.Communication.Bluetooth.Core
371     * @systemapi
372     * @since 16
373     */
374    ERROR_CONNECTION_FAILED = 5,
375
376    /**
377     * Indicates that the file transfer fails.
378     *
379     * @syscap SystemCapability.Communication.Bluetooth.Core
380     * @systemapi
381     * @since 16
382     */
383    ERROR_TRANSFER_FAILED = 6,
384
385    /**
386     * Unknown error
387     *
388     * @syscap SystemCapability.Communication.Bluetooth.Core
389     * @systemapi
390     * @since 16
391     */
392    ERROR_UNKNOWN = 7
393  }
394
395  /**
396   * Describes the transferred file information.
397   *
398   * @typedef OppTransferInformation
399   * @syscap SystemCapability.Communication.Bluetooth.Core
400   * @systemapi
401   * @since 16
402   */
403  interface OppTransferInformation {
404    /**
405     * Path of the file to be transferred.
406     *
407     * @type { string }
408     * @syscap SystemCapability.Communication.Bluetooth.Core
409     * @systemapi
410     * @since 16
411     */
412    filePath: string;
413
414    /**
415     * Device name of the peer transmission object
416     *
417     * @type { string }
418     * @syscap SystemCapability.Communication.Bluetooth.Core
419     * @systemapi
420     * @since 16
421     */
422    remoteDeviceName: string;
423
424    /**
425     * Device Address of the peer transmission object
426     *
427     * @type { string }
428     * @syscap SystemCapability.Communication.Bluetooth.Core
429     * @systemapi
430     * @since 16
431     */
432    remoteDeviceId: string;
433
434    /**
435     * File Transfer Direction
436     *
437     * @type { DirectionType }
438     * @syscap SystemCapability.Communication.Bluetooth.Core
439     * @systemapi
440     * @since 16
441     */
442    direction: DirectionType;
443
444    /**
445     * File transfer status
446     *
447     * @type { TransferStatus }
448     * @syscap SystemCapability.Communication.Bluetooth.Core
449     * @systemapi
450     * @since 16
451     */
452    status: TransferStatus;
453
454    /**
455     * File transfer result
456     *
457     * @type { TransferResult }
458     * @syscap SystemCapability.Communication.Bluetooth.Core
459     * @systemapi
460     * @since 16
461     */
462    result: TransferResult;
463
464    /**
465     * Number of bytes of the file that have been transferred currently
466     *
467     * @type { number }
468     * @syscap SystemCapability.Communication.Bluetooth.Core
469     * @systemapi
470     * @since 16
471     */
472    currentBytes: number;
473
474    /**
475     * Total number of file bytes to transfer
476     *
477     * @type { number }
478     * @syscap SystemCapability.Communication.Bluetooth.Core
479     * @systemapi
480     * @since 16
481     */
482    totalBytes: number;
483
484    /**
485     * Number of files currently transferred
486     *
487     * @type { number }
488     * @syscap SystemCapability.Communication.Bluetooth.Core
489     * @systemapi
490     * @since 16
491     */
492    currentCount: number;
493
494    /**
495     * Total number of transferred files
496     *
497     * @type { number }
498     * @syscap SystemCapability.Communication.Bluetooth.Core
499     * @systemapi
500     * @since 16
501     */
502    totalCount: number;
503  }
504
505  /**
506   * Describes the file info for transfer
507   *
508   * @typedef FileHolder
509   * @syscap SystemCapability.Communication.Bluetooth.Core
510   * @systemapi
511   * @since 16
512   */
513  interface FileHolder {
514    /**
515     * The file path
516     *
517     * @type { string }
518     * @syscap SystemCapability.Communication.Bluetooth.Core
519     * @systemapi
520     * @since 16
521     */
522    filePath: string;
523
524    /**
525     * The file size
526     *
527     * @type { number }
528     * @syscap SystemCapability.Communication.Bluetooth.Core
529     * @systemapi
530     * @since 16
531     */
532    fileSize: number;
533
534    /**
535     * The file fd
536     *
537     * @type { number }
538     * @syscap SystemCapability.Communication.Bluetooth.Core
539     * @systemapi
540     * @since 16
541     */
542    fileFd: number;
543  }
544}
545export default opp;
546