frameworks/base/include/media/stagefright/MediaSource.h

   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/stagefright/MediaErrors.h>
  24 #include <utils/RefBase.h>
  25
  26 namespace android {
  27
  28 class MediaBuffer;
  29 class MetaData;
  30
  31 struct MediaSource : public RefBase {
  32     MediaSource();
  33
  34     // To be called before any other methods on this object, except
  35     // getFormat().
  36     virtual status_t start(MetaData *params = NULL) = 0;
  37
  38     // Any blocking read call returns immediately with a result of NO_INIT.
  39     // It is an error to call any methods other than start after this call
  40     // returns. Any buffers the object may be holding onto at the time of
  41     // the stop() call are released.
  42     // Also, it is imperative that any buffers output by this object and
  43     // held onto by callers be released before a call to stop() !!!
  44     virtual status_t stop() = 0;
  45
  46     // Returns the format of the data output by this media source.
  47     virtual sp<MetaData> getFormat() = 0;
  48
  49     struct ReadOptions;
  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     // Options that modify read() behaviour. The default is to
  62     // a) not request a seek
  63     // b) not be late, i.e. lateness_us = 0
  64     struct ReadOptions {
  65         enum SeekMode {
  66             SEEK_PREVIOUS_SYNC,
  67             SEEK_NEXT_SYNC,
  68             SEEK_CLOSEST_SYNC,
  69             SEEK_CLOSEST,
  70         };
  71
  72         ReadOptions();
  73
  74         // Reset everything back to defaults.
  75         void reset();
  76
  77         void setSeekTo(int64_t time_us, SeekMode mode = SEEK_CLOSEST_SYNC);
  78         void clearSeekTo();
  79         bool getSeekTo(int64_t *time_us, SeekMode *mode) const;
  80
  81         // Option allows encoder to skip some frames until the specified
  82         // time stamp.
  83         // To prevent from being abused, when the skipFrame timestamp is
  84         // found to be more than 1 second later than the current timestamp,
  85         // an error will be returned from read().
  86         void clearSkipFrame();
  87         bool getSkipFrame(int64_t *timeUs) const;
  88         void setSkipFrame(int64_t timeUs);
  89
  90         void setLateBy(int64_t lateness_us);
  91         int64_t getLateBy() const;
  92
  93     private:
  94         enum Options {
  95             // Bit map
  96             kSeekTo_Option      = 1,
  97             kSkipFrame_Option   = 2,
  98         };
  99
 100         uint32_t mOptions;
 101         int64_t mSeekTimeUs;
 102         SeekMode mSeekMode;
 103         int64_t mLatenessUs;
 104
 105         int64_t mSkipFrameUntilTimeUs;
 106     };
 107
 108     // Causes this source to suspend pulling data from its upstream source
 109     // until a subsequent read-with-seek. Currently only supported by
 110     // OMXCodec.
 111     virtual status_t pause() {
 112         return ERROR_UNSUPPORTED;
 113     }
 114
 115 protected:
 116     virtual ~MediaSource();
 117
 118 private:
 119     MediaSource(const MediaSource &);
 120     MediaSource &operator=(const MediaSource &);
 121 };
 122
 123 }  // namespace android
 124
 125 #endif  // MEDIA_SOURCE_H_