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