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_STATUS_H_ 9 #define INCLUDE_WEBM_STATUS_H_ 10 11 #include <cstdint> 12 13 /** 14 \file 15 Status information that represents success, failure, etc. for operations 16 throughout the API. 17 */ 18 19 namespace webm { 20 21 /** 22 \addtogroup PUBLIC_API 23 @{ 24 */ 25 26 /** 27 An object used to represent the resulting status of various operations, 28 indicating success, failure, or some other result. 29 */ 30 struct Status { 31 /** 32 A list of generic status codes used by the parser. Users are encouraged to 33 reuse these values as needed in the derivations of `Callback`. These values 34 will always be <= 0. 35 */ 36 enum Code : std::int32_t { 37 // General status codes. Range: 0 to -1024. 38 /** 39 The operation successfully completed. 40 */ 41 kOkCompleted = 0, 42 43 /** 44 The operation was successful but only partially completed (for example, a 45 read that resulted in fewer bytes than requested). 46 */ 47 kOkPartial = -1, 48 49 /** 50 The operation would block, and should be tried again later. 51 */ 52 kWouldBlock = -2, 53 54 /** 55 More data was requested but the file has ended. 56 */ 57 kEndOfFile = -3, 58 59 /** 60 The reader was unable to seek to the requested location. 61 */ 62 kSeekFailed = -4, 63 64 // Parsing errors. Range: -1025 to -2048. 65 /** 66 An element's ID is malformed. 67 */ 68 kInvalidElementId = -1025, 69 70 /** 71 An element's size is malformed. 72 */ 73 kInvalidElementSize = -1026, 74 75 /** 76 An unknown element has unknown size. 77 */ 78 kIndefiniteUnknownElement = -1027, 79 80 /** 81 A child element overflowed the parent element's bounds. 82 */ 83 kElementOverflow = -1028, 84 85 /** 86 An element's size exceeds the system's memory limits. 87 */ 88 kNotEnoughMemory = -1029, 89 90 /** 91 An element's value is illegal/malformed. 92 */ 93 kInvalidElementValue = -1030, 94 95 /** 96 A recursive element was so deeply nested that exceeded the parser's limit. 97 */ 98 kExceededRecursionDepthLimit = -1031, 99 100 // The following codes are internal-only and should not be used by users. 101 // Additionally, these codes should never be returned to the user; doing so 102 // is considered a bug. 103 /** 104 \internal Parsing should switch from reading to skipping elements. 105 */ 106 kSwitchToSkip = INT32_MIN, 107 }; 108 109 /** 110 Status codes <= 0 are reserved by the parsing library. User error codes 111 should be positive (> 0). Users are encouraged to use codes from the `Code` 112 enum, but may use a positive error code if some application-specific error is 113 encountered. 114 */ 115 std::int32_t code; 116 117 Status() = default; 118 Status(const Status&) = default; 119 Status(Status&&) = default; 120 Status& operator=(const Status&) = default; 121 Status& operator=(Status&&) = default; 122 123 /** 124 Creates a new `Status` object with the given status code. 125 126 \param code The status code which will be used to set the `code` member. 127 */ StatusStatus128 constexpr explicit Status(Code code) : code(code) {} 129 130 /** 131 Creates a new `Status` object with the given status code. 132 133 \param code The status code which will be used to set the `code` member. 134 */ StatusStatus135 constexpr explicit Status(std::int32_t code) : code(code) {} 136 137 /** 138 Returns true if the status code is either `kOkCompleted` or `kOkPartial`. 139 Provided for convenience. 140 */ okStatus141 constexpr bool ok() const { 142 return code == kOkCompleted || code == kOkPartial; 143 } 144 145 /** 146 Returns true if the status code is `kOkCompleted`. Provided for convenience. 147 */ completed_okStatus148 constexpr bool completed_ok() const { return code == kOkCompleted; } 149 150 /** 151 Returns true if the status is considered a parsing error. Parsing errors 152 represent unrecoverable errors due to malformed data. Only status codes in 153 the range -2048 to -1025 (inclusive) are considered parsing errors. 154 */ is_parsing_errorStatus155 constexpr bool is_parsing_error() const { 156 return -2048 <= code && code <= -1025; 157 } 158 }; 159 160 /** 161 @} 162 */ 163 164 } // namespace webm 165 166 #endif // INCLUDE_WEBM_STATUS_H_ 167