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 uninitialized 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