1 /*
2  * Copyright (C) 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.car.audio.hal;
18 
19 import static com.android.car.internal.ExcludeFromCodeCoverageGeneratedReport.DUMP_INFO;
20 
21 import android.annotation.IntDef;
22 import android.annotation.NonNull;
23 import android.annotation.Nullable;
24 import android.hardware.audio.common.PlaybackTrackMetadata;
25 import android.hardware.automotive.audiocontrol.MutingInfo;
26 
27 import com.android.car.audio.CarDuckingInfo;
28 import com.android.car.internal.ExcludeFromCodeCoverageGeneratedReport;
29 import com.android.car.internal.util.IndentingPrintWriter;
30 
31 import java.lang.annotation.Retention;
32 import java.lang.annotation.RetentionPolicy;
33 import java.util.List;
34 
35 /**
36  * AudioControlWrapper wraps IAudioControl HAL interface, handling version specific support so that
37  * the rest of CarAudioService doesn't need to know about it.
38  */
39 public interface AudioControlWrapper {
40     int AUDIOCONTROL_FEATURE_AUDIO_FOCUS = 0;
41     int AUDIOCONTROL_FEATURE_AUDIO_DUCKING = 1;
42     int AUDIOCONTROL_FEATURE_AUDIO_GROUP_MUTING = 2;
43     int AUDIOCONTROL_FEATURE_AUDIO_FOCUS_WITH_METADATA = 3;
44     int AUDIOCONTROL_FEATURE_AUDIO_GAIN_CALLBACK = 4;
45     int AUDIOCONTROL_FEATURE_AUDIO_MODULE_CALLBACK = 5;
46 
47     @IntDef({
48             AUDIOCONTROL_FEATURE_AUDIO_FOCUS,
49             AUDIOCONTROL_FEATURE_AUDIO_DUCKING,
50             AUDIOCONTROL_FEATURE_AUDIO_GROUP_MUTING,
51             AUDIOCONTROL_FEATURE_AUDIO_FOCUS_WITH_METADATA,
52             AUDIOCONTROL_FEATURE_AUDIO_GAIN_CALLBACK,
53             AUDIOCONTROL_FEATURE_AUDIO_MODULE_CALLBACK,
54     })
55     @Retention(RetentionPolicy.SOURCE)
56     @interface AudioControlFeature {
57     }
58 
59     /**
60      * Closes the focus listener that's registered on the AudioControl HAL
61      */
unregisterFocusListener()62     void unregisterFocusListener();
63 
64     /**
65      * Indicates if HAL can support specified feature
66      *
67      * @param feature to check support for. it's expected to be one of the features defined by
68      * {@link AudioControlWrapper.AudioControlFeature}.
69      * @return boolean indicating whether feature is supported
70      */
supportsFeature(@udioControlFeature int feature)71     boolean supportsFeature(@AudioControlFeature int feature);
72 
73     /**
74      * Registers listener for HAL audio focus requests with IAudioControl. Only works if
75      * {@code supportsHalAudioFocus} returns true.
76      *
77      * @param focusListener the listener to register on the IAudioControl HAL.
78      */
registerFocusListener(HalFocusListener focusListener)79     void registerFocusListener(HalFocusListener focusListener);
80 
81     /**
82      * Registers callback for HAL audio gain changed notification with IAudioControl. Only works if
83      * {@code supportsHalAudioGainCallback} returns true.
84      *
85      * @param gainCallback the callback to register on the IAudioControl HAL.
86      */
registerAudioGainCallback(@onNull HalAudioGainCallback gainCallback)87     void registerAudioGainCallback(@NonNull HalAudioGainCallback gainCallback);
88 
89     /**
90      * Closes the audio gain callback registered on the AudioControl HAL
91      */
unregisterAudioGainCallback()92     void unregisterAudioGainCallback();
93 
94     /**
95      * Notifies HAL of change in audio focus for a request it has made.
96      *
97      * @param metadata {@link PlaybackTrackMetadata} that the request is associated with.
98      * @param zoneId for the audio zone that the request is associated with.
99      * @param focusChange the new status of the request.
100      */
onAudioFocusChange(PlaybackTrackMetadata metadata, int zoneId, int focusChange)101     void onAudioFocusChange(PlaybackTrackMetadata metadata, int zoneId, int focusChange);
102 
103     /**
104      * dumps the current state of the AudioControlWrapper
105      *
106      * @param writer stream to write current state
107      */
108     @ExcludeFromCodeCoverageGeneratedReport(reason = DUMP_INFO)
dump(IndentingPrintWriter writer)109     void dump(IndentingPrintWriter writer);
110 
111     /**
112      * Sets the fade for the vehicle.
113      *
114      * @param value to set for the fade. Positive is towards front.
115      */
setFadeTowardFront(float value)116     void setFadeTowardFront(float value);
117 
118     /**
119      * Sets the balance value for the vehicle.
120      *
121      * @param value to set for the balance. Positive is towards the right.
122      */
setBalanceTowardRight(float value)123     void setBalanceTowardRight(float value);
124 
125     /**
126      * Notifies HAL of changes in usages holding focus and the corresponding ducking changes for a
127      * given zone.
128      *
129      * @param carDuckingInfos list of information about focus and addresses to duck for each
130      * impacted zone to relay to the HAL.
131      */
onDevicesToDuckChange(@onNull List<CarDuckingInfo> carDuckingInfos)132     void onDevicesToDuckChange(@NonNull List<CarDuckingInfo> carDuckingInfos);
133 
134     /**
135      * Notifies HAL of changes in muting changes for all audio zones.
136      *
137      * @param carZonesMutingInfo list of information about addresses to mute to relay to the HAL.
138      */
onDevicesToMuteChange(@onNull List<MutingInfo> carZonesMutingInfo)139     void onDevicesToMuteChange(@NonNull List<MutingInfo> carZonesMutingInfo);
140 
141     /**
142      * Registers callback for HAL audio module change notification with IAudioControl. Only works
143      * if {@code supportsHalAudioModuleChangeCallback} returns true.
144      *
145      * @param moduleChangeCallback the callback to register on the IAudioControl HAL.
146      */
setModuleChangeCallback(HalAudioModuleChangeCallback moduleChangeCallback)147     void setModuleChangeCallback(HalAudioModuleChangeCallback moduleChangeCallback);
148 
149     /**
150      * Clears all module change callbacks that's registered on the AudioControl HAL
151      */
clearModuleChangeCallback()152     void clearModuleChangeCallback();
153 
154     /**
155      * Registers recipient to be notified if AudioControl HAL service dies.
156      *
157      * @param deathRecipient to be notified upon HAL service death.
158      */
linkToDeath(@ullable AudioControlDeathRecipient deathRecipient)159     void linkToDeath(@Nullable AudioControlDeathRecipient deathRecipient);
160 
161     /**
162      * Unregisters recipient for AudioControl HAL service death.
163      */
unlinkToDeath()164     void unlinkToDeath();
165 
166     /**
167      * Recipient to be notified upon death of AudioControl HAL.
168      */
169     interface AudioControlDeathRecipient {
170         /**
171          * Called if AudioControl HAL dies.
172          */
serviceDied()173         void serviceDied();
174     }
175 }
176