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. However, it is guaranteed that AMediaDataSource's callbacks will only
47  * ever be invoked by a single thread at a time.
48  *
49  * There will be a thread synchronization point between each call to ensure that
50  * modifications to the state of your AMediaDataSource are visible to future
51  * calls. This means you don't need to do your own synchronization unless you're
52  * modifying the AMediaDataSource from another thread while it's being used by the
53  * framework.
54  */
55 
56 /**
57  * Called to request data from the given |offset|.
58  *
59  * Implementations should should write up to |size| bytes into
60  * |buffer|, and return the number of bytes written.
61  *
62  * Return 0 if size is zero (thus no bytes are read).
63  *
64  * Return -1 to indicate that end of stream is reached.
65  */
66 typedef ssize_t (*AMediaDataSourceReadAt)(
67         void *userdata, off64_t offset, void * buffer, size_t size);
68 
69 /**
70  * Called to get the size of the data source.
71  *
72  * Return the size of data source in bytes, or -1 if the size is unknown.
73  */
74 typedef ssize_t (*AMediaDataSourceGetSize)(void *userdata);
75 
76 /**
77  * Called to close the data source and release associated resources.
78  * The NDK media framework guarantees that after |close| is called
79  * no future callbacks will be invoked on the data source.
80  */
81 typedef void (*AMediaDataSourceClose)(void *userdata);
82 
83 /**
84  * Create new media data source. Returns NULL if memory allocation
85  * for the new data source object fails.
86  */
87 AMediaDataSource* AMediaDataSource_new();
88 
89 /**
90  * Delete a previously created media data source.
91  */
92 void AMediaDataSource_delete(AMediaDataSource*);
93 
94 /**
95  * Set an user provided opaque handle. This opaque handle is passed as
96  * the first argument to the data source callbacks.
97  */
98 void AMediaDataSource_setUserdata(
99         AMediaDataSource*, void *userdata);
100 
101 /**
102  * Set a custom callback for supplying random access media data to the
103  * NDK media framework.
104  *
105  * Implement this if your app has special requirements for the way media
106  * data is obtained, or if you need a callback when data is read by the
107  * NDK media framework.
108  *
109  * Please refer to the definition of AMediaDataSourceReadAt for
110  * additional details.
111  */
112 void AMediaDataSource_setReadAt(
113         AMediaDataSource*,
114         AMediaDataSourceReadAt);
115 
116 /**
117  * Set a custom callback for supplying the size of the data source to the
118  * NDK media framework.
119  *
120  * Please refer to the definition of AMediaDataSourceGetSize for
121  * additional details.
122  */
123 void AMediaDataSource_setGetSize(
124         AMediaDataSource*,
125         AMediaDataSourceGetSize);
126 
127 /**
128  * Set a custom callback to receive signal from the NDK media framework
129  * when the data source is closed.
130  *
131  * Please refer to the definition of AMediaDataSourceClose for
132  * additional details.
133  */
134 void AMediaDataSource_setClose(
135         AMediaDataSource*,
136         AMediaDataSourceClose);
137 
138 #endif  /*__ANDROID_API__ >= 28 */
139 
140 __END_DECLS
141 
142 #endif // _NDK_MEDIA_DATASOURCE_H
143