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