MCL/sf/os/persistentdata: comparison persistentstorage/store/USTRM/US

equal deleted inserted replaced

--1:000000000000
+:08ec8eefde2f
+// Copyright (c) 1998-2009 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:
+//
+#include "US_STD.H"
+EXPORT_C TInt MStreamBuf::Synch()
+/** Synchronises the stream buffer with the stream, returning any error.
+In effect, this ensures that buffered data is delivered to the stream.
+This function calls SynchL() inside a TRAPD harness and returns the leave
+code if a leave occurs.
+@return KErrNone, if successful; otherwise one of the other system wide error
+codes.
+@see MStreamBuf::SynchL()
+@see MStreamBuf::DoSynchL() */
+	{
+	TRAPD(r,SynchL());
+	return r;
+	}
+EXPORT_C void MStreamBuf::Close()
+/** Closes the stream buffer.
+This function attempts to synchronise buffered data with the stream before
+freeing any resources. All errors are ignored.
+@see MStreamBuf::Synch()
+@see MStreamBuf::Release() */
+	{
+	Synch();
+	Release();
+	}
+EXPORT_C void MStreamBuf::PushL()
+/** Puts a cleanup item for this object onto the cleanup stack.
+This allows allocated resources to be cleaned up if a subsequent leave occurs. */
+	{
+	CleanupReleasePushL(*this);
+	}
+EXPORT_C TInt MStreamBuf::Read(TDes8& aDes,TRequestStatus& aStatus)
+/** Reads data, asynchronously, from the stream buffer into the specified descriptor;
+request completion is guaranteed, even if request initiation fails.
+The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&)
+to implement this behaviour. The maximum number of bytes to be read is the
+value of the maximum length of the descriptor.
+@param aDes The target descriptor for the data read from the stream buffer.
+@param aStatus The request status that indicates the completion status of this
+asynchronous request.
+@return The maximum number of bytes to be read, as used in this request. This
+value can be different to the maximum length of the descriptor; this is dependent
+on the implementation.
+@see MStreamBuf::DoReadL() */
+	{
+	return Read(aDes,aDes.MaxLength(),aStatus);
+	}
+EXPORT_C TInt MStreamBuf::Read(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
+/** Reads data, asynchronously, from the stream buffer into the specified descriptor;
+request completion is guaranteed, even if request initiation fails.
+The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&)
+to implement this behaviour.
+@param aDes The target descriptor for the data read from the stream buffer.
+@param aMaxLength The maximum number of bytes to be read.
+@param aStatus The request status that indicates the completion status of this
+asynchronous request.
+@return The maximum number of bytes to be read, as used in this request. This
+can be different to the value supplied in aMaxLength; this is dependent on
+the implementation.
+@see MStreamBuf::DoReadL() */
+	{
+	TInt len=0;
+	TRAPD(r,len=DoReadL(aDes,aMaxLength,aStatus));
+	if (r!=KErrNone)
+		{
+		TRequestStatus* stat=&aStatus;
+		User::RequestComplete(stat,r);
+		}
+	return len;
+	}
+EXPORT_C TInt MStreamBuf::ReadL(TDes8& aDes,TRequestStatus& aStatus)
+/** Reads data, asynchronously, from the stream buffer into the specified descriptor.
+The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&)
+to implement this behaviour. The maximum number of bytes to be read is the
+maximum length of the descriptor.
+If the function leaves, then no read request will have been initiated.
+@param aDes The target descriptor for the data read from the stream buffer.
+@param aStatus The request status that indicates the completion status of this
+asynchronous request.
+@return The maximum number of bytes to be read, as used in this request. This
+value can be different to the maximum length of the descriptor; this is dependent
+on the implementation.
+@see MStreamBuf::DoReadL() */
+	{
+	return DoReadL(aDes,aDes.MaxLength(),aStatus);
+	}
+EXPORT_C TInt MStreamBuf::ReadL(MStreamInput& anInput,TInt aMaxLength)
+/** Reads data from the stream buffer into the specified data sink.
+The function uses the virtual function DoReadL(MStreamInput&,TStreamTransfer)
+to implement this behaviour.
+@param anInput The data sink which is the target for the read operation.
+@param aMaxLength The maximum amount of data available to be read.
+@return The amount of data that was not consumed. */
+	{
+	return aMaxLength-DoReadL(anInput,TStreamTransfer(aMaxLength)).Left();
+	}
+EXPORT_C TInt MStreamBuf::Write(const TDesC8& aDes,TRequestStatus& aStatus)
+/** Writes data, asynchronously, from the specified descriptor into the stream buffer;
+request completion is guaranteed, even if request initiation fails.
+The function calls the virtual function DoWriteL(const TDesC8&,TInt,TRequestStatus&)
+to implement this behaviour. The maximum number of bytes to be written is
+the value of the maximum length of the descriptor.
+@param aDes The source descriptor for the data to be written into the stream
+buffer.
+@param aStatus The request status that indicates the completion status of this
+asynchronous request.
+@return The maximum number of bytes to be written, as used in this request.
+This can be different to the value supplied in aMaxLength; this is dependent
+on the implementation.
+@see MStreamBuf::DoWriteL() */
+	{
+	return Write(aDes,aDes.Length(),aStatus);
+	}
+EXPORT_C TInt MStreamBuf::Write(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
+//
+// Write up to aMaxLength bytes with guaranteed completion.
+//
+	{
+	TInt len=0;
+	TRAPD(r,len=DoWriteL(aDes,aMaxLength,aStatus));
+	if (r!=KErrNone)
+		{
+		TRequestStatus* stat=&aStatus;
+		User::RequestComplete(stat,r);
+		}
+	return len;
+	}
+EXPORT_C TInt MStreamBuf::WriteL(const TDesC8& aDes,TRequestStatus& aStatus)
+/** Writes data, asynchronously, from the specified descriptor into the stream buffer.
+The function calls the virtual function DoWriteL(const TDesC8&,TInt,TRequestStatus&)
+to implement this behaviour. The maximum number of bytes to be written is
+the value of the maximum length of the descriptor.
+If the function leaves, then no write request will have been initiated.
+@param aDes The source descriptor for the data to be written into the stream
+buffer.
+@param aStatus The request status that indicates the completion status of this
+asynchronous request.
+@return The maximum number of bytes to be written, as used in this request.
+This can be different to the maximum length of the descriptor; this is dependent
+on the implementation.
+@see MStreamBuf::DoWriteL() */
+	{
+	return DoWriteL(aDes,aDes.Length(),aStatus);
+	}
+EXPORT_C TInt MStreamBuf::WriteL(MStreamOutput& anOutput,TInt aMaxLength)
+/** Writes data into the stream buffer from the specified data source.
+The function calls the virtual function DoWriteL(MStreamOutput&,TStreamTransfer)
+to implement this behaviour.
+@param anOutput The data source for the write operation.
+@param aMaxLength The maximum amount of data available to be written.
+@return The amount of data that was not consumed. */
+	{
+	return aMaxLength-DoWriteL(anOutput,TStreamTransfer(aMaxLength)).Left();
+	}
+EXPORT_C void MStreamBuf::DoRelease()
+/** Frees resources before abandoning the stream buffer.
+It is called by Release().
+This implementation is empty, but classes derived from MStreamBuf can provide
+their own implementation, if necessary.
+@see MStreamBuf::Release() */
+	{}
+EXPORT_C void MStreamBuf::DoSynchL()
+/** Synchronises the stream buffer with the stream, leaving if any error occurs.
+In effect, this ensures that buffered data is delivered to the stream.
+It is called by SynchL().
+This implementation is empty, but classes derived from MStreamBuf can provide
+their own implementation, if necessary.
+@see MStreamBuf::SynchL() */
+	{}
+EXPORT_C TInt MStreamBuf::DoReadL(TAny*,TInt)
+//
+// Cannot read from this stream buffer.
+//
+	{
+	Panic(EStreamCannotRead);
+	return TInt();
+	}
+EXPORT_C TInt MStreamBuf::DoReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
+/** Reads data from the stream buffer into the specified descriptor.
+This function is called by ReadL(TDes8&,TInt,TRequestStatus&).
+This implementation deals with the request synchronously, and completes the
+request with KErrNone. Other implementations may choose to deal with this
+in a true asynchronous manner.
+In addition, the read operation itself uses the DoReadL(TAny*,TInt) variant.
+@param aDes The target descriptor for the data read from the stream buffer.
+On return, the length of the descriptor is set to the number of bytes read
+from the stream buffer.
+@param aMaxLength The maximum number of bytes to be read. This value must not
+be greater than the maximum length of the descriptor, otherwise the function
+raises a STORE-Stream 2 panic.
+@param aStatus The request status that indicates the completion status of this
+asynchronous request.
+@return The maximum number of bytes to be read, as used in this request. This
+implementation uses, and returns, the value supplied in aMaxLength. Other
+implementations may choose to use a different value.
+@see MStreamBuf::ReadL() */
+	{
+	__ASSERT_DEBUG(aMaxLength<=aDes.MaxLength(),Panic(EStreamReadBeyondEnd));
+	aDes.SetLength(DoReadL((TUint8*)aDes.Ptr(),aMaxLength));
+	TRequestStatus* stat=&aStatus;
+	User::RequestComplete(stat,KErrNone);
+	return aMaxLength;
+	}
+EXPORT_C TStreamTransfer MStreamBuf::DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer)
+/** Reads data from the stream into the specified data sink.
+It is called by ReadL(MStreamInput&,TStreamTransfer).
+This implementation calls the sink's ReadFromL() function, which performs
+the read (transfer) operation.
+This implementation of DoReadL() is called for streams that do not have buffering
+capabilities, and that are derived directly from this class.
+@param anInput The target data sink.
+@param aTransfer A stream transfer object defining the amount of data available
+to be read.
+@return A stream transfer object defining the amount of data that was not consumed.
+@see MStreamInput::ReadFromL() */
+	{
+	return anInput.ReadFromL(*this,aTransfer);
+	}
+EXPORT_C void MStreamBuf::DoWriteL(const TAny*,TInt)
+//
+// Cannot write to this stream buffer.
+//
+	{
+	Panic(EStreamCannotWrite);
+	}
+EXPORT_C TInt MStreamBuf::DoWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
+/** Writes data from the specified descriptor into this stream buffer.
+This function is called by WriteL(const TDesC8&,TInt,TRequestStatus&).
+This implementation deals with the request synchronously, and completes the
+request with KErrNone. Other implementations may choose to deal with this
+in a true asynchronous manner.
+In addition, the write operation itself uses the DoWriteL(TAny*,TInt) variant.
+@param aDes The source descriptor for the data to be written into the stream
+buffer.
+@param aMaxLength The number of bytes to be written. This value must not be
+greater than the maximum length of the descriptor, otherwise the function
+raises a STORE-Stream 6 panic.
+@param aStatus The request status that indicates the completion status of this
+asynchronous request.
+@return The maximum number of bytes to be written, as used in this request.
+This implementation uses, and returns, the value supplied in aMaxLength. Other
+implementations may choose to use a different value.
+@see MStreamBuf::WriteL() */
+	{
+	__ASSERT_DEBUG(aMaxLength<=aDes.Length(),Panic(EStreamWriteBeyondEnd));
+	DoWriteL(aDes.Ptr(),aMaxLength);
+	TRequestStatus* stat=&aStatus;
+	User::RequestComplete(stat,KErrNone);
+	return aMaxLength;
+	}
+EXPORT_C TStreamTransfer MStreamBuf::DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer)
+//
+// Default implementation turning around to anOutput.
+//
+	{
+	return anOutput.WriteToL(*this,aTransfer);
+	}
+EXPORT_C TStreamPos MStreamBuf::DoSeekL(TMark,TStreamLocation,TInt)
+//
+// This stream buffer does not support seeking.
+//
+	{
+	Panic(EStreamCannotSeek);
+	TStreamPos streamPos(-1);
+	return streamPos;
+	}
+EXPORT_C TStreamBuf::TStreamBuf()
+	: iRPtr(NULL),iREnd(NULL),iWPtr(NULL),iWEnd(NULL)
+/** Sets the pointers that mark out the read and write areas within the intermediate
+buffer to null. */
+	{}
+EXPORT_C void TStreamBuf::SetBuf(TArea anArea,TUint8* aPtr,TUint8* anEnd)
+/** Sets the start and end points of the read and/or the write area within the intermediate
+buffer.
+A start point is always within an area; an end point is always the first byte
+beyond the end of an area.
+@param anArea The areas within the intermediate buffer for which the start
+and end points are to be set. These can be the read area and/or the write
+area, as indicated by the ERead and EWrite bits. Only these bits can be set,
+otherwise the function raises a STORE-Stream 17 panic.
+@param aPtr The start point.
+@param anEnd The end point.
+@see MStreamBuf::TRead
+@see MStreamBuf::TWrite */
+	{
+	__ASSERT_ALWAYS(!(anArea&~(ERead|EWrite)),Panic(EStreamAreaInvalid));
+	if (anArea&ERead)
+		SetBuf(ERead,aPtr,anEnd);
+	if (anArea&EWrite)
+		SetBuf(EWrite,aPtr,anEnd);
+	}
+EXPORT_C void TStreamBuf::SetPtr(TArea anArea,TUint8* aPtr)
+/** Sets the start point of the read and/or the write area within the intermediate
+buffer.
+A start point is always within an area.
+@param anArea The areas within the intermediate buffer for which the start
+point is to be set. These can be the read area and/or the write area, as indicated
+by the ERead and EWrite bits. Only these bits can be set, otherwise the function
+raises a STORE-Stream 17 panic.
+@param aPtr The start point.
+@see MStreamBuf::TRead
+@see MStreamBuf::TWrite */
+	{
+	__ASSERT_ALWAYS(!(anArea&~(ERead|EWrite)),Panic(EStreamAreaInvalid));
+	if (anArea&ERead)
+		SetPtr(ERead,aPtr);
+	if (anArea&EWrite)
+		SetPtr(EWrite,aPtr);
+	}
+EXPORT_C void TStreamBuf::SetEnd(TArea anArea,TUint8* anEnd)
+//
+// Set the end pointer for the buffer area(s) indicated by anArea.
+//
+	{
+	__ASSERT_ALWAYS(!(anArea&~(ERead|EWrite)),Panic(EStreamAreaInvalid));
+	if (anArea&ERead)
+		SetEnd(ERead,anEnd);
+	if (anArea&EWrite)
+		SetEnd(EWrite,anEnd);
+	}
+EXPORT_C TUint8* TStreamBuf::Ptr(TArea anArea) const
+/** Gets the current start point of the read or write area within the intermediate
+buffer.
+@param anArea The area within the intermediate buffer for which the start
+point is to be fetched. This can be either the read area or the write area,
+as indicated by the ERead and EWrite bits. Only one of these can be set, otherwise
+the function raises a STORE-Stream 17 panic.
+@return The start point.
+@see MStreamBuf::TRead
+@see MStreamBuf::TWrite */
+	{
+	if (anArea==ERead)
+		return Ptr(ERead);
+//
+	__ASSERT_ALWAYS(anArea==EWrite,Panic(EStreamAreaInvalid));
+	return Ptr(EWrite);
+	}
+EXPORT_C TUint8* TStreamBuf::End(TArea anArea) const
+/** Gets the current end point of the read or write area within the intermediate
+buffer.
+An end point is always the first byte beyond the end of an area.
+@param anArea The area within the intermediate buffer for which the end point
+is to be fetched. This can be either the read area or the write area, as indicated
+by the ERead and EWrite bits. Only one of these can be set, otherwise the
+function raises a STORE-Stream 17 panic.
+@return The end point. */
+	{
+	if (anArea==ERead)
+		return End(ERead);
+//
+	__ASSERT_ALWAYS(anArea==EWrite,Panic(EStreamAreaInvalid));
+	return End(EWrite);
+	}
+EXPORT_C TInt TStreamBuf::Avail(TArea anArea) const
+/** Gets the number of bytes available in the read or write area within the intermediate
+buffer.
+@param anArea The area within the intermediate buffer for which the number
+of available bytes is to be fetched. This can be either the read area or the
+write area, as indicated by the ERead and EWrite bits. Only one of these can
+be set, otherwise the function raises a STORE-Stream 17 panic.
+@return The number of bytes available. */
+	{
+	if (anArea==ERead)
+		return Avail(ERead);
+//
+	__ASSERT_ALWAYS(anArea==EWrite,Panic(EStreamAreaInvalid));
+	return Avail(EWrite);
+	}
+EXPORT_C TInt TStreamBuf::DoReadL(TAny* aPtr,TInt aMaxLength)
+/** Reads data from the intermediate buffer into the specified memory location.
+The function calls the virtual function UnderfLowL() to give concrete implementations
+the chance to refill the intermediate buffer, and satisfy the caller's requirements.
+This implementation overrides the one supplied by the base class MStreamBuf,
+and is called by, MStreamBuf::ReadL(TAny*,TInt).
+@param aPtr A pointer to the target memory location for the data read from
+the intermediate buffer.
+@param aMaxLength The maximum number of bytes to be read.
+@return The number of bytes read. This may be less than the amount requested.
+@see MStreamBuf::ReadL()
+@see MStreamBuf::DoReadL() */
+	{
+	__ASSERT_DEBUG(aMaxLength>=0,Panic(EStreamReadLengthNegative));
+	__ASSERT_DEBUG(aMaxLength>0,Panic(EStreamReadNoTransfer));
+	__ASSERT_DEBUG(Ptr(ERead)!=NULL||End(ERead)==NULL,Panic(EStreamCannotRead));
+	TInt left=aMaxLength;
+	TInt avail=Avail(ERead);
+	__ASSERT_DEBUG(avail>=0,User::Invariant());
+	if (avail==0)
+		goto underflow;
+//
+	do
+		{
+		__ASSERT_DEBUG(avail==Avail(ERead),Panic(EStreamUnderflowInBreach));
+		__ASSERT_DEBUG(left>0&&avail>0,User::Invariant());
+		{
+		TInt len=Min(left,avail);
+		TUint8* ptr=Ptr(ERead);
+		aPtr=Mem::Copy(aPtr,ptr,len);
+		SetPtr(ERead,ptr+len);
+		left-=len;
+		if (left==0)
+			return aMaxLength; // that's it
+		}
+//
+	underflow:
+		avail=UnderflowL(left);
+		} while (avail>0);
+	__ASSERT_DEBUG(avail==0&&Avail(ERead)==0,Panic(EStreamUnderflowInBreach));
+	return aMaxLength-left;
+	}
+EXPORT_C TStreamTransfer TStreamBuf::DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer)
+/** Reads data from the intermediate buffer and, if necessary, any remaining data
+from the stream to the specified target stream input object.
+It is called by ReadL(MStreamInput&,TStreamTransfer).
+The intermediate buffer is emptied first by calling the target stream input's
+PushL() function, which performs the read from intermediate buffer operation.
+Any remaining data is then read from the stream by calling the target stream
+object's ReadFromL() function, which performs the read from stream operation.
+This implementation is called for streams that have buffering capabilities
+and are derived from this class.
+@param anInput The target stream input object.
+@param aTransfer A stream transfer object defining the amount of data available
+to be written.
+@return The amount of data that was not consumed.
+@see MStreamInput::ReadFromL()
+@see MStreamInput::PushL() */
+	{
+	__ASSERT_DEBUG(aTransfer>0,Panic(EStreamReadNoTransfer));
+	__ASSERT_DEBUG(Ptr(ERead)!=NULL||End(ERead)==NULL,Panic(EStreamCannotRead));
+	__ASSERT_DEBUG(Avail(ERead)>=0,User::Invariant());
+	TInt len=aTransfer[Avail(ERead)];
+	if (len>0)
+		{
+		__DEBUG(TInt avail=Avail(ERead)); // may be pushing into this streambuf
+		TUint8* ptr=Ptr(ERead);
+		len=anInput.PushL(ptr,len);
+		__ASSERT_DEBUG(len>=0&&len<=aTransfer[avail]&&Ptr(ERead)==ptr&&Avail(ERead)>=avail,Panic(EStreamPushInBreach));
+		SetPtr(ERead,ptr+len);
+		aTransfer-=len;
+		}
+	if (aTransfer>0)
+		aTransfer=anInput.ReadFromL(*this,aTransfer);
+	return aTransfer;
+	}
+EXPORT_C void TStreamBuf::DoWriteL(const TAny* aPtr,TInt aLength)
+/** Writes data from the specified memory location into the intermediate buffer.
+The function calls the virtual function OverfLowL() to give concrete implementations
+the chance to forward the intermediate buffer content to its destination.
+This implementation overrides the one supplied by the base class MStreamBuf,
+and is called by MStreamBuf::WriteL(const TAny*,TInt).
+@param aPtr A pointer to the source memory location for the data to be written
+to the intermediate buffer.
+@param aLength The number of bytes to be written.
+@return The number of bytes written.
+@see MStreamBuf::WriteL()
+@see MStreamBuf::DoWriteL() */
+	{
+	__ASSERT_DEBUG(aLength>=0,Panic(EStreamWriteLengthNegative));
+	__ASSERT_DEBUG(aLength>0,Panic(EStreamWriteNoTransfer));
+	__ASSERT_DEBUG(Ptr(EWrite)!=NULL||End(EWrite)==NULL,Panic(EStreamCannotWrite));
+	TInt avail=Avail(EWrite);
+	__ASSERT_DEBUG(avail>=0,User::Invariant());
+	if (avail==0)
+		goto overflow;
+//
+	for(;;)
+		{
+		__ASSERT_DEBUG(avail>0,Panic(EStreamOverflowInBreach));
+		__ASSERT_DEBUG(aLength>0,User::Invariant());
+		{
+		TInt len=Min(aLength,avail);
+		SetPtr(EWrite,Mem::Copy(Ptr(EWrite),aPtr,len));
+		aLength-=len;
+		if (aLength==0)
+			return; // done
+//
+		aPtr=(TUint8*)aPtr+len;
+		}
+//
+	overflow:
+		OverflowL();
+		avail=Avail(EWrite);
+		};
+	}
+EXPORT_C TStreamTransfer TStreamBuf::DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer)
+//
+// Default implementation filling the buffer before turning around to anOutput.
+//
+	{
+	__ASSERT_DEBUG(aTransfer>0,Panic(EStreamWriteNoTransfer));
+	__ASSERT_DEBUG(Ptr(EWrite)!=NULL||End(EWrite)==NULL,Panic(EStreamCannotWrite));
+	__ASSERT_DEBUG(Avail(EWrite)>=0,User::Invariant());
+	TInt len=aTransfer[Avail(EWrite)];
+	if (len>0)
+		{
+		__DEBUG(TInt avail=Avail(EWrite)); // may be pulling from this streambuf
+		TUint8* ptr=Ptr(EWrite);
+		len=anOutput.PullL(ptr,len);
+		__ASSERT_DEBUG(len>=0&&len<=aTransfer[avail]&&Ptr(EWrite)==ptr&&Avail(EWrite)>=avail,Panic(EStreamPullInBreach));
+		SetPtr(EWrite,ptr+len);
+		aTransfer-=len;
+		}
+	if (aTransfer>0)
+		aTransfer=anOutput.WriteToL(*this,aTransfer);
+	return aTransfer;
+	}