sal/inc/rtl/byteseq.h

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