1.1 --- a/epoc32/include/s32buf.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/s32buf.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,511 @@
1.4 -s32buf.h
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 +#if !defined(__S32BUF_H__)
1.21 +#define __S32BUF_H__
1.22 +#if !defined(__E32STD_H__)
1.23 +#include <e32std.h>
1.24 +#endif
1.25 +
1.26 +/** Defines the type of location within a stream on which the calculation
1.27 +of a new seek position is based.
1.28 +
1.29 +The type is used by the stream buffer SeekL() functions.
1.30 +
1.31 +@see MStreamBuf::SeekL() */
1.32 +enum TStreamLocation
1.33 + /** The seek position is calculated relative to the beginning of the
1.34 + stream.*/
1.35 + {EStreamBeginning,
1.36 + /** The seek position is calculated relative to the end of the stream.*/
1.37 + EStreamMark,
1.38 + /** The seek position is calculated relative to the existing read or
1.39 + write mark in the stream. */
1.40 + EStreamEnd};
1.41 +
1.42 +/**
1.43 + * @publishedAll
1.44 + * @released
1.45 + * Holds the position of the read or write mark within a seekable stream.
1.46 +
1.47 +Position is the offset from the beginning of a seekable stream. The class
1.48 +provides convenient operators for performing arithmetic on the offset value
1.49 +and for doing comparisons between stream position objects.
1.50 +
1.51 +It can be considered as an absolute stream position.
1.52 +
1.53 +Objects of this type are usually created as a result of calling
1.54 +MStreamBuf::SeekL() or MStreamBuf::TellL(); they allow a program to remember
1.55 +the current read position in a stream buffer and reset it to the same
1.56 +location later.
1.57 +
1.58 +@see MStreamBuf::SeekL()
1.59 +@see MStreamBuf::TellL()
1.60 +*/
1.61 +class TStreamPos
1.62 + {
1.63 +public:
1.64 + /** Constructs an empty stream position object. */
1.65 + TStreamPos() {}
1.66 + inline TStreamPos(TInt anOffset);
1.67 +//
1.68 + inline TBool operator==(TStreamPos aPos) const;
1.69 + inline TBool operator!=(TStreamPos aPos) const;
1.70 + inline TBool operator<(TStreamPos aPos) const;
1.71 + inline TBool operator<=(TStreamPos aPos) const;
1.72 + inline TBool operator>(TStreamPos aPos) const;
1.73 + inline TBool operator>=(TStreamPos aPos) const;
1.74 +//
1.75 + inline TInt operator-(TStreamPos aPos) const;
1.76 + inline TStreamPos operator+(TInt anOffset) const;
1.77 + inline TStreamPos operator-(TInt anOffset) const;
1.78 +//
1.79 + inline TStreamPos& operator+=(TInt anOffset);
1.80 + inline TStreamPos& operator-=(TInt anOffset);
1.81 +//
1.82 + inline TInt Offset() const;
1.83 +private:
1.84 + TInt iOff;
1.85 + };
1.86 +inline TStreamPos operator+(TInt anOffset,TStreamPos aPos);
1.87 +#if defined(__NO_CLASS_CONSTS__)
1.88 +/** Constructs a TStreamPos object that denotes the beginning of any seekable
1.89 +stream.
1.90 +
1.91 +@see TStreamPos */
1.92 +#define KStreamBeginning TStreamPos(0)
1.93 +#else
1.94 +const TStreamPos KStreamBeginning=TStreamPos(0);
1.95 +#endif
1.96 +
1.97 +/**
1.98 + * @publishedAll
1.99 + * @released
1.100 + * Stream transfer object.
1.101 +
1.102 +Holds and maintains a value that represents how much data is to be transferred,
1.103 +or remains to be transferred, between streams.
1.104 +
1.105 +Objects of this type are used by ReadL() and WriteL() functions of MStreamBuf.
1.106 +
1.107 +@see MStreamBuf
1.108 +@see TStreamBuf
1.109 +@see TStreamMark
1.110 +@see TStreamExchange
1.111 +@see RShareBuf
1.112 +*/
1.113 +class TStreamTransfer
1.114 + {
1.115 +public:
1.116 + /** An enumerator type passed to a constructor of this class to indicate
1.117 + that there is no explicit limit to the amount of data that can be
1.118 + transferred between streams. The enumeration is not used. */
1.119 + enum TUnlimited {EUnlimited};
1.120 +public:
1.121 + /** Constructs a stream transfer object specifying that there is no
1.122 + explicit limit to the amount of data that can be transferred between
1.123 + streams.
1.124 +
1.125 + The amount of data to be transferred is only limited by the streams
1.126 + themselves.
1.127 +
1.128 + The arithmetical operators do not change the state of an unlimited stream
1.129 + transfer object. */
1.130 + TStreamTransfer() {}
1.131 + inline TStreamTransfer(TInt aMaxLength);
1.132 + inline TStreamTransfer(TUnlimited);
1.133 +//
1.134 + inline TBool operator==(TInt aLength) const;
1.135 + inline TBool operator>(TInt aLength) const;
1.136 + inline TStreamTransfer operator-(TInt aLength) const;
1.137 + inline TInt operator[](TInt aMaxLength) const;
1.138 +//
1.139 + inline TStreamTransfer& operator-=(TInt aLength);
1.140 +//
1.141 + inline TInt Left() const;
1.142 +private:
1.143 + TInt iVal;
1.144 +private:
1.145 + IMPORT_C static void __DbgChkNonNegative(TInt aLength);
1.146 + };
1.147 +inline TBool operator==(TInt aLength,TStreamTransfer aTransfer);
1.148 +inline TBool operator<(TInt aLength,TStreamTransfer aTransfer);
1.149 +#if defined(__NO_CLASS_CONSTS__)
1.150 +/** Constructs a TStreamTransfer object indicating that no explicit limit is
1.151 +imposed on transfers between streams.
1.152 +
1.153 +@see TStreamTransfer
1.154 +@see MStreamBuf::ReadL()
1.155 +@see MStreamBuf::WriteL() */
1.156 +#define KStreamUnlimited TStreamTransfer(TStreamTransfer::EUnlimited)
1.157 +#else
1.158 +const TStreamTransfer KStreamUnlimited=TStreamTransfer::EUnlimited;
1.159 +#endif
1.160 +//
1.161 +class MStreamInput;
1.162 +class MStreamOutput;
1.163 +
1.164 +/**
1.165 + * @publishedAll
1.166 + * @released
1.167 + * A stream buffer that provides a generic I/O interface for streamed data.
1.168 +
1.169 +A stream buffer:
1.170 +
1.171 +may be buffered or unbuffered
1.172 +
1.173 +may provide read-only, write-only or read/write capability
1.174 +
1.175 +may be seekable, or unseekable.
1.176 +
1.177 +A seekable stream buffer maintains independent read and write pointers, which
1.178 +can be manipulated separately. This is unlike the RFile interface which
1.179 +maintains a single current position in the file. For example, file streams
1.180 +and memory streams are seekable streams, but socket, serial-comms, and filtered
1.181 +streams are not.
1.182 +
1.183 +Objects of this type are used by the stream interface classes derived from
1.184 +RReadStream and RWriteStream.
1.185 +
1.186 +The class has no member data.
1.187 +
1.188 +Derive from this class, if the stream has no intermediate buffering
1.189 +capabilities, otherwise derive from TStreamBuf.
1.190 +
1.191 +Get a reference to the stream buffer used by a read stream by calling
1.192 +RReadStream::Source(). Get a reference to the stream buffer used by a write
1.193 +stream by calling RWriteStream::Sink()
1.194 +
1.195 +@see RReadStream
1.196 +@see RWriteStream
1.197 +@see TStreamBuf
1.198 +*/
1.199 +class MStreamBuf
1.200 + {
1.201 +public:
1.202 + /** Indicates that an operation applies to the read mark in a stream or to
1.203 + the read area in an stream buffer. */
1.204 + enum TRead {ERead=0x01};
1.205 +
1.206 + /** Indicates that an operation applies to the write mark in a stream or
1.207 + to the write area in an stream buffer. */
1.208 + enum TWrite {EWrite=0x02};
1.209 +
1.210 + /** Used to identify the type of mark in a stream.
1.211 +
1.212 + The type is used by functions of this class and derived classes that perform
1.213 + seek operations to marks within a stream.
1.214 +
1.215 + The type uses the ERead and EWrite enumeration values, as bit flags, to
1.216 + identify the read and write marks respectively.
1.217 +
1.218 + ERead is an MStreamBuf::TRead enumerator. EWrite is an MStreamBuf::EWrite
1.219 + enumerator.
1.220 +
1.221 + @see MStreamBuf::TRead
1.222 + @see MStreamBuf::TWrite */
1.223 + typedef TInt TMark;
1.224 +public:
1.225 + IMPORT_C void Close();
1.226 + inline void Release();
1.227 + IMPORT_C TInt Synch();
1.228 + inline void SynchL();
1.229 +//
1.230 + IMPORT_C void PushL();
1.231 +//
1.232 + inline TInt ReadL(TAny* aPtr,TInt aMaxLength);
1.233 + IMPORT_C TInt Read(TDes8& aDes,TRequestStatus& aStatus);
1.234 + IMPORT_C TInt Read(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1.235 + IMPORT_C TInt ReadL(TDes8& aDes,TRequestStatus& aStatus);
1.236 + inline TInt ReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1.237 + inline TStreamTransfer ReadL(MStreamInput& anInput,TStreamTransfer aTransfer);
1.238 + IMPORT_C TInt ReadL(MStreamInput& anInput,TInt aMaxLength);
1.239 + inline void ReadL(MStreamInput& anInput);
1.240 +//
1.241 + inline void WriteL(const TAny* aPtr,TInt aLength);
1.242 + IMPORT_C TInt Write(const TDesC8& aDes,TRequestStatus& aStatus);
1.243 + IMPORT_C TInt Write(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1.244 + IMPORT_C TInt WriteL(const TDesC8& aDes,TRequestStatus& aStatus);
1.245 + inline TInt WriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1.246 + inline TStreamTransfer WriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer);
1.247 + IMPORT_C TInt WriteL(MStreamOutput& anOutput,TInt aMaxLength);
1.248 + inline void WriteL(MStreamOutput& anOutput);
1.249 +//
1.250 + inline void SeekL(TMark aMark,TStreamPos aPos);
1.251 + inline TStreamPos SeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset=0);
1.252 + inline TStreamPos SeekL(TRead,TStreamLocation aLocation,TInt anOffset=0);
1.253 + inline TStreamPos SeekL(TWrite,TStreamLocation aLocation,TInt anOffset=0);
1.254 + inline TStreamPos SeekL(TRead,TInt anOffset);
1.255 + inline TStreamPos SeekL(TWrite,TInt anOffset);
1.256 +//
1.257 + inline TStreamPos TellL(TRead) const;
1.258 + inline TStreamPos TellL(TWrite) const;
1.259 + inline TInt SizeL() const;
1.260 +protected:
1.261 + MStreamBuf() {}
1.262 +private:
1.263 + MStreamBuf(const MStreamBuf&);
1.264 + MStreamBuf& operator=(const MStreamBuf&);
1.265 +//
1.266 + virtual IMPORT_C void DoRelease();
1.267 + virtual IMPORT_C void DoSynchL();
1.268 + virtual IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength);
1.269 + virtual IMPORT_C TInt DoReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1.270 + virtual IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer);
1.271 + virtual IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength);
1.272 + virtual IMPORT_C TInt DoWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1.273 + virtual IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer);
1.274 + virtual IMPORT_C TStreamPos DoSeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset);
1.275 + };
1.276 +
1.277 +/**
1.278 + * @publishedAll
1.279 + * @released
1.280 + * An interface to an object that acts as a target for read operations from
1.281 +a stream. The object behaves as a generic data sink.
1.282 +
1.283 +A stream input object can act as an intelligent buffer, and is useful for
1.284 +performing filtering, compression or any other general kind of conversion
1.285 +operation that might be needed after reading from a stream.
1.286 +
1.287 +The class is pure interface and requires an implementation.
1.288 +
1.289 +@see MStreamBuf::ReadL()
1.290 +*/
1.291 +class MStreamInput
1.292 + {
1.293 +public:
1.294 + /** Reads data from an intermediate buffer into this stream input object.
1.295 +
1.296 + This function is called by the default implementation of
1.297 + TStreamBuf::DoReadL(MStreamInput&,TStreamTransfer)
1.298 + and assumes that the source is a stream buffer's intermediate buffer.
1.299 +
1.300 + @param aPtr A pointer into the intermediate buffer from which the read
1.301 + operation starts.
1.302 + @param aMaxLength The maximum amount of data to be read.
1.303 + @return The amount of data read.
1.304 + @see TStreamBuf::DoReadL()
1.305 + @see TStreamBuf */
1.306 + virtual TInt PushL(const TAny* aPtr,TInt aMaxLength)=0;
1.307 +
1.308 + /** Reads data from the specified stream into this stream input object.
1.309 +
1.310 + This function is called by the default implementation of
1.311 + MStreamBuf::DoReadL(MStreamInput&,TStreamTransfer).
1.312 + It may also be called by TStreamBuf::DoReadL(MStreamInput&,TStreamTransfer),
1.313 + depending on the amount of data to be transferred and the nature of the
1.314 + buffering scheme.
1.315 +
1.316 + @param aSource The stream from which data is to be read.
1.317 + @param aTransfer Defines the amount of data available to be read.
1.318 + @return The amount of data that was not consumed.
1.319 + @see MStreamBuf::DoReadL()
1.320 + @see TStreamBuf::DoReadL() */
1.321 + virtual TStreamTransfer ReadFromL(MStreamBuf& aSource,TStreamTransfer aTransfer)=0;
1.322 + };
1.323 +
1.324 +/**
1.325 + * @publishedAll
1.326 + * @released
1.327 + * An interface to an object that acts as source for write operations to a
1.328 +stream. The object behaves as a generic data source.
1.329 +
1.330 +A stream output object can act as an intelligent buffer, and is useful for
1.331 +performing filtering, compression or any other general kind of conversion
1.332 +operation that might be needed before writing to a stream.
1.333 +
1.334 +The class is pure interface and requires an implementation.
1.335 +
1.336 +@see MStreamBuf::WriteL()
1.337 +*/
1.338 +class MStreamOutput
1.339 + {
1.340 +public:
1.341 + /** Writes data to an intermediate buffer from this stream output object.
1.342 +
1.343 + This function is called by the default implementation of
1.344 + TStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer)
1.345 + and assumes that the target is a stream buffer's intermediate buffer.
1.346 +
1.347 + @param aPtr A pointer into the intermediate buffer where the write operation
1.348 + starts.
1.349 + @param aMaxLength The maximum amount of data to be written.
1.350 + @return The amount of data written.
1.351 + @see TStreamBuf::DoWriteL()
1.352 + @see TStreamBuf */
1.353 + virtual TInt PullL(TAny* aPtr,TInt aMaxLength)=0;
1.354 +
1.355 + /** Writes data to the specified stream from this stream output object.
1.356 +
1.357 + This function is called by the default implementation of
1.358 + MStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer).
1.359 + It may also be called by TStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer),
1.360 + depending on the amount of data to be transferred and the nature of the
1.361 + buffering scheme.
1.362 +
1.363 + @param aSink The stream to which data is to be written.
1.364 + @param aTransfer Defines the amount of data available to be written.
1.365 + @return The amount of data that was not consumed.
1.366 + @see MStreamBuf::DoWriteL()
1.367 + @see TStreamBuf::DoWriteL() */
1.368 + virtual TStreamTransfer WriteToL(MStreamBuf& aSink,TStreamTransfer aTransfer)=0;
1.369 + };
1.370 +
1.371 +/**
1.372 + * @publishedAll
1.373 + * @released
1.374 + * Adds buffering capabilities to a stream buffer
1.375 +
1.376 +The class provides pointers to mark out the current read and write areas within
1.377 +the intermediate buffer. The class also defines the pure virtual functions
1.378 +UnderflowL() and OverflowL() which must be provided by a derived class.
1.379 +
1.380 +Streams which have buffering capabilities derive from this class, otherwise
1.381 +they derive from MStreamBuf.
1.382 +
1.383 +Note that the class does not provide the buffer; this is left to the class
1.384 +derived from it. For example, the memory buffer classes use the memory area
1.385 +directly, the file buffer class allocate a heap cell to use as a buffer.
1.386 +
1.387 +@see UnderflowL()
1.388 +@see OverflowL()
1.389 +*/
1.390 +class TStreamBuf : public MStreamBuf
1.391 + {
1.392 +protected:
1.393 + /** Used to identify the type of area within an intermediate buffer.
1.394 +
1.395 + The type is used by functions of this class that set or get pointers into
1.396 + the intermediate buffer.
1.397 +
1.398 + The type uses the ERead and EWrite enumeration values, as bit flags, to
1.399 + identify the read and write areas respectively.
1.400 +
1.401 + ERead is an MStreamBuf::TRead enumerator. EWrite is an MStreamBuf::EWrite
1.402 + enumerator.
1.403 +
1.404 + @see MStreamBuf::TRead
1.405 + @see MStreamBuf::TWrite */
1.406 + typedef TInt TArea;
1.407 +protected:
1.408 + IMPORT_C TStreamBuf();
1.409 +//
1.410 + IMPORT_C void SetBuf(TArea anArea,TUint8* aPtr,TUint8* anEnd);
1.411 + IMPORT_C void SetPtr(TArea anArea,TUint8* aPtr);
1.412 + IMPORT_C void SetEnd(TArea anArea,TUint8* anEnd);
1.413 + IMPORT_C TUint8* Ptr(TArea anArea) const;
1.414 + IMPORT_C TUint8* End(TArea anArea) const;
1.415 + IMPORT_C TInt Avail(TArea anArea) const;
1.416 +//
1.417 + IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength);
1.418 + IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer);
1.419 + IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength);
1.420 + IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer);
1.421 +//
1.422 + inline void SetBuf(TRead,TUint8* aPtr,TUint8* anEnd);
1.423 + inline void SetBuf(TWrite,TUint8* aPtr,TUint8* anEnd);
1.424 + inline void SetPtr(TRead,TUint8* aPtr);
1.425 + inline void SetPtr(TWrite,TUint8* aPtr);
1.426 + inline void SetEnd(TRead,TUint8* anEnd);
1.427 + inline void SetEnd(TWrite,TUint8* anEnd);
1.428 + inline TUint8* Ptr(TRead) const;
1.429 + inline TUint8* Ptr(TWrite) const;
1.430 + inline TUint8* End(TRead) const;
1.431 + inline TUint8* End(TWrite) const;
1.432 + inline TInt Avail(TRead) const;
1.433 + inline TInt Avail(TWrite) const;
1.434 +private:
1.435 + /** Re-fills the intermediate buffer and resets the start and end points
1.436 + of the read area.
1.437 +
1.438 + The implementation of this function depends on the way the stream itself is
1.439 + implemented. For example, the in-memory streams have simple implementations.
1.440 +
1.441 + @param aMaxLength The maximum amount of data required for the intermediate
1.442 + buffer.
1.443 + @return The amount of data available in the intermediate buffer. */
1.444 + virtual TInt UnderflowL(TInt aMaxLength)=0;
1.445 +
1.446 + /** Empties the intermediate buffer and resets the start and end points
1.447 + of the write area.
1.448 +
1.449 + The implementation of this function depends on the way the stream itself is
1.450 + implemented. For example, the in-memory streams have simple implementations. */
1.451 + virtual void OverflowL()=0;
1.452 +private:
1.453 + TUint8* iRPtr;
1.454 + TUint8* iREnd;
1.455 + TUint8* iWPtr;
1.456 + TUint8* iWEnd;
1.457 + };
1.458 +
1.459 +/**
1.460 + * @publishedAll
1.461 + * @released
1.462 + * Interface to a stream filter.
1.463 +
1.464 +A stream filter is an object that allows stream data to be filtered after
1.465 +retrieval from a host or filtered before being written to a host.
1.466 +
1.467 +The class is abstract and a derived class must be defined an implemented.
1.468 +*/
1.469 +class TStreamFilter : public MStreamBuf
1.470 + {
1.471 +public:
1.472 + enum {EAttached=0x10};
1.473 +protected:
1.474 + IMPORT_C TStreamFilter();
1.475 + inline void Set(MStreamBuf* aHost,TInt aMode);
1.476 + inline void Committed();
1.477 + inline TBool IsCommitted() const;
1.478 + IMPORT_C void EmitL(const TAny* aPtr,TInt aLength);
1.479 +//
1.480 + IMPORT_C void DoRelease();
1.481 + IMPORT_C void DoSynchL();
1.482 + IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength);
1.483 + IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength);
1.484 +private:
1.485 + /** Calculates the maximum size of unfiltered data necessary to give the
1.486 + specified amount of filtered data.
1.487 +
1.488 + @param aMaxLength The amount of filtered data required.
1.489 + @return The maximum amount of unfiltered data guaranteed not to generate
1.490 + more than aMaxLength bytes of filtered output. */
1.491 + virtual TInt Capacity(TInt aMaxLength)=0;
1.492 +
1.493 + /** Performs the filtration process.
1.494 +
1.495 + @param aPtr Pointer to the output location for the filtered data.
1.496 + @param aMaxLength The maximum amount of space available for the filtered
1.497 + data.
1.498 + @param aFrom A reference to a pointer to the unfiltered data source. This
1.499 + pointer should be advanced as the source is consumed.
1.500 + @param anEnd Pointer to the first byte beyond the end of the unfiltered
1.501 + data source.
1.502 + @return The size of the filtered data. */
1.503 + virtual TInt FilterL(TAny* aPtr,TInt aMaxLength,const TUint8*& aFrom,const TUint8* anEnd)=0;
1.504 +private:
1.505 + MStreamBuf* iHost;
1.506 + TInt iMode;
1.507 +private:
1.508 + friend class TFilterInput;
1.509 + friend class TFilterOutput;
1.510 +private:
1.511 + IMPORT_C static void __DbgChkMode(TInt aMode);
1.512 + };
1.513 +
1.514 +#include <s32buf.inl>
1.515 +#endif