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