xref: /aoo41x/main/sal/inc/rtl/byteseq.h (revision 9eab2a37)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 #ifndef _RTL_BYTESEQ_H_
24 #define _RTL_BYTESEQ_H_
25 
26 #include <sal/types.h>
27 #include <rtl/alloc.h>
28 
29 #ifdef __cplusplus
30 extern "C"
31 {
32 #endif
33 
34 /** Assures that the reference count of the given byte sequence is one. Otherwise a new copy
35     of the sequence is created with a reference count of one.
36 
37 	@param ppSequence sequence
38 */
39 void SAL_CALL rtl_byte_sequence_reference2One(
40 	sal_Sequence ** ppSequence )
41     SAL_THROW_EXTERN_C();
42 
43 /** Reallocates length of byte sequence.
44 
45 	@param ppSequence sequence
46 	@param nSize new size of sequence
47 */
48 void SAL_CALL rtl_byte_sequence_realloc(
49 	sal_Sequence ** ppSequence, sal_Int32 nSize )
50     SAL_THROW_EXTERN_C();
51 
52 /** Acquires the byte sequence
53 
54 	@param pSequence sequence, that is to be acquired
55 */
56 void SAL_CALL rtl_byte_sequence_acquire(
57     sal_Sequence *pSequence )
58     SAL_THROW_EXTERN_C();
59 
60 /** Releases the byte sequence. If the refcount drops to zero, the sequence is freed.
61 
62 	@param pSequence sequence, that is to be released; invalid after call
63 */
64 void SAL_CALL rtl_byte_sequence_release(
65     sal_Sequence *pSequence )
66     SAL_THROW_EXTERN_C();
67 
68 /** Constructs a bytes sequence with length nLength. All bytes are set to zero.
69 
70 	@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
71                       after the call, *ppSequence contains the newly constructed sequence
72     @param nLength    length of new sequence
73 */
74 void SAL_CALL rtl_byte_sequence_construct(
75     sal_Sequence **ppSequence , sal_Int32 nLength )
76     SAL_THROW_EXTERN_C();
77 
78 /** Constructs a bytes sequence with length nLength. The data is not initialized.
79 
80 	@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
81                       after the call, *ppSequence contains the newly constructed sequence
82     @param nLength    length of new sequence
83 */
84 void SAL_CALL rtl_byte_sequence_constructNoDefault(
85 	sal_Sequence **ppSequence , sal_Int32 nLength )
86     SAL_THROW_EXTERN_C();
87 
88 /** Constructs a byte sequence with length nLength and copies nLength bytes from pData.
89 
90 	@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
91                       after the call, *ppSequence contains the newly constructed sequence
92     @param pData      initial data
93     @param nLength    length of new sequence
94 */
95 void SAL_CALL rtl_byte_sequence_constructFromArray(
96 	sal_Sequence **ppSequence, const sal_Int8 *pData , sal_Int32 nLength )
97     SAL_THROW_EXTERN_C();
98 
99 /** Assigns the byte sequence pSequence to *ppSequence.
100 
101 	@param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released;
102                       after the call, *ppSequence references pSequence
103 	@param pSequence  the source sequence
104 */
105 void SAL_CALL rtl_byte_sequence_assign(
106     sal_Sequence **ppSequence , sal_Sequence *pSequence )
107     SAL_THROW_EXTERN_C();
108 
109 /** Compares two byte sequences.
110 
111 	@return true, if the data within the sequences are identical; false otherwise
112 */
113 sal_Bool SAL_CALL rtl_byte_sequence_equals(
114     sal_Sequence *pSequence1 , sal_Sequence *pSequence2 )
115     SAL_THROW_EXTERN_C();
116 
117 /** Returns the data array pointer of the sequence.
118 
119 	@return read-pointer to the data array of the sequence. If rtl_byte_sequence_reference2One()
120 	        has been called before, the pointer may be casted to a non const pointer and
121 	        the sequence may be modified
122 */
123 const sal_Int8 *SAL_CALL rtl_byte_sequence_getConstArray(
124     sal_Sequence *pSequence )
125     SAL_THROW_EXTERN_C();
126 
127 /** Returns the length of the sequence
128 
129     @param pSequence sequence handle
130     @return length of the sequence
131 */
132 sal_Int32 SAL_CALL rtl_byte_sequence_getLength(
133     sal_Sequence *pSequence )
134     SAL_THROW_EXTERN_C();
135 
136 #ifdef __cplusplus
137 }
138 namespace rtl
139 {
140 
141 enum __ByteSequence_NoDefault
142 {
143 	/** This enum value can be used to create a bytesequence with uninitalized data
144 	*/
145 	BYTESEQ_NODEFAULT = 0xcafe
146 };
147 
148 enum __ByteSequence_NoAcquire
149 {
150 	/** This enum value can be used to create a bytesequence from a C-Handle without
151         acquiring the handle.
152 	*/
153 	BYTESEQ_NOACQUIRE = 0xcafebabe
154 };
155 
156 /** C++ class representing a SAL byte sequence.
157 	C++ Sequences are reference counted and shared, so the sequence keeps a handle to its data.
158 	To keep value semantics, copies are only generated if the sequence is to be modified
159     (new handle).
160 */
161 class ByteSequence
162 {
163 	/** sequence handle
164         @internal
165 	*/
166 	sal_Sequence * _pSequence;
167 
168 public:
169 	// these are here to force memory de/allocation to sal lib.
170     /** @internal */
operator new(size_t nSize)171 	inline static void * SAL_CALL operator new ( size_t nSize ) SAL_THROW( () )
172 		{ return ::rtl_allocateMemory( nSize ); }
173     /** @internal */
operator delete(void * pMem)174 	inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW( () )
175 		{ ::rtl_freeMemory( pMem ); }
176     /** @internal */
operator new(size_t,void * pMem)177 	inline static void * SAL_CALL operator new ( size_t, void * pMem ) SAL_THROW( () )
178 		{ return pMem; }
179     /** @internal */
operator delete(void *,void *)180 	inline static void SAL_CALL operator delete ( void *, void * ) SAL_THROW( () )
181 		{}
182 
183 	/** Default constructor: Creates an empty sequence.
184 	*/
185 	inline ByteSequence() SAL_THROW( () );
186 	/** Copy constructor: Creates a copy of given sequence.
187 
188 		@param rSeq another byte sequence
189 	*/
190 	inline ByteSequence( const ByteSequence & rSeq ) SAL_THROW( () );
191 	/** Copy constructor Creates a copy from the C-Handle.
192 
193 		@param pSequence another byte sequence handle
194 	*/
195 	inline ByteSequence( sal_Sequence *pSequence ) SAL_THROW( () );
196 	/** Constructor: Creates a copy of given data bytes.
197 
198 		@param pElements an array of bytes
199 		@param len number of bytes
200 	*/
201 	inline ByteSequence( const sal_Int8 * pElements, sal_Int32 len );
202 	/** Constructor: Creates sequence of given length and initializes all bytes to 0.
203 
204 		@param len initial sequence length
205 	*/
206 	inline ByteSequence( sal_Int32 len );
207 	/** Constructor: Creates sequence of given length and does NOT initialize data.
208                      Use this ctor for performance optimization only.
209 
210 		@param len initial sequence length
211 		@param nodefault dummy parameter forcing explicit BYTESEQ_NODEFAULT
212 	*/
213 	inline ByteSequence( sal_Int32 len , enum __ByteSequence_NoDefault nodefault );
214 	/** Constructor:
215         Creates a sequence from a C-Handle without acquiring the handle, thus taking
216         over owenership. Eitherway the handle is release by the destructor.
217         This ctor is useful, when working with a c-interface (it safes a pair of
218         acquire and release call and is thus a performance optimization only).
219 
220         @param pSequence sequence handle to be taken over
221         @param noacquire dummy parameter forcing explicit BYTESEQ_NOACQUIRE
222 	*/
223 	inline ByteSequence( sal_Sequence *pSequence , enum __ByteSequence_NoAcquire noacquire ) SAL_THROW( () );
224 	/** Destructor: Releases sequence handle. Last handle will free memory.
225 	*/
226 	inline ~ByteSequence() SAL_THROW( () );
227 
228 	/** Assignment operator: Acquires given sequence handle and releases a previously set handle.
229 
230 		@param rSeq another byte sequence
231 		@return this sequence
232 	*/
233 	inline ByteSequence & SAL_CALL operator = ( const ByteSequence & rSeq ) SAL_THROW( () );
234 
235 	/** Gets the length of sequence.
236 
237 		@return length of sequence
238 	*/
getLength() const239     inline sal_Int32 SAL_CALL getLength() const SAL_THROW( () )
240 		{ return _pSequence->nElements; }
241 
242 	/** Gets a pointer to byte array for READING. If the sequence has a length of 0, then the
243         returned pointer is undefined.
244 
245 		@return pointer to byte array
246 	*/
getConstArray() const247     inline const sal_Int8 * SAL_CALL getConstArray() const SAL_THROW( () )
248 		{ return (const sal_Int8 *)_pSequence->elements; }
249 	/** Gets a pointer to elements array for READING AND WRITING. In general if the sequence
250         has a handle acquired by other sequences (reference count > 1), then a new sequence is
251         created copying all bytes to keep value semantics!
252 		If the sequence has a length of 0, then the returned pointer is undefined.
253 
254 		@return pointer to elements array
255 	*/
256     inline sal_Int8 * SAL_CALL getArray();
257 
258 	/** Non-const index operator:
259         Obtains a reference to byte indexed at given position.
260         In general if the sequence has a handle acquired by other
261         sequences (reference count > 1), then a new sequence is created
262         copying all bytes to keep value semantics!
263 
264         @attention
265         The implementation does NOT check for array bounds!
266 
267 		@param nIndex index
268 		@return non-const C++ reference to element at index nIndex
269 	*/
270 	inline sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex );
271 
272 	/** Const index operator: Obtains a reference to byte indexed at given position.
273                               The implementation does NOT check for array bounds!
274 
275 		@param nIndex index
276 		@return const C++ reference to byte at element of indenx nIndex
277 	*/
operator [](sal_Int32 nIndex) const278 	inline const sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex ) const SAL_THROW( () )
279 		{ return getConstArray()[ nIndex ]; }
280 
281 	/** Equality operator: Compares two sequences.
282 
283 		@param rSeq another byte sequence (right side)
284 		@return true if both sequences are equal, false otherwise
285 	*/
286 	inline sal_Bool SAL_CALL operator == ( const ByteSequence & rSeq ) const SAL_THROW( () );
287 	/** Unequality operator: Compares two sequences.
288 
289 		@param rSeq another byte sequence (right side)
290 		@return false if both sequences are equal, true otherwise
291 	*/
292 	inline sal_Bool SAL_CALL operator != ( const ByteSequence & rSeq ) const SAL_THROW( () );
293 
294 	/** Reallocates sequence to new length. If the sequence has a handle acquired by other sequences
295 		(reference count > 1), then the remaining elements are copied to a new sequence handle to
296         keep value semantics!
297 
298 		@param nSize new size of sequence
299 	*/
300 	inline void SAL_CALL realloc( sal_Int32 nSize );
301 
302 	/** Returns the UNnacquired C handle of the sequence
303 
304         @return UNacquired handle of the sequence
305     */
getHandle() const306 	inline sal_Sequence * SAL_CALL getHandle() const SAL_THROW( () )
307 		{ return _pSequence; }
308 	/** Returns the UNnacquired C handle of the sequence (for compatibility reasons)
309 
310         @return UNacquired handle of the sequence
311     */
get() const312 	inline sal_Sequence * SAL_CALL get() const SAL_THROW( () )
313 		{ return _pSequence; }
314 };
315 
316 }
317 #endif
318 #endif
319