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 AMediaDataSource* AMediaDataSource_new() __INTRODUCED_IN(28); 93 94 #if __ANDROID_API__ >= 29 95 96 /** 97 * Called to get an estimate of the number of bytes that can be read from this data source 98 * starting at |offset| without blocking for I/O. 99 * 100 * Return -1 when such an estimate is not possible. 101 */ 102 typedef ssize_t (*AMediaDataSourceGetAvailableSize)(void *userdata, off64_t offset); 103 104 /** 105 * Create new media data source. Returns NULL if memory allocation 106 * for the new data source object fails. 107 * 108 * Set the |uri| from which the data source will read, 109 * plus additional http headers when initiating the request. 110 * 111 * Headers will contain corresponding items from |key_values| 112 * in the following fashion: 113 * 114 * key_values[0]:key_values[1] 115 * key_values[2]:key_values[3] 116 * ... 117 * key_values[(numheaders - 1) * 2]:key_values[(numheaders - 1) * 2 + 1] 118 * 119 */ 120 AMediaDataSource* AMediaDataSource_newUri(const char *uri, 121 int numheaders, 122 const char * const *key_values) __INTRODUCED_IN(29); 123 124 #endif /*__ANDROID_API__ >= 29 */ 125 126 /** 127 * Delete a previously created media data source. 128 */ 129 void AMediaDataSource_delete(AMediaDataSource*) __INTRODUCED_IN(28); 130 131 /** 132 * Set an user provided opaque handle. This opaque handle is passed as 133 * the first argument to the data source callbacks. 134 */ 135 void AMediaDataSource_setUserdata( 136 AMediaDataSource*, void *userdata) __INTRODUCED_IN(28); 137 138 /** 139 * Set a custom callback for supplying random access media data to the 140 * NDK media framework. 141 * 142 * Implement this if your app has special requirements for the way media 143 * data is obtained, or if you need a callback when data is read by the 144 * NDK media framework. 145 * 146 * Please refer to the definition of AMediaDataSourceReadAt for 147 * additional details. 148 */ 149 void AMediaDataSource_setReadAt( 150 AMediaDataSource*, 151 AMediaDataSourceReadAt) __INTRODUCED_IN(28); 152 153 /** 154 * Set a custom callback for supplying the size of the data source to the 155 * NDK media framework. 156 * 157 * Please refer to the definition of AMediaDataSourceGetSize for 158 * additional details. 159 */ 160 void AMediaDataSource_setGetSize( 161 AMediaDataSource*, 162 AMediaDataSourceGetSize) __INTRODUCED_IN(28); 163 164 /** 165 * Set a custom callback to receive signal from the NDK media framework 166 * when the data source is closed. 167 * 168 * Please refer to the definition of AMediaDataSourceClose for 169 * additional details. 170 */ 171 void AMediaDataSource_setClose( 172 AMediaDataSource*, 173 AMediaDataSourceClose) __INTRODUCED_IN(28); 174 175 #endif /*__ANDROID_API__ >= 28 */ 176 177 #if __ANDROID_API__ >= 29 178 179 /** 180 * Close the data source, unblock reads, and release associated resources. 181 * 182 * Please refer to the definition of AMediaDataSourceClose for 183 * additional details. 184 */ 185 void AMediaDataSource_close(AMediaDataSource*) __INTRODUCED_IN(29); 186 187 /** 188 * Set a custom callback for supplying the estimated number of bytes 189 * that can be read from this data source starting at an offset without 190 * blocking for I/O. 191 * 192 * Please refer to the definition of AMediaDataSourceGetAvailableSize 193 * for additional details. 194 */ 195 void AMediaDataSource_setGetAvailableSize( 196 AMediaDataSource*, 197 AMediaDataSourceGetAvailableSize) __INTRODUCED_IN(29); 198 199 #endif /*__ANDROID_API__ >= 29 */ 200 201 __END_DECLS 202 203 #endif // _NDK_MEDIA_DATASOURCE_H 204