1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/obexobjects.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,342 @@
1.4 +// Copyright (c) 2003-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 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +
1.20 +
1.21 +/**
1.22 + @file
1.23 + @publishedAll
1.24 + @released
1.25 +*/
1.26 +
1.27 +#ifndef __OBEXOBJECTS_H
1.28 +#define __OBEXOBJECTS_H
1.29 +
1.30 +#include <obextypes.h>
1.31 +#include <obexbaseobject.h>
1.32 +#include <f32file.h>
1.33 +
1.34 +class MObexFileWriter;
1.35 +class TObexBufferingDetails;
1.36 +
1.37 +/**
1.38 +This class is a concrete derivation of the CObexBaseObject class. Use it to
1.39 +store and transfer OBEX objects with the body part stored in an EPOC file.
1.40 +Hence this class is particularly suited to OBEX "file" beaming applications
1.41 +(c.f. arbitrary object beaming), although there is in reality no
1.42 +restriction in what it is used to transfer. Access to the body is acheived
1.43 +through an additional attribute to the object; the data file. This is the
1.44 +file-system name of the file used to store the body of the object. Note
1.45 +that there is no explicit relation between this and the Name of the object,
1.46 +although it is expected that most applications would attempt to relate the
1.47 +two.
1.48 +
1.49 +When ever a valid data file is set (i.e. DataFile().Length > 0), this file
1.50 +is effectively open, hence stopping any other application from opening it
1.51 +with exclusive rights. Therefore, it is recommended that Reset () be called
1.52 +on the object as soon as it is no longer required, and definitely before
1.53 +(conceptually) passing ownership of the data file to any other object or
1.54 +user.
1.55 +
1.56 +CObexFileObject is also suited to situations where an object is expected to
1.57 +be received, but no information about the purpose of this object is known.
1.58 +This is due to CObexFileObject’s ability to create temporary files "on the
1.59 +fly" to store received data into, when a specific file is not provided by
1.60 +the application.
1.61 +
1.62 +This class is not designed for user derivation.
1.63 +
1.64 +@publishedAll
1.65 +@released
1.66 +*/
1.67 +NONSHARABLE_CLASS(CObexFileObject) : public CObexBaseObject
1.68 + {
1.69 +public:
1.70 + static IMPORT_C CObexFileObject* NewL();
1.71 + static IMPORT_C CObexFileObject* NewL(const TDesC &aDataFile);
1.72 + virtual IMPORT_C ~CObexFileObject();
1.73 + IMPORT_C void InitFromFileL(const TDesC& aFile);
1.74 +
1.75 +private:
1.76 + void ConstructL(const TDesC &aDataFile);
1.77 + void SetDataFileL(const TDesC& aDesc);
1.78 + const TDesC& DataFile();
1.79 + TBool RenameFile(const TDesC& aDesC);
1.80 + void SetTempFilePath(const TDesC& aPath);
1.81 + void QueryTempFilePath(TDes& aPath);
1.82 + // From CObexBaseObject
1.83 + virtual void GetData(TInt aPos, TDes8& aDes);
1.84 + virtual void NewData(TInt aPos, TDes8& aDes);
1.85 + virtual TInt DataSize();
1.86 + virtual void ResetData();
1.87 +// Data
1.88 +private:
1.89 + RFs iFs;
1.90 + TParse iDataFile;
1.91 + RFile iFile;
1.92 + TBuf<KObexObjectDescriptionSize> iTempFilePath;
1.93 + };
1.94 +
1.95 +
1.96 +
1.97 +/**
1.98 +Use this class to hold objects where the body part is stored in a CBufFlat
1.99 +object. Please note that although parameters are supplied as CBufBase objects,
1.100 +non-CBufFlat parameters are not supported and will have unpredictable results.
1.101 +At no point does the CObexBufObject create, or take ownership of any CBaseBuf
1.102 +object it uses - it is always the responsibility of the creator/owner of the
1.103 +CBaseBuf to free it when no longer required.
1.104 +
1.105 +As this class does not take ownership of the buffers it uses, it equally can
1.106 +not create its own buffers ad-hoc for storing new data into. Hence at no
1.107 +time is it valid for a CObexBufObject to exist with out it having a valid
1.108 +data buffer set. If such a situation arises, where it is required that
1.109 +received information should be discarded, consider using a CObexNullObject.
1.110 +
1.111 +It is also posible to supply a file instead of a memory buffer, or to supply
1.112 +both. This functionality is due to the MObexServerNotify class expecting to
1.113 +work only on CObexBufObjects, so CObexFileObjects cannot be returned from the
1.114 +upcalls.
1.115 +To use a file for body storage, call NewL() passing in a NULL pointer, then
1.116 +call SetDataBufL() manually afterwards. There are three overloads---to allow
1.117 +purely memory based objects, purely file based, or a hybrid. The hybrid object
1.118 +buffers into a memory buffer (which is not allowed to grow), then writes data
1.119 +to the file when the buffer is full. The buffering behaviour can therefore be
1.120 +tuned to the application by setting the size of the buffer prior to use.
1.121 +
1.122 +This class is not designed for user derivation.
1.123 +
1.124 +@publishedAll
1.125 +@released
1.126 +*/
1.127 +NONSHARABLE_CLASS(CObexBufObject) : public CObexBaseObject
1.128 + {
1.129 +public:
1.130 + /**
1.131 + Obex file buffering method.
1.132 +
1.133 + @publishedAll
1.134 + @released
1.135 + */
1.136 + enum TFileBuffering
1.137 + {
1.138 + /** Only the supplied buffer will be used to buffer file writes. */
1.139 + ESingleBuffering,
1.140 + /** The object will create a second buffer and perform double buffering. */
1.141 + EDoubleBuffering
1.142 + };
1.143 +
1.144 +public:
1.145 + static IMPORT_C CObexBufObject* NewL(CBufBase* aDataBuf);
1.146 + virtual IMPORT_C ~CObexBufObject();
1.147 + IMPORT_C TInt WriteToFile(const TPtrC& aFileName);
1.148 +
1.149 + IMPORT_C void SetDataBufL(TObexBufferingDetails& aDetails);
1.150 + IMPORT_C void SetDataBufL(CBufBase* aDataBuf);
1.151 + IMPORT_C void SetDataBufL(const TPtrC& aFilename);
1.152 + IMPORT_C void SetDataBufL(const TPtrC& aFilename, CBufBase* aDataBuf);
1.153 + IMPORT_C void SetDataBufL(const TPtrC& aFilename, CBufBase& aDataBuf, const TFileBuffering aBufferingStrategy);
1.154 + IMPORT_C CBufBase* DataBuf();
1.155 + HBufC* FileName();
1.156 +
1.157 +private:
1.158 + CObexBufObject();
1.159 + void ConstructL(CBufBase* aDataBuf);
1.160 +
1.161 + void PrepareToSetBufferL();
1.162 +
1.163 + void CopyFileL(const TDesC& aFilename);
1.164 + TInt NewFileData(TInt aPos, TDes8& aDes);
1.165 + void GetFileData(TInt aPos, TDes8& aDes);
1.166 +
1.167 + // From CObexBaseObject
1.168 + virtual void GetData(TInt aPos, TDes8& aDes);
1.169 + virtual void NewData(TInt aPos, TDes8& aDes);
1.170 + virtual TInt DataSize();
1.171 + virtual void ResetData();
1.172 +
1.173 + void CloseDataFile();
1.174 + TInt OpenDataFile(const TDesC& aFilename);
1.175 + void CloseFileServer();
1.176 + TInt OpenFileServer();
1.177 + TInt WriteBufferToFile(TBool aFinal);
1.178 +
1.179 +// Data
1.180 +private:
1.181 + CBufBase* iBuf;
1.182 + HBufC* iFilename;
1.183 + RFs* iFileServ;
1.184 + RFile* iFile;
1.185 + TInt iBufOffset;
1.186 + TInt iBuffered;
1.187 + TInt iBufSegSize;
1.188 +
1.189 +// Added for double-buffering
1.190 +private:
1.191 + // Owned
1.192 + MObexFileWriter* iWriter;
1.193 + CBufBase* iDoubleBuf;
1.194 + };
1.195 +
1.196 +
1.197 +
1.198 +/**
1.199 +Wraps parameters which can affect the buffering method used by the
1.200 +CObexBufObject.
1.201 +This version provides a single memory buffer which holds the entire object.
1.202 +Subclasses will always use a memory buffer, but can override the way that
1.203 +Obex uses it.
1.204 +
1.205 +@publishedAll
1.206 +@released
1.207 +*/
1.208 +NONSHARABLE_CLASS(TObexBufferingDetails)
1.209 + {
1.210 +public:
1.211 + /**
1.212 + Versions (subclasses) of the buffering style object.
1.213 + @internalComponent
1.214 + */
1.215 + enum TVersion
1.216 + {
1.217 + EBasicBuffer,
1.218 + EPureFile,
1.219 + EFilenameBackedBuffer,
1.220 + ERFileBackedBuffer,
1.221 + ELastVersion
1.222 + };
1.223 +
1.224 + IMPORT_C TObexBufferingDetails(CBufBase& aBuffer);
1.225 +
1.226 + TVersion Version(); // Return the version of this object
1.227 + CBufBase* Buffer();
1.228 +
1.229 +protected:
1.230 + TObexBufferingDetails(TVersion aVersion, CBufBase* aBuffer);
1.231 +
1.232 +private:
1.233 + TVersion iVersion;
1.234 + CBufBase* iBuffer;
1.235 +
1.236 + // This data padding has been added to help prevent future binary compatibility breaks
1.237 + // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used
1.238 + TUint32 iPadding1;
1.239 + TUint32 iPadding2;
1.240 + };
1.241 +
1.242 +
1.243 +/**
1.244 +Provides alternate behaviour for a CObexBufObject, allowing use of a file
1.245 +to hold the object in its entirety. No memory buffer is used. This is a
1.246 +special case option provided to cater for the MObexServerNotify interface
1.247 +which requires the use of CObexBufObject objects. It is generally better to
1.248 +use a buffered variant.
1.249 +
1.250 +@publishedAll
1.251 +@released
1.252 +*/
1.253 +NONSHARABLE_CLASS(TObexPureFileBuffer) : public TObexBufferingDetails
1.254 + {
1.255 +public:
1.256 + IMPORT_C TObexPureFileBuffer(const TPtrC& aFilename);
1.257 + const TPtrC& Filename();
1.258 +
1.259 +private:
1.260 + const TPtrC& iFilename;
1.261 +
1.262 + // This data padding has been added to help prevent future binary compatibility breaks
1.263 + // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used
1.264 + TUint32 iPadding1;
1.265 + TUint32 iPadding2;
1.266 + };
1.267 +
1.268 +/**
1.269 +Provides alternate behaviour for a CObexBufObject, allowing use of a file
1.270 +to hold the object in its entirety. Writes to this object are buffered through
1.271 +the supplied CBufBase derived object, which is never enlarged. Once
1.272 +it is full, the data is flushed to the file.
1.273 +
1.274 +@publishedAll
1.275 +@released
1.276 +*/
1.277 +NONSHARABLE_CLASS(TObexFilenameBackedBuffer) : public TObexBufferingDetails
1.278 + {
1.279 +public:
1.280 + IMPORT_C TObexFilenameBackedBuffer(CBufBase& aBuffer, const TPtrC& aFilename, CObexBufObject::TFileBuffering aBufferingStrategy);
1.281 + const TPtrC& Filename();
1.282 + CObexBufObject::TFileBuffering Strategy();
1.283 +
1.284 +private:
1.285 + const TPtrC& iFilename;
1.286 + CObexBufObject::TFileBuffering iBufferingStrategy;
1.287 +
1.288 + // This data padding has been added to help prevent future binary compatibility breaks
1.289 + // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used
1.290 + TUint32 iPadding1;
1.291 + TUint32 iPadding2;
1.292 + };
1.293 +
1.294 +
1.295 +
1.296 +/**
1.297 +Provides alternate behaviour for a CObexBufObject, allowing use of a file
1.298 +to hold the object in its entirety. Writes to this object are buffered through
1.299 +the supplied CBufBase derived object, which is never enlarged. Once
1.300 +it is full, the data is flushed to the file.
1.301 +
1.302 +@publishedAll
1.303 +@released
1.304 +*/
1.305 +NONSHARABLE_CLASS(TObexRFileBackedBuffer) : public TObexBufferingDetails
1.306 + {
1.307 +public:
1.308 + IMPORT_C TObexRFileBackedBuffer(CBufBase& aBuffer, RFile aFile, CObexBufObject::TFileBuffering aBufferingStrategy);
1.309 + RFile File();
1.310 + CObexBufObject::TFileBuffering Strategy();
1.311 +
1.312 +private:
1.313 + RFile iFile;
1.314 + CObexBufObject::TFileBuffering iBufferingStrategy;
1.315 +
1.316 + // This data padding has been added to help prevent future binary compatibility breaks
1.317 + // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used
1.318 + TUint32 iPadding1;
1.319 + TUint32 iPadding2;
1.320 + };
1.321 +
1.322 +
1.323 +
1.324 +/**
1.325 +Concrete OBEX object with NULL data representation. Use when only the
1.326 +headers of an object are required, and the data (if any) can safely be
1.327 +discarded.
1.328 +
1.329 +@publishedAll
1.330 +@released
1.331 +*/
1.332 +NONSHARABLE_CLASS(CObexNullObject) : public CObexBaseObject
1.333 + {
1.334 +public:
1.335 + IMPORT_C static CObexNullObject* NewL ();
1.336 +private:
1.337 + // From CObexBaseObject
1.338 + void ConstructL();
1.339 + virtual void GetData (TInt aPos, TDes8& aDes);
1.340 + virtual void NewData (TInt aPos, TDes8& aDes);
1.341 + virtual TInt DataSize ();
1.342 + virtual void ResetData ();
1.343 + };
1.344 +
1.345 +#endif // __OBEXOBJECTS_H