| // Copyright (c) 2016 The WebM project authors. All Rights Reserved. |
| // |
| // Use of this source code is governed by a BSD-style license |
| // that can be found in the LICENSE file in the root of the source |
| // tree. An additional intellectual property rights grant can be found |
| // in the file PATENTS. All contributing project authors may |
| // be found in the AUTHORS file in the root of the source tree. |
| #ifndef INCLUDE_WEBM_CALLBACK_H_ |
| #define INCLUDE_WEBM_CALLBACK_H_ |
| |
| #include <cstdint> |
| |
| #include "./dom_types.h" |
| #include "./reader.h" |
| #include "./status.h" |
| |
| /** |
| \file |
| The main callback type that receives parsing events. |
| */ |
| |
| namespace webm { |
| |
| /** |
| \addtogroup PUBLIC_API |
| @{ |
| */ |
| |
| /** |
| The action to be performed when parsing an element. |
| */ |
| enum class Action { |
| /** |
| Read and parse the element. |
| */ |
| kRead, |
| |
| /** |
| Skip the element. Skipped elements are not parsed or stored, and the callback |
| is not given any further notifications regarding the element. |
| */ |
| kSkip, |
| }; |
| |
| /** |
| A callback that receives parsing events. |
| |
| Every method that returns a `Status` should return `Status::kOkCompleted` when |
| the method has completed and parsing should continue. Returning any other value |
| will cause parsing to stop. Parsing may be resumed if the returned status was |
| not a parsing error (see `Status::is_parsing_error()`). When parsing is |
| resumed, the same `Callback` method will be called again. |
| |
| Methods that take a `Reader` expect the implementation to consume (either via |
| `Reader::Read()` or `Reader::Skip()`) the specified number of bytes before |
| returning `Status::kOkCompleted`. Default implementations will call |
| `Reader::Skip()` to skip the specified number of bytes and the resulting |
| `Status` will be returned (unless it's `Status::kOkPartial`, in which case |
| `Reader::Skip()` will be called again to skip more data). |
| |
| Throwing an exception from the member functions is permitted, though if the |
| exception will be caught and parsing resumed, then the reader should not |
| advance its position (for methods that take a `Reader`) before the exception is |
| thrown. When parsing is resumed, the same `Callback` method will be called |
| again. |
| |
| Users should derive from this class and override member methods as needed. |
| */ |
| class Callback { |
| public: |
| virtual ~Callback() = default; |
| |
| /** |
| Called when the parser starts a new element. This is called after the |
| elements ID and size has been parsed, but before any of its body has been |
| read (or validated). |
| |
| Defaults to `Action::kRead` and returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element that has just been encountered. |
| \param[out] action The action that should be taken when handling this |
| element. Will not be null. |
| */ |
| virtual Status OnElementBegin(const ElementMetadata& metadata, |
| Action* action); |
| |
| /** |
| Called when the parser encounters an unknown element. |
| |
| Defaults to calling (and returning the result of) `Reader::Skip()`. |
| |
| \param metadata Metadata about the element. |
| \param reader The reader that should be used to consume data. Will not be |
| null. |
| \param[in,out] bytes_remaining The number of remaining bytes that need to be |
| consumed for the element. Will not be null. |
| \return `Status::kOkCompleted` when the element has been fully consumed and |
| `bytes_remaining` is now zero. |
| */ |
| virtual Status OnUnknownElement(const ElementMetadata& metadata, |
| Reader* reader, |
| std::uint64_t* bytes_remaining); |
| |
| /** |
| Called when the parser encounters an `Id::kEbml` element and it has been |
| fully parsed. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param ebml The parsed element. |
| */ |
| virtual Status OnEbml(const ElementMetadata& metadata, const Ebml& ebml); |
| |
| /** |
| Called when the parser encounters an Id::kVoid element. |
| |
| Defaults to calling (and returning the result of) Reader::Skip. |
| |
| \param metadata Metadata about the element. |
| \param reader The reader that should be used to consume data. Will not be |
| null. |
| \param[in,out] bytes_remaining The number of remaining bytes that need to be |
| consumed for the element. Will not be null. |
| \return `Status::kOkCompleted` when the element has been fully consumed and |
| `bytes_remaining` is now zero. |
| */ |
| virtual Status OnVoid(const ElementMetadata& metadata, Reader* reader, |
| std::uint64_t* bytes_remaining); |
| |
| /** |
| Called when the parser starts an `Id::kSegment` element. |
| |
| Defaults to `Action::kRead` and returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element that has just been encountered. |
| \param[out] action The action that should be taken when handling this |
| element. Will not be null. |
| */ |
| virtual Status OnSegmentBegin(const ElementMetadata& metadata, |
| Action* action); |
| |
| /** |
| Called when the parser encounters an `Id::kSeek` element and it has been |
| fully parsed. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param seek The parsed element. |
| */ |
| virtual Status OnSeek(const ElementMetadata& metadata, const Seek& seek); |
| |
| /** |
| Called when the parser encounters an `Id::kInfo` element and it has been |
| fully parsed. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param info The parsed element. |
| */ |
| virtual Status OnInfo(const ElementMetadata& metadata, const Info& info); |
| |
| /** |
| Called when the parser starts an `Id::kCluster` element. |
| |
| Because Cluster elements should start with a Timecode (and optionally |
| PrevSize) child, this method is not invoked until a child BlockGroup or |
| SimpleBlock element is encountered (or the Cluster ends if no such child |
| exists). |
| |
| Defaults to `Action::kRead` and returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param cluster The element, as it has currently been parsed. |
| \param[out] action The action that should be taken when handling this |
| element. Will not be null. |
| */ |
| virtual Status OnClusterBegin(const ElementMetadata& metadata, |
| const Cluster& cluster, Action* action); |
| |
| /** |
| Called when the parser starts an `Id::kSimpleBlock` element. |
| |
| Defaults to `Action::kRead` and returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param simple_block The parsed SimpleBlock header. |
| \param[out] action The action that should be taken when handling this |
| element. Will not be null. |
| */ |
| virtual Status OnSimpleBlockBegin(const ElementMetadata& metadata, |
| const SimpleBlock& simple_block, |
| Action* action); |
| |
| /** |
| Called when the parser finishes an `Id::kSimpleBlock` element. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param simple_block The parsed SimpleBlock header. |
| */ |
| virtual Status OnSimpleBlockEnd(const ElementMetadata& metadata, |
| const SimpleBlock& simple_block); |
| |
| /** |
| Called when the parser starts an `Id::kBlockGroup` element. |
| |
| Defaults to `Action::kRead` and returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param[out] action The action that should be taken when handling this |
| element. Will not be null. |
| */ |
| virtual Status OnBlockGroupBegin(const ElementMetadata& metadata, |
| Action* action); |
| |
| /** |
| Called when the parser starts an `Id::kBlock` element. |
| |
| Defaults to `Action::kRead` and returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param block The parsed Block header. |
| \param[out] action The action that should be taken when handling this |
| element. Will not be null. |
| */ |
| virtual Status OnBlockBegin(const ElementMetadata& metadata, |
| const Block& block, Action* action); |
| |
| /** |
| Called when the parser finishes an `Id::Block` element. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param block The parsed Block header. |
| */ |
| virtual Status OnBlockEnd(const ElementMetadata& metadata, |
| const Block& block); |
| |
| /** |
| Called when the parser finishes an `Id::kBlockGroup` element. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param block_group The parsed element. |
| */ |
| virtual Status OnBlockGroupEnd(const ElementMetadata& metadata, |
| const BlockGroup& block_group); |
| |
| /** |
| Called when the parser encounters a frame within a `Id::kBlock` or |
| `Id::kSimpleBlock` element. |
| |
| Defaults to calling (and returning the result of) `Reader::Skip`. |
| |
| \param metadata Metadata about the frame. |
| \param reader The reader that should be used to consume data. Will not be |
| null. |
| \param[in,out] bytes_remaining The number of remaining bytes that need to be |
| consumed for the frame. Will not be null. |
| \return `Status::kOkCompleted` when the frame has been fully consumed and |
| `bytes_remaining` is now zero. |
| */ |
| virtual Status OnFrame(const FrameMetadata& metadata, Reader* reader, |
| std::uint64_t* bytes_remaining); |
| |
| /** |
| Called when the parser finishes an `Id::kCluster` element. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param cluster The parsed element. |
| */ |
| virtual Status OnClusterEnd(const ElementMetadata& metadata, |
| const Cluster& cluster); |
| |
| /** |
| Called when the parser starts an `Id::kTrackEntry` element. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param track_entry The parsed element. |
| */ |
| virtual Status OnTrackEntry(const ElementMetadata& metadata, |
| const TrackEntry& track_entry); |
| |
| /** |
| Called when the parser encounters an `Id::kCuePoint` element and it has been |
| fully parsed. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param cue_point The parsed element. |
| */ |
| virtual Status OnCuePoint(const ElementMetadata& metadata, |
| const CuePoint& cue_point); |
| |
| /** |
| Called when the parser encounters an `Id::kEditionEntry` element and it has |
| been fully parsed. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param edition_entry The parsed element. |
| */ |
| virtual Status OnEditionEntry(const ElementMetadata& metadata, |
| const EditionEntry& edition_entry); |
| |
| /** |
| Called when the parser encounters an `Id::kTag` element and it has been fully |
| parsed. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| \param tag The parsed element. |
| */ |
| virtual Status OnTag(const ElementMetadata& metadata, const Tag& tag); |
| |
| /** |
| Called when the parser finishes an `Id::kSegment` element. |
| |
| Defaults to returning `Status::kOkCompleted`. |
| |
| \param metadata Metadata about the element. |
| */ |
| virtual Status OnSegmentEnd(const ElementMetadata& metadata); |
| |
| protected: |
| /** |
| Calls (and returns the result of) `Reader::Skip()`, skipping (up to) the |
| requested number of bytes. |
| |
| Unlike `Reader::Skip()`, this method may be called with `*bytes_remaining == |
| 0`, which will result in `Status::kOkCompleted`. `Reader::Skip()` will be |
| called multiple times if it returns `Status::kOkPartial` until it returns a |
| different status (indicating the requested number of bytes has been fully |
| skipped or some error occurred). |
| |
| \param reader The reader that should be used to skip data. Must not be null. |
| \param[in,out] bytes_remaining The number of remaining bytes that need to be |
| skipped. Must not be null. May be zero. |
| \return The result of `Reader::Skip()`. |
| */ |
| static Status Skip(Reader* reader, std::uint64_t* bytes_remaining); |
| }; |
| |
| /** |
| @} |
| */ |
| |
| } // namespace webm |
| |
| #endif // INCLUDE_WEBM_CALLBACK_H_ |