Ion C
C library for Ion
Loading...
Searching...
No Matches
ion_stream.h
Go to the documentation of this file.
1/*
2 * Copyright 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License").
5 * You may not use this file except in compliance with the License.
6 * A copy of the License is located at:
7 *
8 * http://aws.amazon.com/apache2.0/
9 *
10 * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
12 * language governing permissions and limitations under the License.
13 */
16/*
17 * updated versions of the file stream handling support for
18 * the IonC readers and writers.
19 *
20 * fn_fill - updates the streams buffer, curr, limit and max
21 * fields. Should return -1 on eof or bytes read
22 * or error. For a writable stream this may need to
23 * append an empty buffer.
24 *
25 * fn_unread- unreads a byte when there is no room in the current
26 * buffer to hold the unread byte. This will not get
27 * called with an EOF value. Normal behavior is to create
28 * an empty buffer that "preceeds" the current buffer and
29 * write the byte there. It may use the the actual previous
30 * buffer. Or it may fail.
31 *
32 * fn_flush - writes any dirty data out to the output stream.
33 *
34 * fn_close - releases any resources as needed.
35 *
36
37
38 MISSING: skip, fixes for block read/unread, collapse some functions
39
40
41 use cases:
42
43 read only stream - (aka (can write == false)
44 --next char
45 if not end of buffer - done
46 if user buffer - fail
47 find next page
48 if not found
49 if mark allocate new page
50 fill page from last read position
51 --unread
52 if beginning of page
53 find previous page
54 else (not found)
55 create temp page
56 mark as fake
57 save current page
58 make new (found or temp) page current @ end of page
59 back up in current page
60 --write - fail
61 --seek - fail
62 --skip N
63 next char N times
64
65 write only stream - (aka (can read == false)
66 --next char - fail
67 --unread - fail
68 --write
69 if no room
70 write current page to disk
71 release current page
72 get new page
73 fill page
74 make page current @ beginning of buf
75 update dirty pointers
76 --seek - fail
77 --skip - fail
78
79----- read only and write only streams are not seekable
80
81 user buffer
82 --to initialize allocate stream and 1 page set up page to point to user buffer
83 --next char
84 if end of buffer fail with EOF
85 --unread
86 if beginning of buffer - fail
87 back up in current buffer
88 --write
89 if write past buffer length - fail
90 write at current position
91 update dirty pointers
92 --seek
93 if position outside buffer - fail
94 set position
95 --skip
96 compute new position
97 seek to new position
98
99 seekable (read/write)
100 --next char - fail
101 --unread - fail
102 --write
103 if no room in current
104 find next page
105 if not found
106 make page
107 seek to page
108 fill page
109 write data at page
110 update dirty pointers
111 --seek
112 find page
113 if not found
114 make page
115 seek in file to page start
116 fill page
117 make page current
118 set position @ position in page
119 --skip
120 compute new position
121 seek to new position
122
123 ----make page
124 when not buffering
125 flush current page
126 release current page
127 allocate page
128
129 ----make page current
130 if page != current page
131 flush current page
132 if not buffering release current page
133 set up stream members to new page
134 clear dirty pointers
135 *
136 */
137
138#ifndef ION_STREAM_H_
139#define ION_STREAM_H_
140
141#include "ion_types.h"
142#include "ion_platform_config.h"
143#include "ion_errors.h"
144
145#ifdef __cplusplus
146extern "C" {
147#endif
148
149#ifndef ION_STREAM_DECL
150#define ION_STREAM_DECL
151
152// needed when the stream is used outside the context of the
153// general Ion library. Otherwise this must be defined in the
154// Ion type header (ion_types.h).
155typedef struct _ion_stream ION_STREAM;
156
157// decl's for user managed stream
158typedef iERR (*ION_STREAM_HANDLER)(struct _ion_user_stream *pstream);
159struct _ion_user_stream
160{
161 BYTE *curr;
162 BYTE *limit;
163 void *handler_state;
164 ION_STREAM_HANDLER handler;
165};
166
167#endif
168
169typedef struct _ion_stream_user_paged ION_STREAM_USER_PAGED;
170typedef struct _ion_stream_paged ION_STREAM_PAGED;
171typedef struct _ion_page ION_PAGE;
172typedef int32_t PAGE_ID;
173typedef int64_t POSITION;
174
176
177// public constructors
178
180
181
182ION_API_EXPORT iERR ion_stream_open_buffer(BYTE *buffer // pointer to memory to stream over
183 , SIZE buf_length // length of user buffer, filled or not
184 , SIZE buf_filled // length of user filled data (0 or more bytes)
185 , BOOL read_only // if read_only is true write is disallowed (read is always valid)
186 , ION_STREAM **pp_stream
187);
188ION_API_EXPORT iERR ion_stream_open_memory_only(ION_STREAM **pp_stream);
189
190ION_API_EXPORT iERR ion_stream_open_stdin(ION_STREAM **pp_stream);
191ION_API_EXPORT iERR ion_stream_open_stdout(ION_STREAM **pp_stream);
192ION_API_EXPORT iERR ion_stream_open_stderr(ION_STREAM **pp_stream);
193
194ION_API_EXPORT iERR ion_stream_open_file_in(FILE *in, ION_STREAM **pp_stream);
195ION_API_EXPORT iERR ion_stream_open_file_out(FILE *out, ION_STREAM **pp_stream);
196ION_API_EXPORT iERR ion_stream_open_file_rw(FILE *fp, BOOL cache_all, ION_STREAM **pp_stream);
197
198ION_API_EXPORT iERR ion_stream_open_handler_in(ION_STREAM_HANDLER fn_input_handler, void *handler_state, ION_STREAM **pp_stream);
199ION_API_EXPORT iERR ion_stream_open_handler_out(ION_STREAM_HANDLER fn_output_handler, void *handler_state, ION_STREAM **pp_stream);
200
201ION_API_EXPORT iERR ion_stream_open_fd_in(int fd_in, ION_STREAM **pp_stream);
202ION_API_EXPORT iERR ion_stream_open_fd_out(int fd_out, ION_STREAM **pp_stream);
203ION_API_EXPORT iERR ion_stream_open_fd_rw(int fd, BOOL cache_all, ION_STREAM **pp_stream);
204
205ION_API_EXPORT iERR ion_stream_flush(ION_STREAM *stream);
206ION_API_EXPORT iERR ion_stream_close(ION_STREAM *stream);
207
209
210// informational routines (aka getters)
211
213
214ION_API_EXPORT BOOL ion_stream_can_read (ION_STREAM *stream);
215ION_API_EXPORT BOOL ion_stream_can_write (ION_STREAM *stream);
216ION_API_EXPORT BOOL ion_stream_can_seek (ION_STREAM *stream);
217ION_API_EXPORT BOOL ion_stream_can_mark (ION_STREAM *stream);
218ION_API_EXPORT BOOL ion_stream_is_dirty (ION_STREAM *stream);
219ION_API_EXPORT BOOL ion_stream_is_mark_open (ION_STREAM *stream);
220ION_API_EXPORT POSITION ion_stream_get_position (ION_STREAM *stream);
221ION_API_EXPORT FILE *ion_stream_get_file_stream (ION_STREAM *stream);
222ION_API_EXPORT POSITION ion_stream_get_mark_start (ION_STREAM *stream);
223ION_API_EXPORT POSITION ion_stream_get_marked_length (ION_STREAM *stream);
224
226
227// public instance methods
228
230
231ION_API_EXPORT iERR ion_stream_read_byte (ION_STREAM *stream, int *p_c);
232ION_API_EXPORT iERR ion_stream_read (ION_STREAM *stream, BYTE *buf, SIZE len, SIZE *p_bytes_read);
233ION_API_EXPORT iERR ion_stream_unread_byte (ION_STREAM *stream, int c);
234ION_API_EXPORT iERR ion_stream_write (ION_STREAM *stream, BYTE *buf, SIZE len, SIZE *p_bytes_written);
235ION_API_EXPORT iERR ion_stream_write_byte (ION_STREAM *stream, int byte);
236ION_API_EXPORT iERR ion_stream_write_byte_no_checks(ION_STREAM *stream, int byte);
237ION_API_EXPORT iERR ion_stream_write_stream (ION_STREAM *stream, ION_STREAM *stream_input, SIZE len, SIZE *p_written);
238ION_API_EXPORT iERR ion_stream_seek (ION_STREAM *stream, POSITION position);
239ION_API_EXPORT iERR ion_stream_truncate (ION_STREAM *stream);
240ION_API_EXPORT iERR ion_stream_skip (ION_STREAM *stream, SIZE distance, SIZE *p_skipped);
241ION_API_EXPORT iERR ion_stream_mark (ION_STREAM *stream);
242ION_API_EXPORT iERR ion_stream_mark_remark (ION_STREAM *stream, POSITION position);
243ION_API_EXPORT iERR ion_stream_mark_rewind (ION_STREAM *stream);
244ION_API_EXPORT iERR ion_stream_mark_clear (ION_STREAM *stream);
245
246#ifdef __cplusplus
247}
248#endif
249
250#endif /* ION_STREAM_H_ */
ion_errors.h
ion_platform_config.h
ion_types.h
_ion_user_stream
Definition ion_types.h:159