| /************************************************************** |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| #ifndef _RTL_BYTESEQ_H_ |
| #define _RTL_BYTESEQ_H_ |
| |
| #include <sal/types.h> |
| #include <rtl/alloc.h> |
| |
| #ifdef __cplusplus |
| extern "C" |
| { |
| #endif |
| |
| /** Assures that the reference count of the given byte sequence is one. Otherwise a new copy |
| of the sequence is created with a reference count of one. |
| |
| @param ppSequence sequence |
| */ |
| void SAL_CALL rtl_byte_sequence_reference2One( |
| sal_Sequence ** ppSequence ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Reallocates length of byte sequence. |
| |
| @param ppSequence sequence |
| @param nSize new size of sequence |
| */ |
| void SAL_CALL rtl_byte_sequence_realloc( |
| sal_Sequence ** ppSequence, sal_Int32 nSize ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Acquires the byte sequence |
| |
| @param pSequence sequence, that is to be acquired |
| */ |
| void SAL_CALL rtl_byte_sequence_acquire( |
| sal_Sequence *pSequence ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Releases the byte sequence. If the refcount drops to zero, the sequence is freed. |
| |
| @param pSequence sequence, that is to be released; invalid after call |
| */ |
| void SAL_CALL rtl_byte_sequence_release( |
| sal_Sequence *pSequence ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Constructs a bytes sequence with length nLength. All bytes are set to zero. |
| |
| @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released; |
| after the call, *ppSequence contains the newly constructed sequence |
| @param nLength length of new sequence |
| */ |
| void SAL_CALL rtl_byte_sequence_construct( |
| sal_Sequence **ppSequence , sal_Int32 nLength ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Constructs a bytes sequence with length nLength. The data is not initialized. |
| |
| @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released; |
| after the call, *ppSequence contains the newly constructed sequence |
| @param nLength length of new sequence |
| */ |
| void SAL_CALL rtl_byte_sequence_constructNoDefault( |
| sal_Sequence **ppSequence , sal_Int32 nLength ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Constructs a byte sequence with length nLength and copies nLength bytes from pData. |
| |
| @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released; |
| after the call, *ppSequence contains the newly constructed sequence |
| @param pData initial data |
| @param nLength length of new sequence |
| */ |
| void SAL_CALL rtl_byte_sequence_constructFromArray( |
| sal_Sequence **ppSequence, const sal_Int8 *pData , sal_Int32 nLength ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Assigns the byte sequence pSequence to *ppSequence. |
| |
| @param ppSequence inout sequence; on entry *ppSequence may be null, otherwise it is released; |
| after the call, *ppSequence references pSequence |
| @param pSequence the source sequence |
| */ |
| void SAL_CALL rtl_byte_sequence_assign( |
| sal_Sequence **ppSequence , sal_Sequence *pSequence ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Compares two byte sequences. |
| |
| @return true, if the data within the sequences are identical; false otherwise |
| */ |
| sal_Bool SAL_CALL rtl_byte_sequence_equals( |
| sal_Sequence *pSequence1 , sal_Sequence *pSequence2 ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Returns the data array pointer of the sequence. |
| |
| @return read-pointer to the data array of the sequence. If rtl_byte_sequence_reference2One() |
| has been called before, the pointer may be casted to a non const pointer and |
| the sequence may be modified |
| */ |
| const sal_Int8 *SAL_CALL rtl_byte_sequence_getConstArray( |
| sal_Sequence *pSequence ) |
| SAL_THROW_EXTERN_C(); |
| |
| /** Returns the length of the sequence |
| |
| @param pSequence sequence handle |
| @return length of the sequence |
| */ |
| sal_Int32 SAL_CALL rtl_byte_sequence_getLength( |
| sal_Sequence *pSequence ) |
| SAL_THROW_EXTERN_C(); |
| |
| #ifdef __cplusplus |
| } |
| namespace rtl |
| { |
| |
| enum __ByteSequence_NoDefault |
| { |
| /** This enum value can be used to create a bytesequence with uninitalized data |
| */ |
| BYTESEQ_NODEFAULT = 0xcafe |
| }; |
| |
| enum __ByteSequence_NoAcquire |
| { |
| /** This enum value can be used to create a bytesequence from a C-Handle without |
| acquiring the handle. |
| */ |
| BYTESEQ_NOACQUIRE = 0xcafebabe |
| }; |
| |
| /** C++ class representing a SAL byte sequence. |
| C++ Sequences are reference counted and shared, so the sequence keeps a handle to its data. |
| To keep value semantics, copies are only generated if the sequence is to be modified |
| (new handle). |
| */ |
| class ByteSequence |
| { |
| /** sequence handle |
| @internal |
| */ |
| sal_Sequence * _pSequence; |
| |
| public: |
| // these are here to force memory de/allocation to sal lib. |
| /** @internal */ |
| inline static void * SAL_CALL operator new ( size_t nSize ) SAL_THROW( () ) |
| { return ::rtl_allocateMemory( nSize ); } |
| /** @internal */ |
| inline static void SAL_CALL operator delete ( void * pMem ) SAL_THROW( () ) |
| { ::rtl_freeMemory( pMem ); } |
| /** @internal */ |
| inline static void * SAL_CALL operator new ( size_t, void * pMem ) SAL_THROW( () ) |
| { return pMem; } |
| /** @internal */ |
| inline static void SAL_CALL operator delete ( void *, void * ) SAL_THROW( () ) |
| {} |
| |
| /** Default constructor: Creates an empty sequence. |
| */ |
| inline ByteSequence() SAL_THROW( () ); |
| /** Copy constructor: Creates a copy of given sequence. |
| |
| @param rSeq another byte sequence |
| */ |
| inline ByteSequence( const ByteSequence & rSeq ) SAL_THROW( () ); |
| /** Copy constructor Creates a copy from the C-Handle. |
| |
| @param pSequence another byte sequence handle |
| */ |
| inline ByteSequence( sal_Sequence *pSequence ) SAL_THROW( () ); |
| /** Constructor: Creates a copy of given data bytes. |
| |
| @param pElements an array of bytes |
| @param len number of bytes |
| */ |
| inline ByteSequence( const sal_Int8 * pElements, sal_Int32 len ); |
| /** Constructor: Creates sequence of given length and initializes all bytes to 0. |
| |
| @param len initial sequence length |
| */ |
| inline ByteSequence( sal_Int32 len ); |
| /** Constructor: Creates sequence of given length and does NOT initialize data. |
| Use this ctor for performance optimization only. |
| |
| @param len initial sequence length |
| @param nodefault dummy parameter forcing explicit BYTESEQ_NODEFAULT |
| */ |
| inline ByteSequence( sal_Int32 len , enum __ByteSequence_NoDefault nodefault ); |
| /** Constructor: |
| Creates a sequence from a C-Handle without acquiring the handle, thus taking |
| over owenership. Eitherway the handle is release by the destructor. |
| This ctor is useful, when working with a c-interface (it safes a pair of |
| acquire and release call and is thus a performance optimization only). |
| |
| @param pSequence sequence handle to be taken over |
| @param noacquire dummy parameter forcing explicit BYTESEQ_NOACQUIRE |
| */ |
| inline ByteSequence( sal_Sequence *pSequence , enum __ByteSequence_NoAcquire noacquire ) SAL_THROW( () ); |
| /** Destructor: Releases sequence handle. Last handle will free memory. |
| */ |
| inline ~ByteSequence() SAL_THROW( () ); |
| |
| /** Assignment operator: Acquires given sequence handle and releases a previously set handle. |
| |
| @param rSeq another byte sequence |
| @return this sequence |
| */ |
| inline ByteSequence & SAL_CALL operator = ( const ByteSequence & rSeq ) SAL_THROW( () ); |
| |
| /** Gets the length of sequence. |
| |
| @return length of sequence |
| */ |
| inline sal_Int32 SAL_CALL getLength() const SAL_THROW( () ) |
| { return _pSequence->nElements; } |
| |
| /** Gets a pointer to byte array for READING. If the sequence has a length of 0, then the |
| returned pointer is undefined. |
| |
| @return pointer to byte array |
| */ |
| inline const sal_Int8 * SAL_CALL getConstArray() const SAL_THROW( () ) |
| { return (const sal_Int8 *)_pSequence->elements; } |
| /** Gets a pointer to elements array for READING AND WRITING. In general if the sequence |
| has a handle acquired by other sequences (reference count > 1), then a new sequence is |
| created copying all bytes to keep value semantics! |
| If the sequence has a length of 0, then the returned pointer is undefined. |
| |
| @return pointer to elements array |
| */ |
| inline sal_Int8 * SAL_CALL getArray(); |
| |
| /** Non-const index operator: |
| Obtains a reference to byte indexed at given position. |
| In general if the sequence has a handle acquired by other |
| sequences (reference count > 1), then a new sequence is created |
| copying all bytes to keep value semantics! |
| |
| @attention |
| The implementation does NOT check for array bounds! |
| |
| @param nIndex index |
| @return non-const C++ reference to element at index nIndex |
| */ |
| inline sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex ); |
| |
| /** Const index operator: Obtains a reference to byte indexed at given position. |
| The implementation does NOT check for array bounds! |
| |
| @param nIndex index |
| @return const C++ reference to byte at element of indenx nIndex |
| */ |
| inline const sal_Int8 & SAL_CALL operator [] ( sal_Int32 nIndex ) const SAL_THROW( () ) |
| { return getConstArray()[ nIndex ]; } |
| |
| /** Equality operator: Compares two sequences. |
| |
| @param rSeq another byte sequence (right side) |
| @return true if both sequences are equal, false otherwise |
| */ |
| inline sal_Bool SAL_CALL operator == ( const ByteSequence & rSeq ) const SAL_THROW( () ); |
| /** Unequality operator: Compares two sequences. |
| |
| @param rSeq another byte sequence (right side) |
| @return false if both sequences are equal, true otherwise |
| */ |
| inline sal_Bool SAL_CALL operator != ( const ByteSequence & rSeq ) const SAL_THROW( () ); |
| |
| /** Reallocates sequence to new length. If the sequence has a handle acquired by other sequences |
| (reference count > 1), then the remaining elements are copied to a new sequence handle to |
| keep value semantics! |
| |
| @param nSize new size of sequence |
| */ |
| inline void SAL_CALL realloc( sal_Int32 nSize ); |
| |
| /** Returns the UNnacquired C handle of the sequence |
| |
| @return UNacquired handle of the sequence |
| */ |
| inline sal_Sequence * SAL_CALL getHandle() const SAL_THROW( () ) |
| { return _pSequence; } |
| /** Returns the UNnacquired C handle of the sequence (for compatibility reasons) |
| |
| @return UNacquired handle of the sequence |
| */ |
| inline sal_Sequence * SAL_CALL get() const SAL_THROW( () ) |
| { return _pSequence; } |
| }; |
| |
| } |
| #endif |
| #endif |