1 s32share.inl

     1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 // Class TStreamMark

    17 inline TStreamMark::TStreamMark()

    18 	: iPos(KStreamBeginning-1)

    19 /** Constructs a default shared stream mark object.

    20 

    21 The position for the mark is uninitialised.

    22 

    23 An uninitialised mark means that a call to IsEmpty() returns true.

    24 

    25 @see IsEmpty() */

    26 	{}

    27 inline TStreamMark::TStreamMark(TStreamPos aPos)

    28 	: iPos(aPos)

    29 /** Constructs the shared stream mark object, setting the mark to the specified 

    30 stream position.

    31 

    32 An initialised mark means that a call to IsEmpty() returns false.

    33 

    34 @param aPos The stream position

    35 @see IsEmpty() */

    36 	{

    37 #if defined (_DEBUG)

    38 	__DbgChkPos(aPos);

    39 #endif

    40 	}

    41 inline TStreamMark& TStreamMark::operator=(TStreamPos aPos)

    42 /** Assigns the specified stream position value to this shared stream mark object.

    43 

    44 @param aPos The stream position value to be assigned.

    45 @return A reference to this shared stream mark object. */

    46 	{

    47 #if defined (_DEBUG)

    48 	__DbgChkPos(aPos);

    49 #endif

    50 	iPos=aPos;

    51 	return *this;

    52 	}

    53 inline TStreamMark::operator TStreamMark*()

    54 	{return this;}

    55 inline TStreamMark::operator const TStreamMark*() const

    56 	{return this;}

    57 inline TBool TStreamMark::operator==(const TStreamMark& aMark) const

    58 /** Tests whether this object and the specified referenced shared stream mark object 

    59 are the same object.

    60 

    61 @param aMark A reference to a shared stream mark object.

    62 @return True, if the two objects are the same object; false, otherwise. */

    63 	{return this==&aMark;}

    64 inline TBool TStreamMark::operator==(const TStreamMark* aPtr) const

    65 	{return this==aPtr;}

    66 inline TBool TStreamMark::operator!=(const TStreamMark& aMark) const

    67 /** Tests whether this object and the specified shared stream mark object are different 

    68 objects.

    69 

    70 @param aMark A pointer to a shared stream mark object.

    71 @return True, if the two objects are different objects; false, otherwise. */

    72 	{return this!=&aMark;}

    73 inline TBool TStreamMark::operator!=(const TStreamMark* aPtr) const

    74 	{return this!=aPtr;}

    75 inline TBool TStreamMark::IsEmpty() const

    76 /** Tests whether this mark object is uninitialised.

    77 

    78 @return True, if this mark object is uninitialised; false, otherwise. */

    79 	{return iPos<KStreamBeginning;}

    80 inline void TStreamMark::Clear()

    81 /** Resets the mark object to its default state.

    82 

    83 On return from this function, the mark is uninitialised and a call to IsEmpty() 

    84 returns true.

    85 

    86 Empties the object/makes it empty so that IsEmpty() returns false */

    87 	{iPos=KStreamBeginning-1;}

    88 inline TStreamPos TStreamMark::Position() const

    89 /** Gets the position of the mark.

    90 

    91 @return The stream position. */

    92 	{

    93 #if defined (_DEBUG)

    94 	__DbgChkPos(iPos);

    95 #endif

    96 	return iPos;

    97 	}

    98 inline TBool TStreamMark::IsWith(TStreamExchange& aHost) const

    99 /** Tests whether the specified shared streaming manager currently refers to this 

   100 mark object.

   101 

   102 @param aHost The object that manages shared streaming.

   103 @return True, if the shared stream manager refers to this mark; false, otherwise. */

   104 	{return aHost.RefersTo(*this);}

   105 inline TBool TStreamMark::RelatesTo(TStreamExchange& aHost) const

   106 /** Tests whether the specified shared streaming manager currently refers to this 

   107 mark object OR whether this mark object is initialised.

   108 

   109 @param aHost The object that manages shared streaming.

   110 @return True, if the shared stream manager refers to this mark OR if this mark 

   111 object is initialised; false, otherwise.

   112 @see IsWith()

   113 @see TStreamExchange::IsActive() */

   114 	{return iPos>=KStreamBeginning||aHost.RefersTo(*this);}

   115 inline void TStreamMark::Withdraw(TStreamExchange& aHost)

   116 /** Instructs the shared streaming manager to remove any reference it has to this 

   117 mark object.

   118 

   119 @param aHost The object that manages shared streaming. */

   120 	{aHost.Drop(*this);}

   121 inline void TStreamMark::ExtractL(TStreamExchange& aHost)

   122 /** Refreshes this mark from the mark in the host stream buffer and tells the shared 

   123 streaming manager to drop any reference it has to to this mark object.

   124 

   125 @param aHost The object that manages shared streaming. */

   126 	{aHost.GetL(*this);}

   127 inline TInt TStreamMark::ReadL(TStreamExchange& aHost,TAny* aPtr,TInt aMaxLength)

   128 /** Reads data from the shared stream into the specified memory location.

   129 

   130 @param aHost The object that manages shared streaming.

   131 @param aPtr A pointer to the target memory location for the data read from 

   132 the shared stream.

   133 @param aMaxLength The maximum number of bytes to be read.

   134 @return The number of bytes read. */

   135 	{return aHost.DoReadL(aPtr,aMaxLength,*this);}

   136 inline TInt TStreamMark::ReadL(TStreamExchange& aHost,TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus)

   137 /** Reads data, asynchronously, from the shared stream into the specified descriptor.

   138 

   139 If the function leaves, then no read request will have been initiated.

   140 

   141 @param aHost The object that manages shared streaming.

   142 @param aDes The target descriptor for the data read from the shared stream.

   143 @param aMaxLength The maximum number of bytes to be read.

   144 @param aStatus The request status that indicates the completion status of this 

   145 asynchronous request.

   146 @return The maximum number of bytes to be read, as used in this request. This 

   147 can be different to the value supplied in aMaxLength; this is dependent on 

   148 the implementation of the underlying stream. */

   149 	{return aHost.DoReadL(aDes,aMaxLength,aStatus,*this);}

   150 inline TStreamTransfer TStreamMark::ReadL(TStreamExchange& aHost,MStreamInput& anInput,TStreamTransfer aTransfer)

   151 /** Reads data from the shared stream into the specified data sink.

   152 

   153 @param aHost The object that manages shared streaming.

   154 @param anInput The sink which is the target for the read operation.

   155 @param aTransfer Defines the amount of data available to be read from the shared 

   156 stream.

   157 @return The amount of data that was not consumed. */

   158 	{return aHost.DoReadL(anInput,aTransfer,*this);}

   159 inline TInt TStreamMark::ReadL(TStreamExchange& aHost,MStreamInput& anInput,TInt aMaxLength)

   160 /** Reads data from the shared stream into the specified data sink.

   161 

   162 @param aHost The object that manages shared streaming.

   163 @param anInput The sink which is the target for the read operation.

   164 @param aMaxLength The maximum amount of data available to be read from the 

   165 shared stream.

   166 @return The amount of data that was not consumed. */

   167 	{return aMaxLength-aHost.DoReadL(anInput,TStreamTransfer(aMaxLength),*this).Left();}

   168 inline void TStreamMark::ReadL(TStreamExchange& aHost,MStreamInput& anInput)

   169 /** Reads data from the shared stream into the specified data sink.

   170 

   171 No explicit limit is placed on the amount of data that can be read.

   172 

   173 @param aHost The object that manages shared streaming.

   174 @param anInput The sink which is the target for the read operation. */

   175 	{aHost.DoReadL(anInput,KStreamUnlimited,*this);}

   176 inline void TStreamMark::WriteL(TStreamExchange& aHost,const TAny* aPtr,TInt aLength)

   177 /** Writes data from the specified memory location into the shared stream.

   178 

   179 @param aHost The object that manages shared streaming.

   180 @param aPtr A pointer to the memory location from which data is to be written 

   181 to the shared stream.

   182 @param aLength The number of bytes to be written. */

   183 	{aHost.DoWriteL(aPtr,aLength,*this);}

   184 inline TInt TStreamMark::WriteL(TStreamExchange& aHost,const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus)

   185 /** Writes data, asynchronously, from the specified descriptor into the shared 

   186 stream.

   187 

   188 If the function leaves, then no write request will have been initiated.

   189 

   190 @param aHost The object that manages shared streaming.

   191 @param aDes The source descriptor for the data to be written into the shared 

   192 stream.

   193 @param aMaxLength The maximum number of bytes to be written.

   194 @param aStatus The request status that indicates the completion status of this 

   195 asynchronous request.

   196 @return The maximum number of bytes to be written, as used in this request. 

   197 This can be different to the value supplied in aMaxLength; this is dependent 

   198 on the implementation. */

   199 	{return aHost.DoWriteL(aDes,aMaxLength,aStatus,*this);}

   200 inline TStreamTransfer TStreamMark::WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TStreamTransfer aTransfer)

   201 /** Writes data into the shared stream from the specified data source.

   202 

   203 @param aHost The object that manages shared streaming.

   204 @param anOutput The data source for the write operation.

   205 @param aTransfer Defines the amount of data to be pulled from the output stream 

   206 object.

   207 @return A stream transfer object defining the amount of data that was not consumed. */

   208 	{return aHost.DoWriteL(anOutput,aTransfer,*this);}

   209 inline TInt TStreamMark::WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TInt aMaxLength)

   210 /** Writes data into the shared stream from the specified data source

   211 

   212 @param aHost The object that manages shared streaming.

   213 @param anOutput The data source for the write operation.

   214 @param aMaxLength The maximum amount of data available to be written.

   215 @return The amount of data that was not consumed. */

   216 	{return aMaxLength-aHost.DoWriteL(anOutput,TStreamTransfer(aMaxLength),*this).Left();}

   217 inline void TStreamMark::WriteL(TStreamExchange& aHost,MStreamOutput& anOutput)

   218 /** Writes data into the shared stream from the specified data source.

   219 

   220 No explicit limit is placed on the amount of data that can be written.

   221 

   222 @param aHost The object that manages shared streaming.

   223 @param anOutput The data source for the write operation. */

   224 	{aHost.DoWriteL(anOutput,KStreamUnlimited,*this);}

   225 inline void TStreamMark::SeekL(TStreamExchange& aHost,TStreamPos aPos)

   226 	{aHost.DoSeekL(*this,EStreamBeginning,aPos.Offset());}

   227 inline TStreamPos TStreamMark::SeekL(TStreamExchange& aHost,TStreamLocation aLocation,TInt anOffset)

   228 /** Moves the position of the mark in the host stream.

   229 

   230 The new position is calculated by adding the specified offset to one of:

   231 

   232 the position of the beginning of the host stream

   233 

   234 the position of the end of the host stream

   235 

   236 the position of the current mark.

   237 

   238 @param aHost The object that manages shared streaming.

   239 @param aLocation The location in the host stream on which the calculation of 

   240 the new position is based.

   241 @param anOffset The offset value.

   242 @return The new position of the mark. */

   243 	{return aHost.DoSeekL(*this,aLocation,anOffset);}

   244 inline TStreamPos TStreamMark::SeekL(TStreamExchange& aHost,TInt anOffset)

   245 /** Moves the position of the mark in the host stream.

   246 

   247 @param aHost The object that manages shared streaming.

   248 @param anOffset The amount by which the position of the mark is to be moved 

   249 relative to the existing position of the mark.

   250 @return The new position of the mark. */

   251 	{return aHost.DoSeekL(*this,EStreamMark,anOffset);}

   252 inline TStreamPos TStreamMark::TellL(TStreamExchange& aHost) const

   253 /** Gets the position of the mark within the host stream.

   254 

   255 @param aHost The object that manages shared streaming.

   256 @return The stream position. */

   257 	{return aHost.DoSeekL(CONST_CAST(TStreamMark&,*this),EStreamMark,0);}

   258 

   259 // Class TStreamExchange

   260 inline TStreamExchange::TStreamExchange()

   261 	: iHost(NULL),iRMrk(NULL),iWMrk(NULL)

   262 /** Constructs an empty object.

   263 

   264 Call Share() to prepare for access to a shared stream buffer. */

   265 	{}

   266 inline TStreamExchange::TStreamExchange(MStreamBuf* aHost)

   267 	: iHost(aHost),iRMrk(NULL),iWMrk(NULL)

   268 /** Constructs the object, specifying the stream buffer that will act as the shared 

   269 host.

   270 

   271 @param aHost A pointer to a stream buffer that will act as the shared host. */

   272 	{}

   273 inline void TStreamExchange::Share(MStreamBuf* aHost)

   274 /** Tells the object to use the specified stream buffer that will act as the shared 

   275 host.

   276 

   277 @param aHost A pointer to a stream buffer that will act as the shared host. */

   278 	{iHost=aHost;}

   279 inline TBool TStreamExchange::IsActive() const

   280 /** Tests whether this object is using a stream buffer that is acting as shared 

   281 host.

   282 

   283 @return True, if this object is using a shared host ; false, otherwise. */

   284 	{return iHost!=NULL;}

   285 	

   286 // Class RShareBuf

   287 inline void RShareBuf::Open(TStreamExchange& aHost,TInt aMode)

   288 /** Prepares the shared stream buffer for streaming.

   289 

   290 The function sets the read mark and/or the write mark to the beginning of 

   291 the host stream.

   292 

   293 @param aHost The object that manages shared streaming.

   294 @param aMode The streaming mode. This can be read and/or write, as indicated 

   295 by the ERead and EWrite bits.

   296 @see MStreamBuf::TRead

   297 @see MStreamBuf::TWrite

   298 @see KStreamBeginning */

   299 	{Open(aHost,KStreamBeginning,aMode);}

   300 

   301 // Class RShareWriteStream

   302 inline RShareWriteStream::RShareWriteStream(const MExternalizer<TStreamRef>& anExter)

   303 	: RWriteStream(anExter)

   304 	{}