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 _COM_SUN_STAR_UNO_SEQUENCE_H_ 24 #define _COM_SUN_STAR_UNO_SEQUENCE_H_ 25 26 #include "typelib/typedescription.h" 27 #include "uno/sequence2.h" 28 #include "com/sun/star/uno/Type.h" 29 #include "rtl/alloc.h" 30 31 #if ! defined EXCEPTIONS_OFF 32 #include <new> 33 #endif 34 35 36 namespace rtl 37 { 38 class ByteSequence; 39 } 40 41 namespace com 42 { 43 namespace sun 44 { 45 namespace star 46 { 47 namespace uno 48 { 49 50 /** Template C++ class representing an IDL sequence. Template argument is the 51 sequence element type. C++ Sequences are reference counted and shared, 52 so the sequence keeps a handle to its data. To keep value semantics, 53 copies are only generated if the sequence is to be modified (new handle). 54 55 @tplparam E element type of sequence 56 */ 57 template< class E > 58 class Sequence 59 { 60 /** sequence handle 61 @internal 62 */ 63 uno_Sequence * _pSequence; 64 65 public: 66 // these are here to force memory de/allocation to sal lib. 67 /** @internal */ operator new(size_t nSize)68 inline static void * SAL_CALL operator new ( size_t nSize ) 69 SAL_THROW( () ) 70 { return ::rtl_allocateMemory( nSize ); } 71 /** @internal */ operator delete(void * pMem)72 inline static void SAL_CALL operator delete ( void * pMem ) 73 SAL_THROW( () ) 74 { ::rtl_freeMemory( pMem ); } 75 /** @internal */ operator new(size_t,void * pMem)76 inline static void * SAL_CALL operator new ( size_t, void * pMem ) 77 SAL_THROW( () ) 78 { return pMem; } 79 /** @internal */ operator delete(void *,void *)80 inline static void SAL_CALL operator delete ( void *, void * ) 81 SAL_THROW( () ) 82 {} 83 84 /** Static pointer to typelib type of sequence. 85 Don't use directly, call getCppuType(). 86 @internal 87 */ 88 static typelib_TypeDescriptionReference * s_pType; 89 90 /** typedefs the element type of the sequence 91 */ 92 typedef E ElementType; 93 94 /** Default constructor: Creates an empty sequence. 95 */ 96 inline Sequence() SAL_THROW( () ); 97 98 /** Copy constructor: Creates a copy of given sequence. 99 100 @param rSeq another sequence of same type 101 */ 102 inline Sequence( const Sequence< E > & rSeq ) SAL_THROW( () ); 103 104 /** Constructor: Takes over ownership of given sequence. 105 106 @param pSequence a sequence 107 @param dummy SAL_NO_ACQUIRE to force obvious distinction to other 108 constructors 109 */ 110 inline Sequence( uno_Sequence * pSequence, __sal_NoAcquire ) 111 SAL_THROW( () ); 112 113 /** Constructor: Creates a copy of given elements. 114 115 @param pElement an array of elements 116 @param len length of array 117 */ 118 inline Sequence( const E * pElements, sal_Int32 len ); 119 120 /** Constructor: Creates a default constructed sequence of given length. 121 122 @param len initial sequence length 123 */ 124 inline explicit Sequence( sal_Int32 len ); 125 126 /** Destructor: Releases sequence handle. Last handle will destruct 127 elements and free memory. 128 */ 129 inline ~Sequence() SAL_THROW( () ); 130 131 /** Assignment operator: Acquires given sequence handle and releases 132 previously set handle. 133 134 @param rSeq another sequence of same type 135 @return this sequence 136 */ 137 inline Sequence< E > & SAL_CALL operator = ( const Sequence< E > & rSeq ) 138 SAL_THROW( () ); 139 140 /** Gets length of the sequence. 141 142 @return length of sequence 143 */ getLength() const144 inline sal_Int32 SAL_CALL getLength() const SAL_THROW( () ) 145 { return _pSequence->nElements; } 146 147 /** Tests whether the sequence has elements, i.e. elements count is 148 greater than zero. 149 150 @return true, if elements count is greater than zero 151 */ hasElements() const152 inline sal_Bool SAL_CALL hasElements() const SAL_THROW( () ) 153 { return (_pSequence->nElements > 0); } 154 155 /** Gets a pointer to elements array for reading. 156 If the sequence has a length of 0, then the returned pointer is 157 undefined. 158 159 @return pointer to elements array 160 */ getConstArray() const161 inline const E * SAL_CALL getConstArray() const SAL_THROW( () ) 162 { return reinterpret_cast< const E * >( _pSequence->elements ); } 163 164 /** Gets a pointer to elements array for reading and writing. 165 In general if the sequence has a handle acquired by other sequences 166 (reference count > 1), then a new sequence is created copy constructing 167 all elements to keep value semantics! 168 If the sequence has a length of 0, then the returned pointer is 169 undefined. 170 171 @return pointer to elements array 172 */ 173 inline E * SAL_CALL getArray(); 174 175 /** Non-const index operator: Obtains a reference to element indexed at 176 given position. 177 The implementation does not check for array bounds! 178 In general if the sequence has a handle acquired by other sequences 179 (reference count > 1), then a new sequence is created copy constructing 180 all elements to keep value semantics! 181 182 @param nIndex index 183 @return non-const C++ reference to element 184 */ 185 inline E & SAL_CALL operator [] ( sal_Int32 nIndex ); 186 187 /** Const index operator: Obtains a reference to element indexed at 188 given position. The implementation does not check for array bounds! 189 190 @param nIndex index 191 @return const C++ reference to element 192 */ 193 inline const E & SAL_CALL operator [] ( sal_Int32 nIndex ) const 194 SAL_THROW( () ); 195 196 /** Equality operator: Compares two sequences. 197 198 @param rSeq another sequence of same type (right side) 199 @return true if both sequences are equal, false otherwise 200 */ 201 inline sal_Bool SAL_CALL operator == ( const Sequence< E > & rSeq ) const 202 SAL_THROW( () ); 203 204 /** Unequality operator: Compares two sequences. 205 206 @param rSeq another sequence of same type (right side) 207 @return false if both sequences are equal, true otherwise 208 */ 209 inline sal_Bool SAL_CALL operator != ( const Sequence< E > & rSeq ) const 210 SAL_THROW( () ); 211 212 /** Reallocates sequence to new length. 213 If the new length is smaller than the former, then upper elements will 214 be destructed (and their memory freed). If the new length is greater 215 than the former, then upper (new) elements are default constructed. 216 If the sequence has a handle acquired by other sequences 217 (reference count > 1), then the remaining elements are copy constructed 218 to a new sequence handle to keep value semantics! 219 220 @param nSize new size of sequence 221 */ 222 inline void SAL_CALL realloc( sal_Int32 nSize ); 223 224 /** Provides UNacquired sequence handle. 225 226 @return UNacquired sequence handle 227 */ get() const228 inline uno_Sequence * SAL_CALL get() const SAL_THROW( () ) 229 { return _pSequence; } 230 }; 231 232 /** Creates a UNO byte sequence from a SAL byte sequence. 233 234 @param rByteSequence a byte sequence 235 @return a UNO byte sequence 236 */ 237 inline ::com::sun::star::uno::Sequence< sal_Int8 > SAL_CALL toUnoSequence( 238 const ::rtl::ByteSequence & rByteSequence ) SAL_THROW( () ); 239 240 } 241 } 242 } 243 } 244 245 /** Gets the meta type of IDL sequence. 246 247 There are cases (involving templates) where uses of getCppuType are known to 248 not compile. Use cppu::UnoType or cppu::getTypeFavourUnsigned instead. 249 250 @tplparam E element type of sequence 251 @param dummy typed pointer for function signature 252 @return type of IDL sequence 253 */ 254 template< class E > 255 inline const ::com::sun::star::uno::Type & 256 SAL_CALL getCppuType( const ::com::sun::star::uno::Sequence< E > * ) 257 SAL_THROW( () ); 258 259 /** Gets the meta type of IDL sequence. 260 This function has been introduced, because one cannot get the (templated) 261 cppu type out of C++ array types. Array types have special 262 getCppuArrayTypeN() functions. 263 264 @attention 265 the given element type must be the same as the template argument type! 266 @tplparam E element type of sequence 267 @param rElementType element type of sequence 268 @return type of IDL sequence 269 */ 270 template< class E > 271 inline const ::com::sun::star::uno::Type & 272 SAL_CALL getCppuSequenceType( const ::com::sun::star::uno::Type & rElementType ) 273 SAL_THROW( () ); 274 275 /** Gets the meta type of IDL sequence< char >. 276 This function has been introduced due to ambiguities with unsigned short. 277 278 @param dummy typed pointer for function signature 279 @return type of IDL sequence< char > 280 */ 281 inline const ::com::sun::star::uno::Type & 282 SAL_CALL getCharSequenceCppuType() SAL_THROW( () ); 283 284 #endif 285