1 /*
2  * Copyright (C) 2009 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 IMEDIA_SOURCE_BASE_H_
18 
19 #define IMEDIA_SOURCE_BASE_H_
20 
21 #include <binder/IInterface.h>
22 #include <media/stagefright/MediaErrors.h>
23 
24 namespace android {
25 
26 struct MediaSource;
27 class MetaData;
28 class MediaBuffer;
29 class MediaBufferGroup;
30 
31 class IMediaSource : public IInterface {
32 public:
33     DECLARE_META_INTERFACE(MediaSource);
34 
35     enum {
36         // Maximum number of buffers would be read in readMultiple.
37         kMaxNumReadMultiple = 128,
38     };
39 
40     // To be called before any other methods on this object, except
41     // getFormat().
42     virtual status_t start(MetaData *params = NULL) = 0;
43 
44     // Any blocking read call returns immediately with a result of NO_INIT.
45     // It is an error to call any methods other than start after this call
46     // returns. Any buffers the object may be holding onto at the time of
47     // the stop() call are released.
48     // Also, it is imperative that any buffers output by this object and
49     // held onto by callers be released before a call to stop() !!!
50     virtual status_t stop() = 0;
51 
52     // Returns the format of the data output by this media source.
53     virtual sp<MetaData> getFormat() = 0;
54 
55     // Options that modify read() behaviour. The default is to
56     // a) not request a seek
57     // b) not be late, i.e. lateness_us = 0
58     struct ReadOptions {
59         enum SeekMode {
60             SEEK_PREVIOUS_SYNC,
61             SEEK_NEXT_SYNC,
62             SEEK_CLOSEST_SYNC,
63             SEEK_CLOSEST,
64         };
65 
66         ReadOptions();
67 
68         // Reset everything back to defaults.
69         void reset();
70 
71         void setSeekTo(int64_t time_us, SeekMode mode = SEEK_CLOSEST_SYNC);
72         void clearSeekTo();
73         bool getSeekTo(int64_t *time_us, SeekMode *mode) const;
74 
75         void setLateBy(int64_t lateness_us);
76         int64_t getLateBy() const;
77 
78         void setNonBlocking();
79         void clearNonBlocking();
80         bool getNonBlocking() const;
81 
82     private:
83         enum Options {
84             kSeekTo_Option      = 1,
85         };
86 
87         uint32_t mOptions;
88         int64_t mSeekTimeUs;
89         SeekMode mSeekMode;
90         int64_t mLatenessUs;
91         bool mNonBlocking;
92     };
93 
94     // Returns a new buffer of data. Call blocks until a
95     // buffer is available, an error is encountered or the end of the stream
96     // is reached.
97     // End of stream is signalled by a result of ERROR_END_OF_STREAM.
98     // A result of INFO_FORMAT_CHANGED indicates that the format of this
99     // MediaSource has changed mid-stream, the client can continue reading
100     // but should be prepared for buffers of the new configuration.
101     virtual status_t read(
102             MediaBuffer **buffer, const ReadOptions *options = NULL) = 0;
103 
104     // Returns a vector of new buffers of data. The vector size could be
105     // <= |maxNumBuffers|. Used for buffers with small size
106     // since all buffer data are passed back by binder, not shared memory.
107     // Call blocks until an error is encountered, or the end of the stream is
108     // reached, or format change is hit, or |kMaxNumReadMultiple| buffers have
109     // been read.
110     // End of stream is signalled by a result of ERROR_END_OF_STREAM.
111     // A result of INFO_FORMAT_CHANGED indicates that the format of this
112     // MediaSource has changed mid-stream, the client can continue reading
113     // but should be prepared for buffers of the new configuration.
114     virtual status_t readMultiple(
115             Vector<MediaBuffer *> *buffers, uint32_t maxNumBuffers = 1) = 0;
116 
117     // Causes this source to suspend pulling data from its upstream source
118     // until a subsequent read-with-seek. Currently only supported by
119     // OMXCodec.
120     virtual status_t pause()  = 0;
121 
122     // The consumer of this media source requests that the given buffers
123     // are to be returned exclusively in response to read calls.
124     // This will be called after a successful start() and before the
125     // first read() call.
126     // Callee assumes ownership of the buffers if no error is returned.
127     virtual status_t setBuffers(const Vector<MediaBuffer *> & /* buffers */) = 0;
128 
129 };
130 
131 class BnMediaSource: public BnInterface<IMediaSource>
132 {
133 public:
134     BnMediaSource();
135 
136     virtual status_t    onTransact(uint32_t code, const Parcel& data, Parcel* reply,
137                                 uint32_t flags = 0);
138 
pause()139     virtual status_t pause() {
140         return ERROR_UNSUPPORTED;
141     }
142 
setBuffers(const Vector<MediaBuffer * > &)143     virtual status_t setBuffers(const Vector<MediaBuffer *> & /* buffers */) {
144         return ERROR_UNSUPPORTED;
145     }
146 
readMultiple(Vector<MediaBuffer * > *,uint32_t)147     virtual status_t readMultiple(
148             Vector<MediaBuffer *> * /* buffers */, uint32_t /* maxNumBuffers = 1 */) {
149         return ERROR_UNSUPPORTED;
150     }
151 protected:
152     virtual ~BnMediaSource();
153 
154 private:
155     MediaBufferGroup *mGroup;
156 };
157 
158 
159 }  // namespace android
160 
161 #endif  // IMEDIA_SOURCE_BASE_H_
162