1 /* 2 * Copyright (C) 2024 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 /** 18 * This is the system APIs for AAudio. 19 */ 20 #ifndef SYSTEM_AAUDIO_H 21 #define SYSTEM_AAUDIO_H 22 23 #include <aaudio/AAudio.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** 30 * Add one vendor extension tag that the output stream will carry. 31 * 32 * The total size of all added tags, plus one for each tag terminator, must not be greater than 33 * <a href="/reference/android/system/media/audio">AUDIO_ATTRIBUTES_TAGS_MAX_SIZE</a>. 34 * 35 * The tag can be used by the audio policy engine for routing purpose. 36 * Routing is based on audio attributes, translated into legacy stream type. 37 * The stream types cannot be extended, so the product strategies have been introduced to allow 38 * vendor extension of routing capabilities. 39 * This could, for example, affect how volume and routing is handled for the stream. 40 * 41 * The tag can also be used by a System App to pass vendor specific information through the 42 * framework to the HAL. That info could affect routing, ducking or other audio behavior in the HAL. 43 * 44 * By default, audio attributes tags are empty if this method is not called. 45 * 46 * When opening a stream with audio attributes tags, the client should hold 47 * MODIFY_AUDIO_SETTINGS_PRIVILEGED permission. Otherwise, the stream will fail to open. 48 * 49 * @param builder reference provided by AAudio_createStreamBuilder() 50 * @param tag the desired tag to add, which must be UTF-8 format and null-terminated. 51 * @return {@link #AAUDIO_OK} on success or {@link #AAUDIO_ERROR_ILLEGAL_ARGUMENT} if the given 52 * tags is null or {@link #AAUDIO_ERROR_OUT_OF_RANGE} if there is not room for more tags. 53 */ 54 aaudio_result_t AAudioStreamBuilder_addTag(AAudioStreamBuilder* _Nonnull builder, 55 const char* _Nonnull tag); 56 57 /** 58 * Clear all the tags that has been added from calling 59 * {@link #AAudioStreamBuilder_addTag}. 60 * 61 * @param builder reference provided by AAudio_createStreamBuilder() 62 */ 63 void AAudioStreamBuilder_clearTags(AAudioStreamBuilder* _Nonnull builder); 64 65 /** 66 * Allocate and read the audio attributes' tags for the stream into a buffer. 67 * The client is responsible to free the memory for tags by calling 68 * {@link #AAudioStream_releaseTags} unless the number of tags is 0. 69 * 70 * @param stream reference provided by AAudioStreamBuilder_openStream() 71 * @param tags a pointer to a variable that will be set to a pointer to an array of char* pointers 72 * @return number of tags or 73 * {@link #AAUDIO_ERROR_NO_MEMORY} if it fails to allocate memory for tags. 74 */ 75 int32_t AAudioStream_obtainTags(AAudioStream* _Nonnull stream, 76 char* _Nullable* _Nullable* _Nonnull tags); 77 78 /** 79 * Free the memory containing the tags that is allocated when calling 80 * {@link #AAudioStream_obtainTags}. 81 * 82 * @param stream reference provided by AAudioStreamBuilder_openStream() 83 * @param tags reference provided by AAudioStream_obtainTags() 84 */ 85 void AAudioStream_releaseTags(AAudioStream* _Nonnull stream, char* _Nonnull * _Nullable tags); 86 87 #ifdef __cplusplus 88 } 89 #endif 90 91 #endif //SYSTEM_AAUDIO_H 92