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
24namespace android {
25
26struct MediaSource;
27class MetaData;
28class MediaBuffer;
29class MediaBufferGroup;
30
31class IMediaSource : public IInterface {
32public:
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
131class BnMediaSource: public BnInterface<IMediaSource>
132{
133public:
134    BnMediaSource();
135
136    virtual status_t    onTransact(uint32_t code, const Parcel& data, Parcel* reply,
137                                uint32_t flags = 0);
138
139    virtual status_t pause() {
140        return ERROR_UNSUPPORTED;
141    }
142
143    virtual status_t setBuffers(const Vector<MediaBuffer *> & /* buffers */) {
144        return ERROR_UNSUPPORTED;
145    }
146
147    virtual status_t readMultiple(
148            Vector<MediaBuffer *> * /* buffers */, uint32_t /* maxNumBuffers = 1 */) {
149        return ERROR_UNSUPPORTED;
150    }
151protected:
152    virtual ~BnMediaSource();
153
154private:
155    MediaBufferGroup *mGroup;
156};
157
158
159}  // namespace android
160
161#endif  // IMEDIA_SOURCE_BASE_H_
162