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 MEDIA_SOURCE_H_
18
19#define MEDIA_SOURCE_H_
20
21#include <sys/types.h>
22
23#include <media/IMediaSource.h>
24#include <media/stagefright/MediaErrors.h>
25#include <utils/RefBase.h>
26#include <utils/Vector.h>
27
28namespace android {
29
30class MediaBuffer;
31class MetaData;
32
33struct MediaSource : public BnMediaSource {
34    MediaSource();
35
36    // To be called before any other methods on this object, except
37    // getFormat().
38    virtual status_t start(MetaData *params = NULL) = 0;
39
40    // Any blocking read call returns immediately with a result of NO_INIT.
41    // It is an error to call any methods other than start after this call
42    // returns. Any buffers the object may be holding onto at the time of
43    // the stop() call are released.
44    // Also, it is imperative that any buffers output by this object and
45    // held onto by callers be released before a call to stop() !!!
46    virtual status_t stop() = 0;
47
48    // Returns the format of the data output by this media source.
49    virtual sp<MetaData> getFormat() = 0;
50
51    // Returns a new buffer of data. Call blocks until a
52    // buffer is available, an error is encountered of the end of the stream
53    // is reached.
54    // End of stream is signalled by a result of ERROR_END_OF_STREAM.
55    // A result of INFO_FORMAT_CHANGED indicates that the format of this
56    // MediaSource has changed mid-stream, the client can continue reading
57    // but should be prepared for buffers of the new configuration.
58    virtual status_t read(
59            MediaBuffer **buffer, const ReadOptions *options = NULL) = 0;
60
61    // Causes this source to suspend pulling data from its upstream source
62    // until a subsequent read-with-seek. This is currently not supported
63    // as such by any source. E.g. MediaCodecSource does not suspend its
64    // upstream source, and instead discard upstream data while paused.
65    virtual status_t pause() {
66        return ERROR_UNSUPPORTED;
67    }
68
69    // The consumer of this media source requests that the given buffers
70    // are to be returned exclusively in response to read calls.
71    // This will be called after a successful start() and before the
72    // first read() call.
73    // Callee assumes ownership of the buffers if no error is returned.
74    virtual status_t setBuffers(const Vector<MediaBuffer *> & /* buffers */) {
75        return ERROR_UNSUPPORTED;
76    }
77
78protected:
79    virtual ~MediaSource();
80
81private:
82    MediaSource(const MediaSource &);
83    MediaSource &operator=(const MediaSource &);
84};
85
86}  // namespace android
87
88#endif  // MEDIA_SOURCE_H_
89