1.1 --- a/epoc32/include/s32mem.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/s32mem.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,9 +1,9 @@
1.4 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 // All rights reserved.
1.6 // This component and the accompanying materials are made available
1.7 -// 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.8 +// under the terms of "Eclipse Public License v1.0"
1.9 // which accompanies this distribution, and is available
1.10 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.12 //
1.13 // Initial Contributors:
1.14 // Nokia Corporation - initial contribution.
1.15 @@ -23,17 +23,17 @@
1.16 #endif
1.17
1.18 /**
1.19 - * @publishedAll
1.20 + * @publishedAll
1.21 * @released
1.22 * A stream buffer that uses plain memory for its implementation.
1.23
1.24 -A stream of this type is used by RMemWriteStream and RMemReadStream objects.
1.25 +A stream of this type is used by RMemWriteStream and RMemReadStream objects.
1.26 It also has intermediate buffering capabilities.
1.27
1.28 This is a seekable stream buffer.
1.29
1.30 @see RMemWriteStream
1.31 -@see RMemReadStream
1.32 +@see RMemReadStream
1.33 */
1.34 class TMemBuf : public TStreamBuf
1.35 {
1.36 @@ -52,23 +52,23 @@
1.37 };
1.38
1.39 /**
1.40 - * @publishedAll
1.41 + * @publishedAll
1.42 * @released
1.43 * A stream buffer that uses a descriptor for its implementation.
1.44
1.45 -A stream of this type is used by RDesWriteStream and RDesReadStream objects.
1.46 +A stream of this type is used by RDesWriteStream and RDesReadStream objects.
1.47 It also has intermediate buffering capabilities.
1.48
1.49 This is a seekable stream buffer.
1.50
1.51 -When used in write mode, the length of the descriptor is only updated when
1.52 -the stream buffer's SynchL() function is called, i.e. as a result of a call
1.53 +When used in write mode, the length of the descriptor is only updated when
1.54 +the stream buffer's SynchL() function is called, i.e. as a result of a call
1.55 to RWriteStream::CommitL().
1.56
1.57 @see RDesWriteStream
1.58 @see RDesReadStream
1.59 @see RWriteStream::CommitL()
1.60 -@see MStreamBuf::SynchL()
1.61 +@see MStreamBuf::SynchL()
1.62 */
1.63 class TDesBuf : public TStreamBuf
1.64 {
1.65 @@ -89,11 +89,11 @@
1.66 };
1.67
1.68 /**
1.69 - * @publishedAll
1.70 + * @publishedAll
1.71 * @released
1.72 * A stream buffer that uses a dynamic buffer for its implementation.
1.73
1.74 -A stream of this type is used by RBufWriteStream and RBufReadStream objects.
1.75 +A stream of this type is used by RBufWriteStream and RBufReadStream objects.
1.76 It also has intermediate buffering capabilities.
1.77
1.78 This is a seekable stream buffer.
1.79 @@ -102,23 +102,23 @@
1.80
1.81 insert mode - inserts new data into the buffer at the offset passed to Set()
1.82
1.83 -overwrite mode - replaces the data in the buffer starting at the offset passed
1.84 -to Set(). Once the end of the buffer is reached, it is automatically extended
1.85 +overwrite mode - replaces the data in the buffer starting at the offset passed
1.86 +to Set(). Once the end of the buffer is reached, it is automatically extended
1.87 as more data is written. This is the default mode.
1.88
1.89 -truncate mode - truncates the buffer to the offset passed to Set() before
1.90 -data is written, extending the buffer. When writing, the buffer size as reported
1.91 -by CBufBase::Size() may be larger than the data written to the stream. To
1.92 -synchronise the buffer's reported size with the stream, call the MStreamBuf::SynchL()
1.93 +truncate mode - truncates the buffer to the offset passed to Set() before
1.94 +data is written, extending the buffer. When writing, the buffer size as reported
1.95 +by CBufBase::Size() may be larger than the data written to the stream. To
1.96 +synchronise the buffer's reported size with the stream, call the MStreamBuf::SynchL()
1.97 function.
1.98
1.99 -Note that this object never takes ownership of the dynamic buffer, the CBufBase
1.100 +Note that this object never takes ownership of the dynamic buffer, the CBufBase
1.101 type object.
1.102
1.103 @see RBufWriteStream
1.104 @see RBufReadStream
1.105 @see CBufBase::Size()
1.106 -@see MStreamBuf::SynchL()
1.107 +@see MStreamBuf::SynchL()
1.108 */
1.109 class TBufBuf : public TStreamBuf
1.110 {
1.111 @@ -155,17 +155,22 @@
1.112 };
1.113
1.114 /**
1.115 -@publishedAll
1.116 +@publishedAll
1.117 @released
1.118
1.119 Supports the reading of a stream from a pointer of any type.
1.120
1.121 @see TMemBuf
1.122 -@see RReadStream
1.123 +@see RReadStream
1.124 */
1.125 class RMemReadStream : public RReadStream
1.126 {
1.127 public:
1.128 +/**
1.129 +Constructs an empty object.
1.130 +
1.131 +Call Open() to prepare the stream for reading.
1.132 +*/
1.133 RMemReadStream() {}
1.134 IMPORT_C RMemReadStream(const TAny* aPtr,TInt aLength);
1.135 IMPORT_C void Open(const TAny* aPtr,TInt aLength);
1.136 @@ -174,17 +179,22 @@
1.137 };
1.138
1.139 /**
1.140 -@publishedAll
1.141 +@publishedAll
1.142 @released
1.143
1.144 Supports the writing of a stream to a pointer of any type.
1.145
1.146 @see TMemBuf
1.147 -@see RWriteStream
1.148 +@see RWriteStream
1.149 */
1.150 class RMemWriteStream : public RWriteStream
1.151 {
1.152 public:
1.153 +/**
1.154 +Constructs an empty write stream object.
1.155 +
1.156 +Call Open() to prepare a stream for writing.
1.157 +*/
1.158 RMemWriteStream() {}
1.159 inline RMemWriteStream(const MExternalizer<TStreamRef>& anExter);
1.160 IMPORT_C RMemWriteStream(TAny* aPtr,TInt aMaxLength);
1.161 @@ -194,17 +204,22 @@
1.162 };
1.163
1.164 /**
1.165 -@publishedAll
1.166 +@publishedAll
1.167 @released
1.168
1.169 Supports the reading of a stream from an 8-bit descriptor.
1.170
1.171 @see TMemBuf
1.172 -@see RReadStream
1.173 +@see RReadStream
1.174 */
1.175 class RDesReadStream : public RReadStream
1.176 {
1.177 public:
1.178 +/**
1.179 +Constructs an empty read stream object.
1.180 +
1.181 +Call Open() to prepare the stream for reading.
1.182 +*/
1.183 RDesReadStream() {}
1.184 IMPORT_C RDesReadStream(const TDesC8& aDes);
1.185 IMPORT_C void Open(const TDesC8& aDes);
1.186 @@ -213,17 +228,22 @@
1.187 };
1.188
1.189 /**
1.190 -@publishedAll
1.191 +@publishedAll
1.192 @released
1.193
1.194 -Supports the writing of a stream to an 8-bit descriptor.
1.195 +Supports the writing of a stream to a stream buffer hosted by an 8-bit descriptor.
1.196
1.197 @see TDesBuf
1.198 -@see RWriteStream
1.199 +@see RWriteStream
1.200 */
1.201 class RDesWriteStream : public RWriteStream
1.202 {
1.203 public:
1.204 +/**
1.205 +Constructs an empty write stream object.
1.206 +
1.207 +Call Open() to prepare a stream for writing.
1.208 +*/
1.209 RDesWriteStream() {}
1.210 inline RDesWriteStream(const MExternalizer<TStreamRef>& anExter);
1.211 IMPORT_C RDesWriteStream(TDes8& aDes);
1.212 @@ -233,17 +253,25 @@
1.213 };
1.214
1.215 /**
1.216 -@publishedAll
1.217 +@publishedAll
1.218 @released
1.219
1.220 -Supports the reading of a stream from a dynamic buffer.
1.221 +Supports the opening of an existing stream hosted by a dynamic buffer.
1.222 +The stream does not take ownership of the dynamic buffer, which means
1.223 +that the creator is responsible for deleting the buffer when it is no
1.224 +longer needed.
1.225
1.226 @see TBufBuf
1.227 -@see RReadStream
1.228 +@see RReadStream
1.229 */
1.230 class RBufReadStream : public RReadStream
1.231 {
1.232 public:
1.233 +/**
1.234 +Constructs an empty read stream object.
1.235 +
1.236 +Call Open() to prepare the stream for reading.
1.237 +*/
1.238 RBufReadStream() {}
1.239 IMPORT_C RBufReadStream(const CBufBase& aBuf,TInt aPos=0);
1.240 IMPORT_C void Open(const CBufBase& aBuf,TInt aPos=0);
1.241 @@ -252,18 +280,26 @@
1.242 };
1.243
1.244 /**
1.245 -@publishedAll
1.246 +@publishedAll
1.247 @released
1.248
1.249 -Supports the writing of a stream to a dynamic buffer.
1.250 +Supports the writing of a stream to a dynamic buffer. The stream does
1.251 +not take ownership of the dynamic buffer, which means that the creator
1.252 +is responsible for deleting the buffer when it is no longer needed.
1.253
1.254 @see TBufBuf
1.255 -@see RWriteStream
1.256 +@see RWriteStream
1.257 */
1.258 class RBufWriteStream : public RWriteStream
1.259 {
1.260 public:
1.261 +/**
1.262 +Default constructor. Constructs an empty write stream object.
1.263 +
1.264 +Call Open(), Truncate() or Insert() to prepare a stream for writing.
1.265 +*/
1.266 RBufWriteStream() {}
1.267 +
1.268 inline RBufWriteStream(const MExternalizer<TStreamRef>& anExter);
1.269 IMPORT_C RBufWriteStream(CBufBase& aBuf,TInt aPos=0);
1.270 IMPORT_C void Open(CBufBase& aBuf,TInt aPos=0);
1.271 @@ -275,21 +311,21 @@
1.272 };
1.273
1.274 /**
1.275 - * @publishedAll
1.276 + * @publishedAll
1.277 * @released
1.278 - * In-memory non-persistent store. The buffer store does not have a root stream
1.279 + * In-memory non-persistent store. The buffer store does not have a root stream
1.280 and cannot be closed without losing all the data.
1.281
1.282 -It implements many of the operations defined by the store abstract framework.
1.283 -Specifically, streams in this store can be: overwritten, replaced, appended,
1.284 -deleted, and created in advance of being written to. However the class does
1.285 +It implements many of the operations defined by the store abstract framework.
1.286 +Specifically, streams in this store can be: overwritten, replaced, appended,
1.287 +deleted, and created in advance of being written to. However the class does
1.288 not support commit and revert operations.
1.289
1.290 -Overwriting an existing stream can result in a shorter stream; however, a
1.291 -stream cannot be extended beyond its original length. Replacing a stream can
1.292 -result in a stream which is longer or shorter than the original. The order
1.293 -in which streams are written to a memory store is not important as streams
1.294 -can be changed and rewritten.
1.295 +Overwriting an existing stream can result in a shorter stream; however, a
1.296 +stream cannot be extended beyond its original length. Replacing a stream can
1.297 +result in a stream which is longer or shorter than the original. The order
1.298 +in which streams are written to a memory store is not important as streams
1.299 +can be changed and rewritten.
1.300 */
1.301 class CBufStore : public CStreamStore
1.302 {
1.303 @@ -310,7 +346,7 @@
1.304 private:
1.305 CArrayFixFlat<CBufSeg*> iBufArray;
1.306 TInt iExpandSize;
1.307 - };
1.308 + };
1.309
1.310 #include <s32mem.inl>
1.311 #endif