1 /*============================================================================== 2 * 3 * PUBLIC DOMAIN NOTICE 4 * National Center for Biotechnology Information 5 * 6 * This software/database is a "United States Government Work" under the 7 * terms of the United States Copyright Act. It was written as part of 8 * the author's official duties as a United States Government employee and 9 * thus cannot be copyrighted. This software/database is freely available 10 * to the public for use. The National Library of Medicine and the U.S. 11 * Government have not placed any restriction on its use or reproduction. 12 * 13 * Although all reasonable efforts have been taken to ensure the accuracy 14 * and reliability of the software and data, the NLM and the U.S. 15 * Government do not and cannot warrant the performance or results that 16 * may be obtained by using this software or data. The NLM and the U.S. 17 * Government disclaim all warranties, express or implied, including 18 * warranties of performance, merchantability or fitness for any particular 19 * purpose. 20 * 21 * Please cite the author in any work or product based on this material. 22 * 23 * Author: Kurt Rodarmer 24 * 25 * =========================================================================== 26 * 27 */ 28 29 #pragma once 30 31 #include <ncbi/secure/busy.hpp> 32 #include <ncbi/secure/except.hpp> 33 34 35 /** 36 * @file ncbi/secure/payload.hpp 37 * @brief a payload abstraction 38 */ 39 40 namespace ncbi 41 { 42 43 /*=====================================================* 44 * Payload * 45 *=====================================================*/ 46 47 /** 48 * @class Payload 49 * @brief contains binary data in a managed package 50 */ 51 class Payload 52 { 53 public: 54 55 /** 56 * data 57 * @overload non-const version 58 * @return non-const pointer to buffer 59 */ 60 unsigned char * data (); 61 62 /** 63 * data 64 * @overload const version 65 * @return const pointer to buffer 66 */ 67 const unsigned char * data () const; 68 69 /** 70 * size 71 * @return size of data in bytes 72 */ 73 size_t size () const; 74 75 /** 76 * capacity 77 * @return size of buffer in bytes 78 */ 79 size_t capacity () const; 80 81 /** 82 * setSize 83 * @brief record actual size 84 * @param amt actual size in bytes 85 */ 86 void setSize ( size_t amt ); 87 88 /** 89 * increaseCapacity 90 * @brief increase buffer size 91 * @param amt amount of size increment 92 */ 93 void increaseCapacity ( size_t amt = 256 ); 94 95 /** 96 * wipe 97 * @brief overwrites buffer space 98 */ 99 void wipe (); 100 101 /** 102 * reinitialize 103 * @brief deletes any buffer space and resets to initial state 104 * @param wipe if true, overwrite buffer space before freeing 105 */ 106 void reinitialize ( bool wipe = true ); 107 108 /** 109 * operator = 110 * @brief copy operator 111 * @param payload source from which contents are STOLEN 112 * @return C++ self-reference for use in idiomatic C++ expressions 113 * 114 * Source object will be empty afterward. 115 */ 116 Payload & operator = ( const Payload & payload ); 117 118 /** 119 * operator = 120 * @brief move operator 121 * @param payload source from which contents are STOLEN 122 * @return C++ self-reference for use in idiomatic C++ expressions 123 * 124 * Source object will be empty afterward. 125 */ 126 Payload & operator = ( const Payload && payload ); 127 128 /** 129 * Payload 130 * @overload copy constructor 131 * @param payload source from which contents are STOLEN 132 * 133 * Source object will be empty afterward 134 */ 135 Payload ( const Payload & payload ); 136 137 /** 138 * Payload 139 * @overload move constructor 140 * @param payload source from which contents are STOLEN 141 * 142 * Source object will be empty afterward 143 */ 144 Payload ( const Payload && payload ); 145 146 /** 147 * Payload 148 * @overload create zero size payload with initial buffer capacity 149 * @param initial_capacity value in bytes of initial buffer size 150 */ 151 explicit Payload ( size_t initial_capacity ); 152 153 /** 154 * Payload 155 * @overload default constructor 156 */ 157 Payload () noexcept; 158 159 /** 160 * ~Payload 161 * @brief delete buffer if present 162 */ 163 ~ Payload () noexcept; 164 165 private: 166 167 BusyLock busy; 168 mutable unsigned char * buff; 169 mutable size_t sz, cap; 170 }; 171 172 173 /*=====================================================* 174 * EXCEPTIONS * 175 *=====================================================*/ 176 177 } 178