1.1 --- a/epoc32/include/s32share.inl Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/s32share.inl Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,304 @@
1.4 -s32share.inl
1.5 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +// Class TStreamMark
1.21 +inline TStreamMark::TStreamMark()
1.22 + : iPos(KStreamBeginning-1)
1.23 +/** Constructs a default shared stream mark object.
1.24 +
1.25 +The position for the mark is uninitialised.
1.26 +
1.27 +An uninitialised mark means that a call to IsEmpty() returns true.
1.28 +
1.29 +@see IsEmpty() */
1.30 + {}
1.31 +inline TStreamMark::TStreamMark(TStreamPos aPos)
1.32 + : iPos(aPos)
1.33 +/** Constructs the shared stream mark object, setting the mark to the specified
1.34 +stream position.
1.35 +
1.36 +An initialised mark means that a call to IsEmpty() returns false.
1.37 +
1.38 +@param aPos The stream position
1.39 +@see IsEmpty() */
1.40 + {
1.41 +#if defined (_DEBUG)
1.42 + __DbgChkPos(aPos);
1.43 +#endif
1.44 + }
1.45 +inline TStreamMark& TStreamMark::operator=(TStreamPos aPos)
1.46 +/** Assigns the specified stream position value to this shared stream mark object.
1.47 +
1.48 +@param aPos The stream position value to be assigned.
1.49 +@return A reference to this shared stream mark object. */
1.50 + {
1.51 +#if defined (_DEBUG)
1.52 + __DbgChkPos(aPos);
1.53 +#endif
1.54 + iPos=aPos;
1.55 + return *this;
1.56 + }
1.57 +inline TStreamMark::operator TStreamMark*()
1.58 + {return this;}
1.59 +inline TStreamMark::operator const TStreamMark*() const
1.60 + {return this;}
1.61 +inline TBool TStreamMark::operator==(const TStreamMark& aMark) const
1.62 +/** Tests whether this object and the specified referenced shared stream mark object
1.63 +are the same object.
1.64 +
1.65 +@param aMark A reference to a shared stream mark object.
1.66 +@return True, if the two objects are the same object; false, otherwise. */
1.67 + {return this==&aMark;}
1.68 +inline TBool TStreamMark::operator==(const TStreamMark* aPtr) const
1.69 + {return this==aPtr;}
1.70 +inline TBool TStreamMark::operator!=(const TStreamMark& aMark) const
1.71 +/** Tests whether this object and the specified shared stream mark object are different
1.72 +objects.
1.73 +
1.74 +@param aMark A pointer to a shared stream mark object.
1.75 +@return True, if the two objects are different objects; false, otherwise. */
1.76 + {return this!=&aMark;}
1.77 +inline TBool TStreamMark::operator!=(const TStreamMark* aPtr) const
1.78 + {return this!=aPtr;}
1.79 +inline TBool TStreamMark::IsEmpty() const
1.80 +/** Tests whether this mark object is uninitialised.
1.81 +
1.82 +@return True, if this mark object is uninitialised; false, otherwise. */
1.83 + {return iPos<KStreamBeginning;}
1.84 +inline void TStreamMark::Clear()
1.85 +/** Resets the mark object to its default state.
1.86 +
1.87 +On return from this function, the mark is uninitialised and a call to IsEmpty()
1.88 +returns true.
1.89 +
1.90 +Empties the object/makes it empty so that IsEmpty() returns false */
1.91 + {iPos=KStreamBeginning-1;}
1.92 +inline TStreamPos TStreamMark::Position() const
1.93 +/** Gets the position of the mark.
1.94 +
1.95 +@return The stream position. */
1.96 + {
1.97 +#if defined (_DEBUG)
1.98 + __DbgChkPos(iPos);
1.99 +#endif
1.100 + return iPos;
1.101 + }
1.102 +inline TBool TStreamMark::IsWith(TStreamExchange& aHost) const
1.103 +/** Tests whether the specified shared streaming manager currently refers to this
1.104 +mark object.
1.105 +
1.106 +@param aHost The object that manages shared streaming.
1.107 +@return True, if the shared stream manager refers to this mark; false, otherwise. */
1.108 + {return aHost.RefersTo(*this);}
1.109 +inline TBool TStreamMark::RelatesTo(TStreamExchange& aHost) const
1.110 +/** Tests whether the specified shared streaming manager currently refers to this
1.111 +mark object OR whether this mark object is initialised.
1.112 +
1.113 +@param aHost The object that manages shared streaming.
1.114 +@return True, if the shared stream manager refers to this mark OR if this mark
1.115 +object is initialised; false, otherwise.
1.116 +@see IsWith()
1.117 +@see TStreamExchange::IsActive() */
1.118 + {return iPos>=KStreamBeginning||aHost.RefersTo(*this);}
1.119 +inline void TStreamMark::Withdraw(TStreamExchange& aHost)
1.120 +/** Instructs the shared streaming manager to remove any reference it has to this
1.121 +mark object.
1.122 +
1.123 +@param aHost The object that manages shared streaming. */
1.124 + {aHost.Drop(*this);}
1.125 +inline void TStreamMark::ExtractL(TStreamExchange& aHost)
1.126 +/** Refreshes this mark from the mark in the host stream buffer and tells the shared
1.127 +streaming manager to drop any reference it has to to this mark object.
1.128 +
1.129 +@param aHost The object that manages shared streaming. */
1.130 + {aHost.GetL(*this);}
1.131 +inline TInt TStreamMark::ReadL(TStreamExchange& aHost,TAny* aPtr,TInt aMaxLength)
1.132 +/** Reads data from the shared stream into the specified memory location.
1.133 +
1.134 +@param aHost The object that manages shared streaming.
1.135 +@param aPtr A pointer to the target memory location for the data read from
1.136 +the shared stream.
1.137 +@param aMaxLength The maximum number of bytes to be read.
1.138 +@return The number of bytes read. */
1.139 + {return aHost.DoReadL(aPtr,aMaxLength,*this);}
1.140 +inline TInt TStreamMark::ReadL(TStreamExchange& aHost,TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
1.141 +/** Reads data, asynchronously, from the shared stream into the specified descriptor.
1.142 +
1.143 +If the function leaves, then no read request will have been initiated.
1.144 +
1.145 +@param aHost The object that manages shared streaming.
1.146 +@param aDes The target descriptor for the data read from the shared stream.
1.147 +@param aMaxLength The maximum number of bytes to be read.
1.148 +@param aStatus The request status that indicates the completion status of this
1.149 +asynchronous request.
1.150 +@return The maximum number of bytes to be read, as used in this request. This
1.151 +can be different to the value supplied in aMaxLength; this is dependent on
1.152 +the implementation of the underlying stream. */
1.153 + {return aHost.DoReadL(aDes,aMaxLength,aStatus,*this);}
1.154 +inline TStreamTransfer TStreamMark::ReadL(TStreamExchange& aHost,MStreamInput& anInput,TStreamTransfer aTransfer)
1.155 +/** Reads data from the shared stream into the specified data sink.
1.156 +
1.157 +@param aHost The object that manages shared streaming.
1.158 +@param anInput The sink which is the target for the read operation.
1.159 +@param aTransfer Defines the amount of data available to be read from the shared
1.160 +stream.
1.161 +@return The amount of data that was not consumed. */
1.162 + {return aHost.DoReadL(anInput,aTransfer,*this);}
1.163 +inline TInt TStreamMark::ReadL(TStreamExchange& aHost,MStreamInput& anInput,TInt aMaxLength)
1.164 +/** Reads data from the shared stream into the specified data sink.
1.165 +
1.166 +@param aHost The object that manages shared streaming.
1.167 +@param anInput The sink which is the target for the read operation.
1.168 +@param aMaxLength The maximum amount of data available to be read from the
1.169 +shared stream.
1.170 +@return The amount of data that was not consumed. */
1.171 + {return aMaxLength-aHost.DoReadL(anInput,TStreamTransfer(aMaxLength),*this).Left();}
1.172 +inline void TStreamMark::ReadL(TStreamExchange& aHost,MStreamInput& anInput)
1.173 +/** Reads data from the shared stream into the specified data sink.
1.174 +
1.175 +No explicit limit is placed on the amount of data that can be read.
1.176 +
1.177 +@param aHost The object that manages shared streaming.
1.178 +@param anInput The sink which is the target for the read operation. */
1.179 + {aHost.DoReadL(anInput,KStreamUnlimited,*this);}
1.180 +inline void TStreamMark::WriteL(TStreamExchange& aHost,const TAny* aPtr,TInt aLength)
1.181 +/** Writes data from the specified memory location into the shared stream.
1.182 +
1.183 +@param aHost The object that manages shared streaming.
1.184 +@param aPtr A pointer to the memory location from which data is to be written
1.185 +to the shared stream.
1.186 +@param aLength The number of bytes to be written. */
1.187 + {aHost.DoWriteL(aPtr,aLength,*this);}
1.188 +inline TInt TStreamMark::WriteL(TStreamExchange& aHost,const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
1.189 +/** Writes data, asynchronously, from the specified descriptor into the shared
1.190 +stream.
1.191 +
1.192 +If the function leaves, then no write request will have been initiated.
1.193 +
1.194 +@param aHost The object that manages shared streaming.
1.195 +@param aDes The source descriptor for the data to be written into the shared
1.196 +stream.
1.197 +@param aMaxLength The maximum number of bytes to be written.
1.198 +@param aStatus The request status that indicates the completion status of this
1.199 +asynchronous request.
1.200 +@return The maximum number of bytes to be written, as used in this request.
1.201 +This can be different to the value supplied in aMaxLength; this is dependent
1.202 +on the implementation. */
1.203 + {return aHost.DoWriteL(aDes,aMaxLength,aStatus,*this);}
1.204 +inline TStreamTransfer TStreamMark::WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TStreamTransfer aTransfer)
1.205 +/** Writes data into the shared stream from the specified data source.
1.206 +
1.207 +@param aHost The object that manages shared streaming.
1.208 +@param anOutput The data source for the write operation.
1.209 +@param aTransfer Defines the amount of data to be pulled from the output stream
1.210 +object.
1.211 +@return A stream transfer object defining the amount of data that was not consumed. */
1.212 + {return aHost.DoWriteL(anOutput,aTransfer,*this);}
1.213 +inline TInt TStreamMark::WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TInt aMaxLength)
1.214 +/** Writes data into the shared stream from the specified data source
1.215 +
1.216 +@param aHost The object that manages shared streaming.
1.217 +@param anOutput The data source for the write operation.
1.218 +@param aMaxLength The maximum amount of data available to be written.
1.219 +@return The amount of data that was not consumed. */
1.220 + {return aMaxLength-aHost.DoWriteL(anOutput,TStreamTransfer(aMaxLength),*this).Left();}
1.221 +inline void TStreamMark::WriteL(TStreamExchange& aHost,MStreamOutput& anOutput)
1.222 +/** Writes data into the shared stream from the specified data source.
1.223 +
1.224 +No explicit limit is placed on the amount of data that can be written.
1.225 +
1.226 +@param aHost The object that manages shared streaming.
1.227 +@param anOutput The data source for the write operation. */
1.228 + {aHost.DoWriteL(anOutput,KStreamUnlimited,*this);}
1.229 +inline void TStreamMark::SeekL(TStreamExchange& aHost,TStreamPos aPos)
1.230 + {aHost.DoSeekL(*this,EStreamBeginning,aPos.Offset());}
1.231 +inline TStreamPos TStreamMark::SeekL(TStreamExchange& aHost,TStreamLocation aLocation,TInt anOffset)
1.232 +/** Moves the position of the mark in the host stream.
1.233 +
1.234 +The new position is calculated by adding the specified offset to one of:
1.235 +
1.236 +the position of the beginning of the host stream
1.237 +
1.238 +the position of the end of the host stream
1.239 +
1.240 +the position of the current mark.
1.241 +
1.242 +@param aHost The object that manages shared streaming.
1.243 +@param aLocation The location in the host stream on which the calculation of
1.244 +the new position is based.
1.245 +@param anOffset The offset value.
1.246 +@return The new position of the mark. */
1.247 + {return aHost.DoSeekL(*this,aLocation,anOffset);}
1.248 +inline TStreamPos TStreamMark::SeekL(TStreamExchange& aHost,TInt anOffset)
1.249 +/** Moves the position of the mark in the host stream.
1.250 +
1.251 +@param aHost The object that manages shared streaming.
1.252 +@param anOffset The amount by which the position of the mark is to be moved
1.253 +relative to the existing position of the mark.
1.254 +@return The new position of the mark. */
1.255 + {return aHost.DoSeekL(*this,EStreamMark,anOffset);}
1.256 +inline TStreamPos TStreamMark::TellL(TStreamExchange& aHost) const
1.257 +/** Gets the position of the mark within the host stream.
1.258 +
1.259 +@param aHost The object that manages shared streaming.
1.260 +@return The stream position. */
1.261 + {return aHost.DoSeekL(CONST_CAST(TStreamMark&,*this),EStreamMark,0);}
1.262 +
1.263 +// Class TStreamExchange
1.264 +inline TStreamExchange::TStreamExchange()
1.265 + : iHost(NULL),iRMrk(NULL),iWMrk(NULL)
1.266 +/** Constructs an empty object.
1.267 +
1.268 +Call Share() to prepare for access to a shared stream buffer. */
1.269 + {}
1.270 +inline TStreamExchange::TStreamExchange(MStreamBuf* aHost)
1.271 + : iHost(aHost),iRMrk(NULL),iWMrk(NULL)
1.272 +/** Constructs the object, specifying the stream buffer that will act as the shared
1.273 +host.
1.274 +
1.275 +@param aHost A pointer to a stream buffer that will act as the shared host. */
1.276 + {}
1.277 +inline void TStreamExchange::Share(MStreamBuf* aHost)
1.278 +/** Tells the object to use the specified stream buffer that will act as the shared
1.279 +host.
1.280 +
1.281 +@param aHost A pointer to a stream buffer that will act as the shared host. */
1.282 + {iHost=aHost;}
1.283 +inline TBool TStreamExchange::IsActive() const
1.284 +/** Tests whether this object is using a stream buffer that is acting as shared
1.285 +host.
1.286 +
1.287 +@return True, if this object is using a shared host ; false, otherwise. */
1.288 + {return iHost!=NULL;}
1.289 +
1.290 +// Class RShareBuf
1.291 +inline void RShareBuf::Open(TStreamExchange& aHost,TInt aMode)
1.292 +/** Prepares the shared stream buffer for streaming.
1.293 +
1.294 +The function sets the read mark and/or the write mark to the beginning of
1.295 +the host stream.
1.296 +
1.297 +@param aHost The object that manages shared streaming.
1.298 +@param aMode The streaming mode. This can be read and/or write, as indicated
1.299 +by the ERead and EWrite bits.
1.300 +@see MStreamBuf::TRead
1.301 +@see MStreamBuf::TWrite
1.302 +@see KStreamBeginning */
1.303 + {Open(aHost,KStreamBeginning,aMode);}
1.304 +
1.305 +// Class RShareWriteStream
1.306 +inline RShareWriteStream::RShareWriteStream(const MExternalizer<TStreamRef>& anExter)
1.307 + : RWriteStream(anExter)
1.308 + {}