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