include/rtl/byteseq.h

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