You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
364 lines
12 KiB
364 lines
12 KiB
// 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_
|