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