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