NCBI C++ ToolKit
reader_writer.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CORELIB___READER_WRITER__HPP
2 #define CORELIB___READER_WRITER__HPP
3 
4 /* $Id: reader_writer.hpp 89418 2020-03-27 22:47:07Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Anton Lavrentiev
30  *
31  * File Description:
32  * Abstract reader-writer interface classes
33  *
34  */
35 
36 /// @file reader_writer.hpp
37 /// Abstract reader-writer interface classes
38 ///
39 /// Slightly adapted, however, to build std::streambuf on top of them.
40 
41 
42 #include <corelib/ncbistl.hpp>
43 #include <stddef.h>
44 
45 /** @addtogroup Stream
46  *
47  * @{
48  */
49 
50 
52 
53 
54 /// Result codes for I/O operations.
55 /// @note
56 /// Exceptions (if any) thrown by IReader/IWriter interfaces should be
57 /// treated as unrecoverable errors (eRW_Error).
58 /// @sa
59 /// IReader, IWriter, IReaderWriter
60 enum ERW_Result {
61  eRW_NotImplemented = -1, ///< Action / information is not available
62  eRW_Success = 0, ///< Everything is okay, I/O completed
63  eRW_Timeout, ///< Timeout expired, try again later
64  eRW_Error, ///< Unrecoverable error, no retry possible
65  eRW_Eof ///< End of data, should be considered permanent
66 };
67 
69 
70 
71 /// A very basic data-read interface.
72 /// @sa
73 /// IWriter, IReaderWriter, CRStream
75 {
76 public:
77  /// Read as many as "count" bytes into a buffer pointed to by the "buf"
78  /// argument. Always store the number of bytes actually read (0 if read
79  /// none) via the pointer "bytes_read", if provided non-NULL.
80  /// Return non-eRW_Success code if EOF / error condition has been
81  /// encountered during the operation (some data may have been read,
82  /// nevertheless, and reflected in "*bytes_read").
83  /// Special case: if "count" is passed as 0, then the value of "buf" must
84  /// be ignored, and no change should be made to the state of the input
85  /// device (but may return non-eRW_Success to indicate that the input
86  /// device has already been in an error condition).
87  /// @note
88  /// Apparently, may not return eRW_Success if hasn't been able to read
89  /// "count" bytes as requested, and "bytes_read" was provided as NULL.
90  /// @note
91  /// When returning "*bytes_read" as zero for a non-zero "count"
92  /// requested, the return status should not indicate eRW_Success.
93  /// @warning
94  /// "*bytes_read" may never be returned greater than "count".
95  /// @attention
96  /// It is implementation-dependent whether the call blocks until the
97  /// entire buffer is read or the call returns when at least some data
98  /// are available. In general, it is advised that this call is made
99  /// within a loop that checks for EOF condition and proceeds with the
100  /// reading until the required amount of data has been retrieved.
101  virtual ERW_Result Read(void* buf,
102  size_t count,
103  size_t* bytes_read = 0) = 0;
104 
105  /// Via parameter "count" (which is guaranteed to be supplied non-NULL)
106  /// return the number of bytes that are ready to be read from the input
107  /// device without blocking.
108  /// Return eRW_Success if the number of pending bytes has been stored at
109  /// the location pointed to by "count".
110  /// Return eRW_NotImplemented if the number cannot be determined.
111  /// Otherwise, return other eRW_... condition to reflect the problem
112  /// ("*count" does not need to be updated in the case of non-eRW_Success).
113  /// Note that if reporting 0 bytes ready, the method may return either
114  /// both eRW_Success and zero "*count", or return eRW_NotImplemented alone.
115  virtual ERW_Result PendingCount(size_t* count) = 0;
116 
117  /// This method gets called by RStream buffer destructor to return buffered
118  /// yet still unread (from the stream) portion of data back to the device.
119  /// It's semantically equivalent to CStreamUtils::Pushback() with the only
120  /// difference that IReader can only assume the ownership of "buf" when
121  /// "del_ptr" is passed non-NULL.
122  /// Return eRW_Success when data have been successfully pushed back and the
123  /// ownership of the pointers has been assumed as described above.
124  /// Any other error code results in pointers remained and handled within
125  /// the stream buffer being deleted, with an error message suppressed for
126  /// eRW_NotImplemented (default implementation).
127  /// @sa
128  /// CStreamUtils::Pushback
129  virtual ERW_Result Pushback(const void* buf, size_t count,
130  void* del_ptr = 0);
131 
132  virtual ~IReader();
133 };
134 
135 
136 /// A very basic data-write interface.
137 /// @sa
138 /// IReader, IReaderWriter, CWStream
140 {
141 public:
142  /// Write up to "count" bytes from the buffer pointed to by the "buf"
143  /// argument onto the output device. Always store the number of bytes
144  /// actually written, or 0 if "count" has been passed as 0 ("buf" must be
145  /// ignored in this case), via the "bytes_written" pointer, if provided
146  /// non-NULL. Note that the method can return non-eRW_Success in case of
147  /// an I/O error along with indicating (some) data delivered to the output
148  /// device (and reflected in "*bytes_written").
149  /// @note
150  /// Apparently, may not return eRW_Success if hasn't been able to write
151  /// "count" bytes as requested, and "bytes_written" was passed as NULL.
152  /// @note
153  /// When returning "*bytes_written" as zero for a non-zero "count"
154  /// requested, the return status should not indicate eRW_Success.
155  /// @warning
156  /// "*bytes_written" may never be returned greater than "count".
157  /// @attention
158  /// It is implementation-dependent whether the call blocks until the
159  /// entire buffer or only some data has been written out. In general,
160  /// it is advised that this call is made within a loop that checks for
161  /// errors and proceeds with the writing until the required amount of
162  /// data has been sent.
163  virtual ERW_Result Write(const void* buf,
164  size_t count,
165  size_t* bytes_written = 0) = 0;
166 
167  /// Flush pending data (if any) down to the output device.
168  virtual ERW_Result Flush(void) = 0;
169 
170  virtual ~IWriter();
171 };
172 
173 
174 /// A very basic data-read/write interface.
175 /// @sa
176 /// IReader, IWriter, CRWStream
177 class NCBI_XNCBI_EXPORT IReaderWriter : public virtual IReader,
178  public virtual IWriter
179 {
180 public:
181  virtual ~IReaderWriter();
182 };
183 
184 
186 
187 
188 /* @} */
189 
190 #endif /* CORELIB___READER_WRITER__HPP */
A very basic data-read/write interface.
A very basic data-read interface.
A very basic data-write interface.
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
ERW_Result
Result codes for I/O operations.
const char * g_RW_ResultToString(ERW_Result res)
virtual ERW_Result Flush(void)=0
Flush pending data (if any) down to the output device.
virtual ERW_Result PendingCount(size_t *count)=0
Via parameter "count" (which is guaranteed to be supplied non-NULL) return the number of bytes that a...
virtual ERW_Result Write(const void *buf, size_t count, size_t *bytes_written=0)=0
Write up to "count" bytes from the buffer pointed to by the "buf" argument onto the output device.
virtual ERW_Result Read(void *buf, size_t count, size_t *bytes_read=0)=0
Read as many as "count" bytes into a buffer pointed to by the "buf" argument.
@ eRW_NotImplemented
Action / information is not available.
@ eRW_Eof
End of data, should be considered permanent.
@ eRW_Error
Unrecoverable error, no retry possible.
@ eRW_Timeout
Timeout expired, try again later.
@ eRW_Success
Everything is okay, I/O completed.
#define NCBI_XNCBI_EXPORT
Definition: ncbi_export.h:1283
char * buf
The NCBI C++/STL use hints.
Modified on Sat May 25 14:22:44 2024 by modify_doxy.py rev. 669887