1 // Copyright (c) 2016 The WebM project authors. All Rights Reserved. 2 // 3 // Use of this source code is governed by a BSD-style license 4 // that can be found in the LICENSE file in the root of the source 5 // tree. An additional intellectual property rights grant can be found 6 // in the file PATENTS. All contributing project authors may 7 // be found in the AUTHORS file in the root of the source tree. 8 #ifndef INCLUDE_WEBM_READER_H_ 9 #define INCLUDE_WEBM_READER_H_ 10 11 #include <cstddef> 12 #include <cstdint> 13 14 #include "./status.h" 15 16 /** 17 \file 18 An interface that acts as a data source for the parser to read from. 19 */ 20 21 namespace webm { 22 23 /** 24 \addtogroup PUBLIC_API 25 @{ 26 */ 27 28 /** 29 A generic interface for reading from a data source. 30 31 Throwing an exception from the member functions is permitted, though if the 32 exception will be caught and parsing resumed, then the reader should not 33 advance its position before throwing the exception. 34 */ 35 class Reader { 36 public: 37 virtual ~Reader() = default; 38 39 /** 40 Reads data from the source and advances the reader's position by the number 41 of bytes read. 42 43 Short reads are permitted, as is reading no data. 44 45 \param num_to_read The number of bytes that should be read. Must not be 0. 46 \param buffer The buffer to store the read bytes. Must be large enough to 47 store at least `num_to_read` bytes. Must not be null. 48 \param[out] num_actually_read The number of bytes that were actually read is 49 stored in this integer. Must not be null. 50 \return `Status::kOkCompleted` if `num_to_read` bytes were read. 51 `Status::kOkPartial` if the number of bytes read is > 0 and < `num_to_read`. 52 If no bytes are read, then some status other than `Status::kOkCompleted` and 53 `Status::kOkPartial` must be returned and `num_actually_read` must be set to 54 0. 55 */ 56 virtual Status Read(std::size_t num_to_read, std::uint8_t* buffer, 57 std::uint64_t* num_actually_read) = 0; 58 59 /** 60 Skips data from the source and advances the reader's position by the number 61 of bytes skipped. 62 63 Short skips are permitted, as is skipping no data. This is similar to the 64 `Read()` method, but does not store data in an output buffer. 65 66 \param num_to_skip The number of bytes that should be skipped. Must not be 0. 67 \param[out] num_actually_skipped The number of bytes that were actually 68 skipped is stored in this integer. Must not be null. 69 \return `Status::kOkCompleted` if `num_to_skip` bytes were skipped. 70 `Status::kOkPartial` if the number of bytes skipped is > 0 and < 71 `num_to_skip`. If no bytes are skipped, then some status other than 72 `Status::kOkCompleted` and `Status::kOkPartial` must be returned and 73 `num_actually_skipped` must be set to 0. 74 */ 75 virtual Status Skip(std::uint64_t num_to_skip, 76 std::uint64_t* num_actually_skipped) = 0; 77 78 /** 79 Gets the Reader's current absolute byte position in the stream. 80 81 Implementations don't necessarily need to start from 0 (which might be the 82 case if parsing is starting in the middle of a data source). The value 83 `kUnknownElementPosition` must not be returned. 84 */ 85 virtual std::uint64_t Position() const = 0; 86 }; 87 88 /** 89 @} 90 */ 91 92 } // namespace webm 93 94 #endif // INCLUDE_WEBM_READER_H_ 95