1 // Copyright 2019 Google Inc. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 /////////////////////////////////////////////////////////////////////////////// 16 17 #ifndef TINK_RANDOM_ACCESS_STREAM_H_ 18 #define TINK_RANDOM_ACCESS_STREAM_H_ 19 20 #include "tink/util/buffer.h" 21 #include "tink/util/status.h" 22 #include "tink/util/statusor.h" 23 24 namespace crypto { 25 namespace tink { 26 27 // Abstract interface for streams that provide random access for reading, 28 // like regular files. 29 class RandomAccessStream { 30 public: 31 RandomAccessStream() = default; 32 virtual ~RandomAccessStream() = default; 33 34 // Reads up to 'count' bytes starting at 'position' and writes them 35 // to 'dest_buffer'. 'position' must be within the size of the stream, 36 // 'count' must be positive, 'dest_buffer' must be non-NULL and its 37 // allocated size must be not smaller than 'count'. 38 // 39 // Return values: 40 // OK: if exactly 'count' bytes were read and written to 'dest_buffer', 41 // or if fewer than 'count' (potentially 0) bytes were read, 42 // but the lack of bytes is not permanent, and retrying may succeed; 43 // in this case 'dest_buffer' contains the read bytes, and the size 44 // of the buffer has been changed to the number of bytes read. 45 // OUT_OF_RANGE: if the end of stream has been reached; 46 // in this case 'dest_buffer' contains the bytes read till the end 47 // of the stream (if any). This status is returned also when 48 // 'position' is larger than the current size of the stream. 49 // INVALID_ARGUMENT: if some of the arguments are not valid. 50 // other: if some other error occurred. 51 virtual crypto::tink::util::Status PRead( 52 int64_t position, 53 int count, 54 crypto::tink::util::Buffer* dest_buffer) = 0; 55 56 // Returns the size of this stream in bytes, if available. 57 // If the size is not available, returns a non-Ok status. 58 // The returned value is the "logical" size of a stream, i.e. of 59 // a sequence of bytes), stating how many bytes are there in the sequence. 60 // For a successful PRead-operation the starting position should be 61 // in the range 0..size()-1 (otherwise PRead may return a non-Ok status). 62 virtual crypto::tink::util::StatusOr<int64_t> size() = 0; 63 }; 64 65 } // namespace tink 66 } // namespace crypto 67 68 #endif // TINK_RANDOM_ACCESS_STREAM_H_ 69