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 // Parsing errors. Range: -1025 to -2048. 60 /** 61 An element's ID is malformed. 62 */ 63 kInvalidElementId = -1025, 64 65 /** 66 An element's size is malformed. 67 */ 68 kInvalidElementSize = -1026, 69 70 /** 71 An unknown element has unknown size. 72 */ 73 kIndefiniteUnknownElement = -1027, 74 75 /** 76 A child element overflowed the parent element's bounds. 77 */ 78 kElementOverflow = -1028, 79 80 /** 81 An element's size exceeds the system's memory limits. 82 */ 83 kNotEnoughMemory = -1029, 84 85 /** 86 An element's value is illegal/malformed. 87 */ 88 kInvalidElementValue = -1030, 89 90 /** 91 A recursive element was so deeply nested that exceeded the parser's limit. 92 */ 93 kExceededRecursionDepthLimit = -1031, 94 95 // The following codes are internal-only and should not be used by users. 96 // Additionally, these codes should never be returned to the user; doing so 97 // is considered a bug. 98 /** 99 \internal Parsing should switch from reading to skipping elements. 100 */ 101 kSwitchToSkip = INT32_MIN, 102 }; 103 104 /** 105 Status codes <= 0 are reserved by the parsing library. User error codes 106 should be positive (> 0). Users are encouraged to use codes from the `Code` 107 enum, but may use a positive error code if some application-specific error is 108 encountered. 109 */ 110 std::int32_t code; 111 112 Status() = default; 113 Status(const Status&) = default; 114 Status(Status&&) = default; 115 Status& operator=(const Status&) = default; 116 Status& operator=(Status&&) = default; 117 118 /** 119 Creates a new `Status` object with the given status code. 120 121 \param code The status code which will be used to set the `code` member. 122 */ StatusStatus123 constexpr explicit Status(Code code) : code(code) {} 124 125 /** 126 Creates a new `Status` object with the given status code. 127 128 \param code The status code which will be used to set the `code` member. 129 */ StatusStatus130 constexpr explicit Status(std::int32_t code) : code(code) {} 131 132 /** 133 Returns true if the status code is either `kOkCompleted` or `kOkPartial`. 134 Provided for convenience. 135 */ okStatus136 constexpr bool ok() const { 137 return code == kOkCompleted || code == kOkPartial; 138 } 139 140 /** 141 Returns true if the status code is `kOkCompleted`. Provided for convenience. 142 */ completed_okStatus143 constexpr bool completed_ok() const { return code == kOkCompleted; } 144 145 /** 146 Returns true if the status is considered a parsing error. Parsing errors 147 represent unrecoverable errors due to malformed data. Only status codes in 148 the range -2048 to -1025 (inclusive) are considered parsing errors. 149 */ is_parsing_errorStatus150 constexpr bool is_parsing_error() const { 151 return -2048 <= code && code <= -1025; 152 } 153 }; 154 155 /** 156 @} 157 */ 158 159 } // namespace webm 160 161 #endif // INCLUDE_WEBM_STATUS_H_ 162