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