1 /* 2 * Copyright (C) 2018 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 /* 19 * This file defines an NDK API. 20 * Do not remove methods. 21 * Do not change method signatures. 22 * Do not change the value of constants. 23 * Do not change the size of any of the classes defined in here. 24 * Do not reference types that are not part of the NDK. 25 * Do not #include files that aren't part of the NDK. 26 */ 27 28 #ifndef _NDK_MEDIA_DATASOURCE_H 29 #define _NDK_MEDIA_DATASOURCE_H 30 31 #include <sys/cdefs.h> 32 #include <sys/types.h> 33 34 #include <media/NdkMediaError.h> 35 36 __BEGIN_DECLS 37 38 struct AMediaDataSource; 39 typedef struct AMediaDataSource AMediaDataSource; 40 41 #if __ANDROID_API__ >= 28 42 43 /* 44 * AMediaDataSource's callbacks will be invoked on an implementation-defined thread 45 * or thread pool. No guarantees are provided about which thread(s) will be used for 46 * callbacks. For example, |close| can be invoked from a different thread than the 47 * thread invoking |readAt|. As such, the Implementations of AMediaDataSource callbacks 48 * must be threadsafe. 49 */ 50 51 /** 52 * Called to request data from the given |offset|. 53 * 54 * Implementations should should write up to |size| bytes into 55 * |buffer|, and return the number of bytes written. 56 * 57 * Return 0 if size is zero (thus no bytes are read). 58 * 59 * Return -1 to indicate that end of stream is reached. 60 */ 61 typedef ssize_t (*AMediaDataSourceReadAt)( 62 void *userdata, off64_t offset, void * buffer, size_t size); 63 64 /** 65 * Called to get the size of the data source. 66 * 67 * Return the size of data source in bytes, or -1 if the size is unknown. 68 */ 69 typedef ssize_t (*AMediaDataSourceGetSize)(void *userdata); 70 71 /** 72 * Called to close the data source, unblock reads, and release associated 73 * resources. 74 * 75 * The NDK media framework guarantees that after the first |close| is 76 * called, no future callbacks will be invoked on the data source except 77 * for |close| itself. 78 * 79 * Closing a data source allows readAt calls that were blocked waiting 80 * for I/O data to return promptly. 81 * 82 * When using AMediaDataSource as input to AMediaExtractor, closing 83 * has the effect of unblocking slow reads inside of setDataSource 84 * and readSampleData. 85 */ 86 typedef void (*AMediaDataSourceClose)(void *userdata); 87 88 /** 89 * Create new media data source. Returns NULL if memory allocation 90 * for the new data source object fails. 91 * 92 * Available since API level 28. 93 */ 94 AMediaDataSource* AMediaDataSource_new() __INTRODUCED_IN(28); 95 96 #if __ANDROID_API__ >= 29 97 98 /** 99 * Called to get an estimate of the number of bytes that can be read from this data source 100 * starting at |offset| without blocking for I/O. 101 * 102 * Return -1 when such an estimate is not possible. 103 */ 104 typedef ssize_t (*AMediaDataSourceGetAvailableSize)(void *userdata, off64_t offset); 105 106 /** 107 * Create new media data source. Returns NULL if memory allocation 108 * for the new data source object fails. 109 * 110 * Set the |uri| from which the data source will read, 111 * plus additional http headers when initiating the request. 112 * 113 * Headers will contain corresponding items from |key_values| 114 * in the following fashion: 115 * 116 * key_values[0]:key_values[1] 117 * key_values[2]:key_values[3] 118 * ... 119 * key_values[(numheaders - 1) * 2]:key_values[(numheaders - 1) * 2 + 1] 120 * 121 * Available since API level 29. 122 */ 123 AMediaDataSource* AMediaDataSource_newUri(const char *uri, 124 int numheaders, 125 const char * const *key_values) __INTRODUCED_IN(29); 126 127 #endif /*__ANDROID_API__ >= 29 */ 128 129 /** 130 * Delete a previously created media data source. 131 * 132 * Available since API level 28. 133 */ 134 void AMediaDataSource_delete(AMediaDataSource*) __INTRODUCED_IN(28); 135 136 /** 137 * Set an user provided opaque handle. This opaque handle is passed as 138 * the first argument to the data source callbacks. 139 * 140 * Available since API level 28. 141 */ 142 void AMediaDataSource_setUserdata( 143 AMediaDataSource*, void *userdata) __INTRODUCED_IN(28); 144 145 /** 146 * Set a custom callback for supplying random access media data to the 147 * NDK media framework. 148 * 149 * Implement this if your app has special requirements for the way media 150 * data is obtained, or if you need a callback when data is read by the 151 * NDK media framework. 152 * 153 * Please refer to the definition of AMediaDataSourceReadAt for 154 * additional details. 155 * 156 * Available since API level 28. 157 */ 158 void AMediaDataSource_setReadAt( 159 AMediaDataSource*, 160 AMediaDataSourceReadAt) __INTRODUCED_IN(28); 161 162 /** 163 * Set a custom callback for supplying the size of the data source to the 164 * NDK media framework. 165 * 166 * Please refer to the definition of AMediaDataSourceGetSize for 167 * additional details. 168 * 169 * Available since API level 28. 170 */ 171 void AMediaDataSource_setGetSize( 172 AMediaDataSource*, 173 AMediaDataSourceGetSize) __INTRODUCED_IN(28); 174 175 /** 176 * Set a custom callback to receive signal from the NDK media framework 177 * when the data source is closed. 178 * 179 * Please refer to the definition of AMediaDataSourceClose for 180 * additional details. 181 * 182 * Available since API level 28. 183 */ 184 void AMediaDataSource_setClose( 185 AMediaDataSource*, 186 AMediaDataSourceClose) __INTRODUCED_IN(28); 187 188 #endif /*__ANDROID_API__ >= 28 */ 189 190 #if __ANDROID_API__ >= 29 191 192 /** 193 * Close the data source, unblock reads, and release associated resources. 194 * 195 * Please refer to the definition of AMediaDataSourceClose for 196 * additional details. 197 * 198 * Available since API level 29. 199 */ 200 void AMediaDataSource_close(AMediaDataSource*) __INTRODUCED_IN(29); 201 202 /** 203 * Set a custom callback for supplying the estimated number of bytes 204 * that can be read from this data source starting at an offset without 205 * blocking for I/O. 206 * 207 * Please refer to the definition of AMediaDataSourceGetAvailableSize 208 * for additional details. 209 * 210 * Available since API level 29. 211 */ 212 void AMediaDataSource_setGetAvailableSize( 213 AMediaDataSource*, 214 AMediaDataSourceGetAvailableSize) __INTRODUCED_IN(29); 215 216 #endif /*__ANDROID_API__ >= 29 */ 217 218 __END_DECLS 219 220 #endif // _NDK_MEDIA_DATASOURCE_H 221