williamr@2: // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@4: // under the terms of "Eclipse Public License v1.0" williamr@2: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // williamr@2: williamr@2: /** williamr@2: @file williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: williamr@2: #ifndef __OBEXOBJECTS_H williamr@2: #define __OBEXOBJECTS_H williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: class MObexFileWriter; williamr@2: class TObexBufferingDetails; williamr@2: williamr@2: /** williamr@2: This class is a concrete derivation of the CObexBaseObject class. Use it to williamr@2: store and transfer OBEX objects with the body part stored in an EPOC file. williamr@2: Hence this class is particularly suited to OBEX "file" beaming applications williamr@2: (c.f. arbitrary object beaming), although there is in reality no williamr@2: restriction in what it is used to transfer. Access to the body is acheived williamr@2: through an additional attribute to the object; the data file. This is the williamr@2: file-system name of the file used to store the body of the object. Note williamr@2: that there is no explicit relation between this and the Name of the object, williamr@2: although it is expected that most applications would attempt to relate the williamr@2: two. williamr@2: williamr@2: When ever a valid data file is set (i.e. DataFile().Length > 0), this file williamr@2: is effectively open, hence stopping any other application from opening it williamr@2: with exclusive rights. Therefore, it is recommended that Reset () be called williamr@2: on the object as soon as it is no longer required, and definitely before williamr@2: (conceptually) passing ownership of the data file to any other object or williamr@2: user. williamr@2: williamr@2: CObexFileObject is also suited to situations where an object is expected to williamr@2: be received, but no information about the purpose of this object is known. williamr@2: This is due to CObexFileObject’s ability to create temporary files "on the williamr@2: fly" to store received data into, when a specific file is not provided by williamr@2: the application. williamr@2: williamr@2: This class is not designed for user derivation. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: NONSHARABLE_CLASS(CObexFileObject) : public CObexBaseObject williamr@2: { williamr@2: public: williamr@2: static IMPORT_C CObexFileObject* NewL(); williamr@2: static IMPORT_C CObexFileObject* NewL(const TDesC &aDataFile); williamr@2: virtual IMPORT_C ~CObexFileObject(); williamr@2: IMPORT_C void InitFromFileL(const TDesC& aFile); williamr@2: williamr@2: private: williamr@2: void ConstructL(const TDesC &aDataFile); williamr@2: void SetDataFileL(const TDesC& aDesc); williamr@2: const TDesC& DataFile(); williamr@2: TBool RenameFile(const TDesC& aDesC); williamr@2: void SetTempFilePath(const TDesC& aPath); williamr@2: void QueryTempFilePath(TDes& aPath); williamr@2: // From CObexBaseObject williamr@2: virtual void GetData(TInt aPos, TDes8& aDes); williamr@2: virtual void NewData(TInt aPos, TDes8& aDes); williamr@2: virtual TInt DataSize(); williamr@2: virtual void ResetData(); williamr@2: // Data williamr@2: private: williamr@2: RFs iFs; williamr@2: TParse iDataFile; williamr@2: RFile iFile; williamr@2: TBuf iTempFilePath; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: /** williamr@2: Use this class to hold objects where the body part is stored in a CBufFlat williamr@2: object. Please note that although parameters are supplied as CBufBase objects, williamr@2: non-CBufFlat parameters are not supported and will have unpredictable results. williamr@2: At no point does the CObexBufObject create, or take ownership of any CBaseBuf williamr@2: object it uses - it is always the responsibility of the creator/owner of the williamr@2: CBaseBuf to free it when no longer required. williamr@2: williamr@2: As this class does not take ownership of the buffers it uses, it equally can williamr@2: not create its own buffers ad-hoc for storing new data into. Hence at no williamr@2: time is it valid for a CObexBufObject to exist with out it having a valid williamr@2: data buffer set. If such a situation arises, where it is required that williamr@2: received information should be discarded, consider using a CObexNullObject. williamr@2: williamr@2: It is also posible to supply a file instead of a memory buffer, or to supply williamr@2: both. This functionality is due to the MObexServerNotify class expecting to williamr@2: work only on CObexBufObjects, so CObexFileObjects cannot be returned from the williamr@2: upcalls. williamr@2: To use a file for body storage, call NewL() passing in a NULL pointer, then williamr@2: call SetDataBufL() manually afterwards. There are three overloads---to allow williamr@2: purely memory based objects, purely file based, or a hybrid. The hybrid object williamr@2: buffers into a memory buffer (which is not allowed to grow), then writes data williamr@2: to the file when the buffer is full. The buffering behaviour can therefore be williamr@2: tuned to the application by setting the size of the buffer prior to use. williamr@2: williamr@2: This class is not designed for user derivation. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: NONSHARABLE_CLASS(CObexBufObject) : public CObexBaseObject williamr@2: { williamr@2: public: williamr@2: /** williamr@2: Obex file buffering method. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: enum TFileBuffering williamr@2: { williamr@2: /** Only the supplied buffer will be used to buffer file writes. */ williamr@2: ESingleBuffering, williamr@2: /** The object will create a second buffer and perform double buffering. */ williamr@2: EDoubleBuffering williamr@2: }; williamr@2: williamr@2: public: williamr@2: static IMPORT_C CObexBufObject* NewL(CBufBase* aDataBuf); williamr@2: virtual IMPORT_C ~CObexBufObject(); williamr@2: IMPORT_C TInt WriteToFile(const TPtrC& aFileName); williamr@2: williamr@2: IMPORT_C void SetDataBufL(TObexBufferingDetails& aDetails); williamr@2: IMPORT_C void SetDataBufL(CBufBase* aDataBuf); williamr@2: IMPORT_C void SetDataBufL(const TPtrC& aFilename); williamr@2: IMPORT_C void SetDataBufL(const TPtrC& aFilename, CBufBase* aDataBuf); williamr@2: IMPORT_C void SetDataBufL(const TPtrC& aFilename, CBufBase& aDataBuf, const TFileBuffering aBufferingStrategy); williamr@2: IMPORT_C CBufBase* DataBuf(); williamr@2: HBufC* FileName(); williamr@2: williamr@2: private: williamr@2: CObexBufObject(); williamr@2: void ConstructL(CBufBase* aDataBuf); williamr@2: williamr@2: void PrepareToSetBufferL(); williamr@2: williamr@2: void CopyFileL(const TDesC& aFilename); williamr@2: TInt NewFileData(TInt aPos, TDes8& aDes); williamr@2: void GetFileData(TInt aPos, TDes8& aDes); williamr@2: williamr@2: // From CObexBaseObject williamr@2: virtual void GetData(TInt aPos, TDes8& aDes); williamr@2: virtual void NewData(TInt aPos, TDes8& aDes); williamr@2: virtual TInt DataSize(); williamr@2: virtual void ResetData(); williamr@2: williamr@2: void CloseDataFile(); williamr@2: TInt OpenDataFile(const TDesC& aFilename); williamr@2: void CloseFileServer(); williamr@2: TInt OpenFileServer(); williamr@2: TInt WriteBufferToFile(TBool aFinal); williamr@2: williamr@2: // Data williamr@2: private: williamr@2: CBufBase* iBuf; williamr@2: HBufC* iFilename; williamr@2: RFs* iFileServ; williamr@2: RFile* iFile; williamr@2: TInt iBufOffset; williamr@2: TInt iBuffered; williamr@2: TInt iBufSegSize; williamr@2: williamr@2: // Added for double-buffering williamr@2: private: williamr@2: // Owned williamr@2: MObexFileWriter* iWriter; williamr@2: CBufBase* iDoubleBuf; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: /** williamr@2: Wraps parameters which can affect the buffering method used by the williamr@2: CObexBufObject. williamr@2: This version provides a single memory buffer which holds the entire object. williamr@2: Subclasses will always use a memory buffer, but can override the way that williamr@2: Obex uses it. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: NONSHARABLE_CLASS(TObexBufferingDetails) williamr@2: { williamr@2: public: williamr@2: /** williamr@2: Versions (subclasses) of the buffering style object. williamr@4: This enum should not be used outside the dll. williamr@2: @internalComponent williamr@2: */ williamr@2: enum TVersion williamr@2: { williamr@2: EBasicBuffer, williamr@2: EPureFile, williamr@2: EFilenameBackedBuffer, williamr@2: ERFileBackedBuffer, williamr@2: ELastVersion williamr@2: }; williamr@2: williamr@2: IMPORT_C TObexBufferingDetails(CBufBase& aBuffer); williamr@2: williamr@2: TVersion Version(); // Return the version of this object williamr@2: CBufBase* Buffer(); williamr@2: williamr@2: protected: williamr@2: TObexBufferingDetails(TVersion aVersion, CBufBase* aBuffer); williamr@2: williamr@2: private: williamr@2: TVersion iVersion; williamr@2: CBufBase* iBuffer; williamr@2: williamr@2: // This data padding has been added to help prevent future binary compatibility breaks williamr@2: // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used williamr@2: TUint32 iPadding1; williamr@2: TUint32 iPadding2; williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: Provides alternate behaviour for a CObexBufObject, allowing use of a file williamr@2: to hold the object in its entirety. No memory buffer is used. This is a williamr@2: special case option provided to cater for the MObexServerNotify interface williamr@2: which requires the use of CObexBufObject objects. It is generally better to williamr@2: use a buffered variant. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: NONSHARABLE_CLASS(TObexPureFileBuffer) : public TObexBufferingDetails williamr@2: { williamr@2: public: williamr@2: IMPORT_C TObexPureFileBuffer(const TPtrC& aFilename); williamr@2: const TPtrC& Filename(); williamr@2: williamr@2: private: williamr@2: const TPtrC& iFilename; williamr@2: williamr@2: // This data padding has been added to help prevent future binary compatibility breaks williamr@2: // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used williamr@2: TUint32 iPadding1; williamr@2: TUint32 iPadding2; williamr@2: }; williamr@2: williamr@2: /** williamr@2: Provides alternate behaviour for a CObexBufObject, allowing use of a file williamr@2: to hold the object in its entirety. Writes to this object are buffered through williamr@2: the supplied CBufBase derived object, which is never enlarged. Once williamr@2: it is full, the data is flushed to the file. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: NONSHARABLE_CLASS(TObexFilenameBackedBuffer) : public TObexBufferingDetails williamr@2: { williamr@2: public: williamr@2: IMPORT_C TObexFilenameBackedBuffer(CBufBase& aBuffer, const TPtrC& aFilename, CObexBufObject::TFileBuffering aBufferingStrategy); williamr@2: const TPtrC& Filename(); williamr@2: CObexBufObject::TFileBuffering Strategy(); williamr@2: williamr@2: private: williamr@2: const TPtrC& iFilename; williamr@2: CObexBufObject::TFileBuffering iBufferingStrategy; williamr@2: williamr@2: // This data padding has been added to help prevent future binary compatibility breaks williamr@2: // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used williamr@2: TUint32 iPadding1; williamr@2: TUint32 iPadding2; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: /** williamr@2: Provides alternate behaviour for a CObexBufObject, allowing use of a file williamr@2: to hold the object in its entirety. Writes to this object are buffered through williamr@2: the supplied CBufBase derived object, which is never enlarged. Once williamr@2: it is full, the data is flushed to the file. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: NONSHARABLE_CLASS(TObexRFileBackedBuffer) : public TObexBufferingDetails williamr@2: { williamr@2: public: williamr@2: IMPORT_C TObexRFileBackedBuffer(CBufBase& aBuffer, RFile aFile, CObexBufObject::TFileBuffering aBufferingStrategy); williamr@2: RFile File(); williamr@2: CObexBufObject::TFileBuffering Strategy(); williamr@2: williamr@2: private: williamr@2: RFile iFile; williamr@2: CObexBufObject::TFileBuffering iBufferingStrategy; williamr@2: williamr@2: // This data padding has been added to help prevent future binary compatibility breaks williamr@2: // Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used williamr@2: TUint32 iPadding1; williamr@2: TUint32 iPadding2; williamr@2: }; williamr@2: williamr@2: williamr@2: williamr@2: /** williamr@2: Concrete OBEX object with NULL data representation. Use when only the williamr@2: headers of an object are required, and the data (if any) can safely be williamr@2: discarded. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: NONSHARABLE_CLASS(CObexNullObject) : public CObexBaseObject williamr@2: { williamr@2: public: williamr@2: IMPORT_C static CObexNullObject* NewL (); williamr@2: private: williamr@2: // From CObexBaseObject williamr@2: void ConstructL(); williamr@2: virtual void GetData (TInt aPos, TDes8& aDes); williamr@2: virtual void NewData (TInt aPos, TDes8& aDes); williamr@2: virtual TInt DataSize (); williamr@2: virtual void ResetData (); williamr@2: }; williamr@2: williamr@2: #endif // __OBEXOBJECTS_H