1/*
2 * Copyright (c) 2024 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 * @addtogroup Distributed Audio
18 * @{
19 *
20 * @brief Provides APIs for communication to distributed audio SA service
21 *
22 * Call of the transmission interface between the distributed audio HDF service and
23 * the distributed audio SA service, and provide hardware driver interfaces for
24 * the upper layer.
25 *
26 * @since 5.0
27 * @version 2.0
28 */
29
30package ohos.hdi.distributed_audio.audioext.v2_0;
31
32import ohos.hdi.distributed_audio.audioext.v2_0.Types;
33
34/**
35 * @brief Basic operations for Distributed Audio devices.
36 *
37 * Enabling and disabling distributed audio devices, setting audio parameters,
38 * event notifications, and other related operations
39 *
40 * @since 5.0
41 * @version 2.0
42 */
43[callback] interface IDAudioCallback {
44    /**
45     * @brief Create distributed audio stream.
46     *
47     * @param streamId Stream ID for distributed audio devices.
48     *
49     * @return a value of 0 if success, return a negative value if failed.
50     *
51     * @since 5.0
52     * @version 2.0
53     */
54    CreateStream([in] int streamId);
55
56    /**
57     * @brief Create distributed audio stream.
58     *
59     * @param streamId Stream ID for distributed audio devices.
60     *
61     * @return a value of 0 if success, return a negative value if failed.
62     *
63     * @since 5.0
64     * @version 2.0
65     */
66    DestroyStream([in] int streamId);
67
68    /**
69     * @brief Set distributed audio device parameters.
70     *
71     * @param streamId Stream ID for distributed audio devices.
72     * @param param Audio parameters (sampling rate, number of channels, etc.)
73     *
74     * @return a value of 0 if success, return a negative value if failed.
75     *
76     * @since 5.0
77     * @version 2.0
78     */
79    SetParameters([in] int streamId, [in] struct AudioParameter param);
80
81    /**
82     * @brief Notify distributed audio SA of events.
83     *
84     * @param streamId Stream ID for distributed audio devices.
85     * @param event Notification event types (such as focus events, volume events)
86     *
87     * @return a value of 0 if success, return a negative value if failed.
88     *
89     * @since 5.0
90     * @version 2.0
91     */
92    NotifyEvent([in] int streamId, [in] struct DAudioEvent event);
93
94    /**
95     * @brief Write stream to distributed audio devices.
96     *
97     * @param streamId Stream ID for distributed audio devices.
98     * @param data frame data of audio stream.
99     *
100     * @return a value of 0 if success, return a negative value if failed.
101     *
102     * @since 5.0
103     * @version 2.0
104     */
105    WriteStreamData([in] int streamId, [in] struct AudioData data);
106
107    /**
108     * @brief Reading recording streams from distributed audio devices.
109     *
110     * @param streamId Stream ID for distributed audio devices.
111     * @param data Frame data of audio stream.
112     *
113     * @return a value of 0 if success, return a negative value if failed.
114     *
115     * @since 5.0
116     * @version 2.0
117     */
118    ReadStreamData([in] int streamId, [out] struct AudioData data);
119
120    /**
121     * @brief Get the current frame rate and timestamp for reading and writing
122     *
123     * @param streamId Stream ID for distributed audio devices.
124     * @param frames current frame number
125     * @param time current timestamp
126     *
127     * @return a value of 0 if success, return a negative value if failed.
128     *
129     * @since 5.0
130     * @version 2.0
131     */
132    ReadMmapPosition([in] int streamId, [out] unsigned long frames, [out] struct CurrentTime time);
133
134    /**
135     * @brief Refresh shared memory information
136     *
137     * @param streamId Stream ID for distributed audio devices.
138     * @param fd file descriptors corresponding to shared memory
139     * @param ashmemLength The total number of bytes of shared memory.
140     * @param lengthPerTrans The number of bytes to be transmitted.
141     *
142     * @return a value of 0 if success, return a negative value if failed.
143     *
144     * @since 5.0
145     * @version 2.0
146     */
147    RefreshAshmemInfo([in] int streamId, [in] FileDescriptor fd, [in] int ashmemLength, [in] int lengthPerTrans);
148}