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 #ifndef MEDIA_EXTRACTOR_PLUGIN_API_H_
18 #define MEDIA_EXTRACTOR_PLUGIN_API_H_
19 
20 #include <utils/Errors.h> // for status_t
21 #include <media/NdkMediaError.h>
22 struct AMediaFormat;
23 
24 namespace android {
25 
26 struct MediaTrack;
27 class MetaDataBase;
28 class MediaBufferBase;
29 
30 extern "C" {
31 
32 struct CDataSource {
33     ssize_t (*readAt)(void *handle, off64_t offset, void *data, size_t size);
34     status_t (*getSize)(void *handle, off64_t *size);
35     uint32_t (*flags)(void *handle );
36     bool (*getUri)(void *handle, char *uriString, size_t bufferSize);
37     void *handle;
38 };
39 
40 enum CMediaTrackReadOptions : uint32_t {
41     SEEK_PREVIOUS_SYNC = 0,
42     SEEK_NEXT_SYNC = 1,
43     SEEK_CLOSEST_SYNC = 2,
44     SEEK_CLOSEST = 3,
45     SEEK_FRAME_INDEX = 4,
46     SEEK = 8,
47     NONBLOCKING = 16
48 };
49 
50 /**
51  * only use CMediaBuffer allocated from the CMediaBufferGroup that is
52  * provided to CMediaTrack::start()
53  */
54 struct CMediaBuffer {
55     void *handle;
56     void (*release)(void *handle);
57     void* (*data)(void *handle);
58     size_t (*size)(void *handle);
59     size_t (*range_offset)(void *handle);
60     size_t (*range_length)(void *handle);
61     void (*set_range)(void *handle, size_t offset, size_t length);
62     AMediaFormat* (*meta_data)(void *handle);
63 };
64 
65 struct CMediaBufferGroup {
66     void *handle;
67     bool (*init)(void *handle, size_t buffers, size_t buffer_size, size_t growthLimit);
68     void (*add_buffer)(void *handle, size_t size);
69     media_status_t (*acquire_buffer)(void *handle,
70             CMediaBuffer **buffer, bool nonBlocking, size_t requestedSize);
71     bool (*has_buffers)(void *handle);
72 };
73 
74 struct CMediaTrack {
75     void *data;
76     void (*free)(void *data);
77 
78     media_status_t (*start)(void *data, CMediaBufferGroup *bufferGroup);
79     media_status_t (*stop)(void *data);
80     media_status_t (*getFormat)(void *data, AMediaFormat *format);
81     media_status_t (*read)(void *data, CMediaBuffer **buffer, uint32_t options, int64_t seekPosUs);
82     bool     (*supportsNonBlockingRead)(void *data);
83 };
84 
85 struct CMediaExtractor {
86     void *data;
87 
88     void (*free)(void *data);
89     size_t (*countTracks)(void *data);
90     CMediaTrack* (*getTrack)(void *data, size_t index);
91     media_status_t (*getTrackMetaData)(
92             void *data,
93             AMediaFormat *meta,
94             size_t index, uint32_t flags);
95 
96     media_status_t (*getMetaData)(void *data, AMediaFormat *meta);
97     uint32_t (*flags)(void *data);
98     media_status_t (*setMediaCas)(void *data, const uint8_t* casToken, size_t size);
99     const char * (*name)(void *data);
100 };
101 
102 typedef CMediaExtractor* (*CreatorFunc)(CDataSource *source, void *meta);
103 typedef void (*FreeMetaFunc)(void *meta);
104 
105 // The sniffer can optionally fill in an opaque object, "meta", that helps
106 // the corresponding extractor initialize its state without duplicating
107 // effort already exerted by the sniffer. If "freeMeta" is given, it will be
108 // called against the opaque object when it is no longer used.
109 typedef CreatorFunc (*SnifferFunc)(
110         CDataSource *source, float *confidence,
111         void **meta, FreeMetaFunc *freeMeta);
112 
113 typedef CMediaExtractor CMediaExtractor;
114 typedef CreatorFunc CreatorFunc;
115 
116 
117 typedef struct {
118     const uint8_t b[16];
119 } media_uuid_t;
120 
121 struct ExtractorDef {
122     // version number of this structure
123     const uint32_t def_version;
124 
125     // A unique identifier for this extractor.
126     // See below for a convenience macro to create this from a string.
127     media_uuid_t extractor_uuid;
128 
129     // Version number of this extractor. When two extractors with the same
130     // uuid are encountered, the one with the largest version number will
131     // be used.
132     const uint32_t extractor_version;
133 
134     // a human readable name
135     const char *extractor_name;
136 
137     union {
138         struct {
139             SnifferFunc sniff;
140         } v2;
141         struct {
142             SnifferFunc sniff;
143             // a NULL terminated list of container mime types and/or file extensions
144             // that this extractor supports
145             const char **supported_types;
146         } v3;
147     } u;
148 };
149 
150 // the C++ based API which first shipped in P and is no longer supported
151 const uint32_t EXTRACTORDEF_VERSION_LEGACY = 1;
152 
153 // the first C/NDK based API
154 const uint32_t EXTRACTORDEF_VERSION_NDK_V1 = 2;
155 
156 // the second C/NDK based API
157 const uint32_t EXTRACTORDEF_VERSION_NDK_V2 = 3;
158 
159 const uint32_t EXTRACTORDEF_VERSION = EXTRACTORDEF_VERSION_NDK_V2;
160 
161 // each plugin library exports one function of this type
162 typedef ExtractorDef (*GetExtractorDef)();
163 
164 } // extern "C"
165 
166 }  // namespace android
167 
168 #endif  // MEDIA_EXTRACTOR_PLUGIN_API_H_
169