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