1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2023 Google LLC. All rights reserved.
3 //
4 // Use of this source code is governed by a BSD-style
5 // license that can be found in the LICENSE file or at
6 // https://developers.google.com/open-source/licenses/bsd
7
8 #ifndef UPB_IO_ZERO_COPY_INPUT_STREAM_H_
9 #define UPB_IO_ZERO_COPY_INPUT_STREAM_H_
10
11 #include "upb/base/status.h"
12
13 // Must be last.
14 #include "upb/port/def.inc"
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 typedef struct upb_ZeroCopyInputStream upb_ZeroCopyInputStream;
21
22 typedef struct {
23 // Obtains a chunk of data from the stream.
24 //
25 // Preconditions:
26 // "count" and "status" are not NULL.
27 //
28 // Postconditions:
29 // All errors are permanent. If an error occurs then:
30 // - NULL will be returned to the caller.
31 // - *count will be set to zero.
32 // - *status will be set to the error.
33 // EOF is permanent. If EOF is reached then:
34 // - NULL will be returned to the caller.
35 // - *count will be set to zero.
36 // - *status will not be touched.
37 // Otherwise:
38 // - The returned value will point to a buffer containing the bytes read.
39 // - *count will be set to the number of bytes read.
40 // - *status will not be touched.
41 //
42 // Ownership of this buffer remains with the stream, and the buffer
43 // remains valid only until some other method of the stream is called
44 // or the stream is destroyed.
45 const void* (*Next)(struct upb_ZeroCopyInputStream* z, size_t* count,
46 upb_Status* status);
47
48 // Backs up a number of bytes, so that the next call to Next() returns
49 // data again that was already returned by the last call to Next(). This
50 // is useful when writing procedures that are only supposed to read up
51 // to a certain point in the input, then return. If Next() returns a
52 // buffer that goes beyond what you wanted to read, you can use BackUp()
53 // to return to the point where you intended to finish.
54 //
55 // Preconditions:
56 // * The last method called must have been Next().
57 // * count must be less than or equal to the size of the last buffer
58 // returned by Next().
59 //
60 // Postconditions:
61 // * The last "count" bytes of the last buffer returned by Next() will be
62 // pushed back into the stream. Subsequent calls to Next() will return
63 // the same data again before producing new data.
64 void (*BackUp)(struct upb_ZeroCopyInputStream* z, size_t count);
65
66 // Skips a number of bytes. Returns false if the end of the stream is
67 // reached or some input error occurred. In the end-of-stream case, the
68 // stream is advanced to the end of the stream (so ByteCount() will return
69 // the total size of the stream).
70 bool (*Skip)(struct upb_ZeroCopyInputStream* z, size_t count);
71
72 // Returns the total number of bytes read since this object was created.
73 size_t (*ByteCount)(const struct upb_ZeroCopyInputStream* z);
74 } _upb_ZeroCopyInputStream_VTable;
75
76 struct upb_ZeroCopyInputStream {
77 const _upb_ZeroCopyInputStream_VTable* vtable;
78 };
79
upb_ZeroCopyInputStream_Next(upb_ZeroCopyInputStream * z,size_t * count,upb_Status * status)80 UPB_INLINE const void* upb_ZeroCopyInputStream_Next(upb_ZeroCopyInputStream* z,
81 size_t* count,
82 upb_Status* status) {
83 const void* out = z->vtable->Next(z, count, status);
84 UPB_ASSERT((out == NULL) == (*count == 0));
85 return out;
86 }
87
upb_ZeroCopyInputStream_BackUp(upb_ZeroCopyInputStream * z,size_t count)88 UPB_INLINE void upb_ZeroCopyInputStream_BackUp(upb_ZeroCopyInputStream* z,
89 size_t count) {
90 return z->vtable->BackUp(z, count);
91 }
92
upb_ZeroCopyInputStream_Skip(upb_ZeroCopyInputStream * z,size_t count)93 UPB_INLINE bool upb_ZeroCopyInputStream_Skip(upb_ZeroCopyInputStream* z,
94 size_t count) {
95 return z->vtable->Skip(z, count);
96 }
97
98 UPB_INLINE size_t
upb_ZeroCopyInputStream_ByteCount(const upb_ZeroCopyInputStream * z)99 upb_ZeroCopyInputStream_ByteCount(const upb_ZeroCopyInputStream* z) {
100 return z->vtable->ByteCount(z);
101 }
102
103 #ifdef __cplusplus
104 } /* extern "C" */
105 #endif
106
107 #include "upb/port/undef.inc"
108
109 #endif /* UPB_IO_ZERO_COPY_INPUT_STREAM_H_ */
110