sl@0: // Copyright (c) 2006-2010 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #ifndef __SQLBUFFLAT_H__
sl@0: #define __SQLBUFFLAT_H__
sl@0: 
sl@0: #include <e32base.h>
sl@0: #include "SqlAssert.h"
sl@0: 
sl@0: //Forward declarations
sl@0: class TSqlBufRIterator;
sl@0: class CSqlSecurityPolicy;
sl@0: class TSqlSecurityPolicyIterator;
sl@0: 
sl@0: #ifdef _DEBUG
sl@0: const TUint64 KSqlBufFlatMagicValue = 0xAA11BB44221199EEULL;//TInt64 for 8-byte alignment
sl@0: #define SQLFLATBUF_INVARIANT() Invariant()
sl@0: #else
sl@0: #define SQLFLATBUF_INVARIANT() void(0)
sl@0: #endif
sl@0: 
sl@0: /**
sl@0: RSqlBufFlat class manages a flat memory buffer with fixed elements count.
sl@0: Each element (or field) of the flat buffer has a type and variable length data and is accessible using an
sl@0: index. The data may be NULL.
sl@0: The RSqlBufFlat objects are used for sending/receiving data between client dlls and servers, 
sl@0: because once the buffer filled, a pointer to the flat buffer data can be used to send the whole buffer in a single
sl@0: IPC call, which is more effective than using a stream like transfer.
sl@0: 
sl@0: RSqlBufFlat public functions are not very convenient for storing/retrieving values based on the column type 
sl@0: and there are two additional classes which may be used instead of working with the flat buffer directly: 
sl@0: TSqlBufRIterator and TSqlBufWIterator.
sl@0: 
sl@0: The physical structure of the flat buffer is:
sl@0: ---------------------------
sl@0: | SysData | Header | Data |
sl@0: ---------------------------
sl@0: - "SysData" has fixed length and contains fields with about the buffer used size, elements count, header size;
sl@0: - "Header"  has fixed length, which depends of the number of elements and contains cells, one per element.
sl@0:             Each cell contains information about: element type, element data length, the start position of the 
sl@0:             element data in the flat buffer, "present"/"not present" flag. "Not present" means that no memory
sl@0:             is reserved for the element data, but the buffer "knows" what is the element type and element data length;
sl@0:             (In the current design there is no "Present"/"Not present flag". If the data position is 0, that indicates
sl@0:             the element is "Not present"). See RSqlBufFlat::TCell comments for details.
sl@0: - "Data"    Is the dynamic part of the buffer which may grow during the operations with the flat buffer (setting
sl@0:             element data);
sl@0:             
sl@0: "Present"/"Not present" attribute has a key role in the large data transfers between the client and the server.
sl@0: In order to optimize memory usage, usually the client specifies what can be the max field size. The server
sl@0: knows that and when it fills a particular flat buffer, which has to be sent to the client, it puts in the
sl@0: flat buffer only the pieces of data whose size is less than the specified "large data" size. Any data piece whose
sl@0: size is larger will be set as "Not present" in the flat buffer. The "Not present" field will have all the
sl@0: attributes, like type and size, but won't have any data or any allocated flat buffer memory.
sl@0: So the client, when it receives the flat buffer, will know the field type and size and if it wants to get the field data,
sl@0: will have to make an additional call to the server. 
sl@0: 
sl@0: Note that the fields in the buffer are 8-byte aligned.
sl@0: 
sl@0: Typical examples how the buffer can be used:
sl@0: 
sl@0: Case 1 - a dll client wants to receive from the server a flat buffer data. 
sl@0: 
sl@0: @code
sl@0: RSqlBufFlat bufFlat;
sl@0: bufFlat.SetCount(N);								//N is the field count
sl@0: ....
sl@0: bufFlat.Reset();									//Clears the content of the buffer without shrinking it.
sl@0: ipcArgs.Set(0, bufFlat.MaxSize());					//Tell the server what is the flat buffer max size
sl@0: ipcArgs.Set(1, &bufFlat.BufPtr());
sl@0: TInt rc = session.SendReceive(funcNum, ipcArgs);
sl@0: if(rc > KSqlClientBufOverflowCode)
sl@0: 	{												//the client buffer is not big enough and has to be resized
sl@0: 	rc = bufFlat.ReAlloc(err - KSqlClientBufOverflowCode);
sl@0: 	if(rc != KErrNone)
sl@0: 		{
sl@0: 		return rc;
sl@0: 		}
sl@0: 	ipcArgs.Set(0, bufFlat.MaxSize());
sl@0: 	ipcArgs.Set(1, &bufFlat.BufPtr());
sl@0: 	rc = session.SendReceive(funcNum, ipcArgs);
sl@0: 	}
sl@0: @endcode
sl@0: 
sl@0: Case 2 - a dll client wants to send to the server a flat buffer data. 
sl@0: 
sl@0: @code
sl@0: RSqlBufFlat bufFlat;
sl@0: bufFlat.SetCount(N);								//N is the field count
sl@0: ....
sl@0: TPtrC8 ptr(bufFlat.BufDes());
sl@0: TInt err = session.SendReceive(funcNum, TIpcArgs(ptr.Length(), &ptr));
sl@0: @endcode
sl@0: 
sl@0: Case 3 - the server wants to return to the client a flat buffer data.
sl@0: @code
sl@0: RSqlBufFlat bufFlat;
sl@0: bufFlat.SetCount(N);								//N is the field count
sl@0: ....
sl@0: TInt maxCliBufSize = msg.Int0();					//The max size of the client buffer
sl@0: if(maxCliBufSize < bufFlat.Size())
sl@0: 	{
sl@0: 	return bufFlat.Size() + KSqlClientBufOverflowCode;//Tell the client that its buffer is too small
sl@0: 	}
sl@0: msg.WriteL(1, bufFlat.BufDes());
sl@0: @endcode
sl@0: 
sl@0: Case 4 - the server wants to receive from the client a flat buffer data.
sl@0: @code
sl@0: RSqlBufFlat bufFlat;
sl@0: bufFlat.SetCount(N);								//N is the field count
sl@0: ....
sl@0: TInt cliBufFlatLen = aMessage.Int0();
sl@0: TInt err = bufFlat.ReAlloc(cliBufFlatLen);			//Reallocate memory for the flat buffer
sl@0: if(err != KErrNone)
sl@0: 	{
sl@0: 	return err;
sl@0: 	}
sl@0: msg.ReadL(1, bufFlat.BufPtr());
sl@0: @endcode
sl@0: 
sl@0: Case 5 - the server (or the client) wants to fill the flat buffer with some data.
sl@0: @code
sl@0: RSqlBufFlat bufFlat;
sl@0: bufFlat.SetCount(N);								//N is the field count
sl@0: ....
sl@0: TInt err = flatBuf.SetCount(M);						//If the field count has to be changed to M
sl@0: if(err != KErrNone)
sl@0: 	{
sl@0: 	return err;
sl@0: 	}
sl@0: //use the TSqlBufWIterator iterator to fill the buffer
sl@0: @endcode
sl@0: 
sl@0: @see TSqlBufRIterator
sl@0: @see TSqlBufWIterator
sl@0: @see RSqlBufFlat::TCell
sl@0: @see RSqlBufFlat::TBufFlat
sl@0: 
sl@0: @internalComponent
sl@0: */
sl@0: class RSqlBufFlat
sl@0: 	{
sl@0: 	friend class TSqlBufRIterator;
sl@0: 	friend class CSqlSecurityPolicy;
sl@0: 	friend class TSqlSecurityPolicyIterator;
sl@0: 
sl@0: public:	
sl@0: 	//This enum has to be in the "public" section because it is used by TCell (declared as "private" in RSqlBufFlat)
sl@0: 	enum 
sl@0: 		{
sl@0: 		EWidthType = 3, 					//Bit width of the "Type" field of the header cell
sl@0: 		EWidthLen = 29						//Bit width of the "Length" field of the header cell
sl@0: 		};
sl@0: 	//This enum has to be in the "public" section because it is used by TCell (declared as "private" in RSqlBufFlat)
sl@0: 	enum 
sl@0: 		{
sl@0: 		EMaxType = 1 << EWidthType, 		//Max allowed flat buffer field type
sl@0: 		EMaxLength = 1 << EWidthLen			//Max allowed flat buffer field length
sl@0: 		};
sl@0: 
sl@0: 	RSqlBufFlat();
sl@0: 	TInt SetCount(TInt aCount);
sl@0: 	TInt ReAlloc(TInt aSize);
sl@0: 	void ResetAndMinimize();
sl@0: 	void Reset();
sl@0: 	void Close();
sl@0: 	inline TInt Count() const;
sl@0: 	inline TInt Size() const;
sl@0: 	inline TInt MaxSize() const;
sl@0: 	
sl@0: 	TInt SetField(TInt aIndex, TInt aType, const void* aData, TInt aDataLength);
sl@0: 	
sl@0: 	inline const TDesC8& BufDes() const;
sl@0: 	inline TPtr8& BufPtr();
sl@0: 	
sl@0: private:	//Data type declarations
sl@0: 	/**
sl@0: 	TCell represents the structure of header cells.
sl@0: 	Each cells contains the following fields:
sl@0: 	- Flat buffer field type;
sl@0: 	- Flat buffer field length;
sl@0: 	- Flat buffer field data position;
sl@0: 	  = if 0 then the field is "Not present" (no memory is reserved for the field data, the field data is missing);
sl@0: 	  = if positive - the field data position in the flat buffer (counting from the beginning of the header);
sl@0: 	  = if negative - the field is "Not present", but memory has been reserved for it;
sl@0: 	  
sl@0: 	RSqlBufFlat class offers fast, indexed access to the header cells.
sl@0: 	
sl@0: 	@see RSqlBufFlat
sl@0: 	*/
sl@0: 	struct TCell
sl@0: 		{
sl@0: 		inline TInt Type() const {return (iBits >> RSqlBufFlat::EWidthLen) & (RSqlBufFlat::EMaxType - 1);}
sl@0: 		inline TInt Size() const {return (iBits & (RSqlBufFlat::EMaxLength - 1));}
sl@0: 		TUint32	iBits;						//element type: EWidthType bits & element length: EWidthLen bits.
sl@0: 		TInt32	iPos;						//element data position, relative to the beginning of the header.
sl@0: 											//                       Zero if the element is not present.
sl@0: 											//                       Negative if the element is not present but memory is reserved.
sl@0: 		};
sl@0: 
sl@0: 	enum {EExpandSize = 256};				//iBuf min expansion size - it must be a power of 2 and 
sl@0: 											//                          (EExpandSize % 8) should be 0.
sl@0: 	/**
sl@0: 	TBufFlat structure represents the "SysData" part of the flat buffer (see RSqlBufFlat comments), beyond which
sl@0: 	begins the flat buffer header and "Data" part.
sl@0: 
sl@0: 	TBufFlat structure contains information about:
sl@0: 	- Flat buffer elements count;
sl@0: 	- Flat buffer header size;
sl@0: 	- The size of used part of the flat buffer;
sl@0: 
sl@0: 	@see RSqlBufFlat
sl@0: 	*/
sl@0: 	struct TBufFlat
sl@0: 		{
sl@0: 		TInt	iCount;			//element count
sl@0: 		TInt	iHeaderSize;	//buffer header size	
sl@0: 		TInt	iSize;			//used buffer size
sl@0: 		TInt	iReserved;		//maintains TBufFlat 8-byte aligned
sl@0: 		};
sl@0: 	
sl@0: private:	//Method declarations
sl@0: 	void DoInit();
sl@0: 	TInt DoReAlloc(TInt aSize);
sl@0: 	inline TInt Available() const;
sl@0: 	void DoSet(TInt aIndex, TInt aType, const void* aData, TInt aDataLength);
sl@0: 	TInt Reserve(TInt aLength);
sl@0: 	void Invariant() const;
sl@0: 	inline const TCell* Header() const;
sl@0: 	inline TCell* Header();
sl@0: 	inline TInt SysDataSize() const;
sl@0: 	
sl@0: private:	//Data declarations
sl@0: 	// IPC data
sl@0: 	TBufFlat*		iBuf;
sl@0: 	// non-IPC data
sl@0: 	TInt			iMaxSize;	//max buffer size (allocated memory), not part of RSqlBufFlat data (IPC - sent/received).
sl@0: 								//iMaxSize can't be part of the IPC data, because it may be overwritten, which leads to 
sl@0: 								//"hard to detect" problems. For example:
sl@0: 								//  - client sends to the server in/out flat buffer with max size 256 bytes (allocated);
sl@0: 								//  - the server has a flat buffer which max size is 512, but the used size is 200;
sl@0: 								//  - the client flat buffer has enough space for those 200 bytes, so the server will
sl@0: 								//    copy its flat buffer content to the client flat buffer. The client's flat buffer
sl@0: 								//    iMaxSize data member will lose its original value (256) and will have new value assigned -
sl@0: 								//    512. But the client flat buffer does not have 512 bytes allocated!
sl@0: 	mutable TPtrC8	iBufPtrC;	//it is set to point to iBuf. Not part of RSqlBufFlat data (IPC - sent/received)
sl@0: 	mutable TPtr8	iBufPtr;	//it is set to point to iBuf. Not part of RSqlBufFlat data (IPC - sent/received)
sl@0: 	};
sl@0: 
sl@0: #include "SqlBufFlat.inl"
sl@0: 
sl@0: #endif//__SQLBUFFLAT_H__