/*
* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  
*
*/


#ifndef CATALOGS_CLIENTSERVER_ALLOC_UTILS_H
#define CATALOGS_CLIENTSERVER_ALLOC_UTILS_H

#include <badesca.h>

/**
 * Function that allocates a descriptor of given expected length. If
 * the given length is less than minimum length acceptable when using
 * return message allocation then this minimum allocation length is
 * used.
 * 
 * @param aExpectedLength Expected length of return message.
 * @param aAllocatedBuf Reference to a pointer which is used to
 *                      return the allocated descriptor.
 * @return TInt KErrNone on success.
 */
TInt AllocReturnBuf( TInt aExpectedLength, HBufC8*& aAllocatedBuf );

/**
 * Function that allocates a descriptor of given expected length. If
 * the given length is less than minimum length acceptable when using
 * return message allocation then this minimum allocation length is
 * used.
 * 
 * @param aExpectedLength Expected length of return message.
 * @param aAllocatedBuf Reference to a pointer which is used to
 *                      return the allocated descriptor.
 * @return TInt KErrNone on success.
 */
TInt AllocReturnBuf( TInt aExpectedLength, HBufC16*& aAllocatedBuf );
                         


/**
 * Retrieves realloc-information from the given descriptor and
 * reallocates the descriptor according to it. Also makes the
 * descriptor empty. Realloc-information is expected to be sent from
 * the server-side to inform of a too small return buffer-size.
 * This function also returns the handle of the incomplete message
 * in a reference. In error situations remember to delete server-side
 * incomplete message if this function gives the handle to it.
 * If not given, -1 is set to aIncompleteMessageHandle.
 * 
 * @param aTempReturnBuf Buffer which contains realloc info sent
 *                       from server side and which is reallocated
 *                       according to it.
 * @param aIncompleteMessageHandle Handle of the incomplete message.
 * @return TInt KErrNone on success.
 */
TInt RetrieveNewDescLengthAndReAlloc( HBufC8*& aTempReturnBuf,
                                      TInt& aIncompleteMessageHandle );

/**
 * Retrieves realloc-information from the given descriptor and
 * reallocates the descriptor according to it. Also makes the
 * descriptor empty. Realloc-information is expected to be sent from
 * the server-side to inform of a too small return buffer-size.
 * This function also returns the handle of the incomplete message
 * in a reference. In error situations remember to delete server-side
 * incomplete message if this function gives the handle to it.
 * If not given, -1 is set to aIncompleteMessageHandle.
 * 
 * @param aTempReturnBuf Buffer which contains realloc info sent
 *                       from server side and which is reallocated
 *                       according to it.
 * @param aIncompleteMessageHandle Handle of the incomplete message.
 * @return TInt KErrNone on success.
 */
TInt RetrieveNewDescLengthAndReAlloc( HBufC16*& aTempReturnBuf,
                                      TInt& aIncompleteMessageHandle );




/**
 * Function that retrieves handle of a incomplete message and a
 * new descriptor maximum length from the given descriptor. The message
 * in descriptor is expected to be sent from the server-side to
 * inform of a too small return buffer-size.
 * 
 * @param aTempReturnBuf Buffer which contains realloc info sent
 *                       from server side and which is reallocated
 *                       according to it.
 * @param aIncompleteMessageHandle Handle of the incomplete message.
 * @return TInt KErrNone on success.
 */
TInt InterpretNewAllocInfo( const HBufC8& aTempReturnBuf,
                            TInt& aIncompleteMessageHandle,
                            TInt& aNewDescriptorMaxLength );
                            
/**
 * Function that retrieves handle of a incomplete message and a
 * new descriptor maximum length from the given descriptor. The message
 * in descriptor is expected to be sent from the server-side to
 * inform of a too small return buffer-size.
 * 
 * @param aTempReturnBuf Buffer which contains realloc info sent
 *                       from server side and which is reallocated
 *                       according to it.
 * @param aIncompleteMessageHandle Handle of the incomplete message.
 * @return TInt KErrNone on success.
 */
TInt InterpretNewAllocInfo( const HBufC16& aTempReturnBuf,
                            TInt& aIncompleteMessageHandle,
                            TInt& aNewDescriptorMaxLength );


#endif // CATALOGS_CLIENTSERVER_ALLOC_UTILS_H