// 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