1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedAll

    19  @released

    20 */

    21 

    22 #ifndef __OBEXOBJECTS_H

    23 #define __OBEXOBJECTS_H

    24 

    25 #include <obextypes.h>

    26 #include <obexbaseobject.h>

    27 #include <f32file.h>

    28 

    29 class MObexFileWriter;

    30 class TObexBufferingDetails;

    31 

    32 /**

    33 This class is a concrete derivation of the CObexBaseObject class. Use it to 

    34 store and transfer OBEX objects with the body part stored in an EPOC file. 

    35 Hence this class is particularly suited to OBEX "file" beaming applications 

    36 (c.f. arbitrary object beaming), although there is in reality no 

    37 restriction in what it is used to transfer. Access to the body is acheived 

    38 through an additional attribute to the object; the data file. This is the 

    39 file-system name of the file used to store the body of the object. Note 

    40 that there is no explicit relation between this and the Name of the object, 

    41 although it is expected that most applications would attempt to relate the 

    42 two.

    43 

    44 When ever a valid data file is set (i.e. DataFile().Length > 0), this file 

    45 is effectively open, hence stopping any other application from opening it 

    46 with exclusive rights. Therefore, it is recommended that Reset () be called 

    47 on the object as soon as it is no longer required, and definitely before 

    48 (conceptually) passing ownership of the data file to any other object or 

    49 user.

    50 

    51 CObexFileObject is also suited to situations where an object is expected to 

    52 be received, but no information about the purpose of this object is known. 

    53 This is due to CObexFileObject’s ability to create temporary files "on the 

    54 fly" to store received data into, when a specific file is not provided by 

    55 the application.

    56 

    57 This class is not designed for user derivation.

    58 

    59 @publishedAll

    60 @released

    61 */

    62 NONSHARABLE_CLASS(CObexFileObject) : public CObexBaseObject

    63 	{

    64 public:

    65 	static IMPORT_C CObexFileObject* NewL();

    66 	static IMPORT_C CObexFileObject* NewL(const TDesC &aDataFile);

    67 	virtual IMPORT_C ~CObexFileObject();

    68 	IMPORT_C void InitFromFileL(const TDesC& aFile);

    69 

    70 private:

    71 	void ConstructL(const TDesC &aDataFile);

    72 	void SetDataFileL(const TDesC& aDesc);

    73 	const TDesC& DataFile();

    74 	TBool RenameFile(const TDesC& aDesC);

    75 	void SetTempFilePath(const TDesC& aPath);

    76 	void QueryTempFilePath(TDes& aPath);

    77 	// From CObexBaseObject

    78 	virtual void GetData(TInt aPos, TDes8& aDes);

    79 	virtual void NewData(TInt aPos, TDes8& aDes);

    80 	virtual TInt DataSize();

    81 	virtual void ResetData();

    82 // Data

    83 private:

    84 	RFs iFs;

    85 	TParse iDataFile;

    86 	RFile iFile;

    87 	TBuf<KObexObjectDescriptionSize> iTempFilePath;

    88 	};

    89 

    90 

    91 

    92 /**

    93 Use this class to hold objects where the body part is stored in a CBufFlat

    94 object. Please note that although parameters are supplied as CBufBase objects,

    95 non-CBufFlat parameters are not supported and will have unpredictable results.

    96 At no point does the CObexBufObject create, or take ownership of any CBaseBuf

    97 object it uses - it is always the responsibility of the creator/owner of the

    98 CBaseBuf to free it when no longer required.

    99 

   100 As this class does not take ownership of the buffers it uses, it equally can

   101 not create its own buffers ad-hoc for storing new data into. Hence at no 

   102 time is it valid for a CObexBufObject to exist with out it having a valid 

   103 data buffer set. If such a situation arises, where it is required that 

   104 received information should be discarded, consider using a CObexNullObject.

   105 

   106 It is also posible to supply a file instead of a memory buffer, or to supply

   107 both.  This functionality is due to the MObexServerNotify class expecting to

   108 work only on CObexBufObjects, so CObexFileObjects cannot be returned from the

   109 upcalls.

   110 To use a file for body storage, call NewL() passing in a NULL pointer, then

   111 call SetDataBufL() manually afterwards.  There are three overloads---to allow

   112 purely memory based objects, purely file based, or a hybrid.  The hybrid object

   113 buffers into a memory buffer (which is not allowed to grow), then writes data

   114 to the file when the buffer is full.  The buffering behaviour can therefore be

   115 tuned to the application by setting the size of the buffer prior to use.

   116 

   117 This class is not designed for user derivation.

   118 

   119 @publishedAll

   120 @released

   121 */

   122 NONSHARABLE_CLASS(CObexBufObject) : public CObexBaseObject

   123 	{

   124 public:

   125 	/**

   126 	Obex file buffering method.

   127 	

   128 	@publishedAll

   129 	@released

   130 	*/

   131 	enum TFileBuffering

   132 		{

   133 		/** Only the supplied buffer will be used to buffer file writes. */

   134 		ESingleBuffering,

   135 		/** The object will create a second buffer and perform double buffering. */

   136 		EDoubleBuffering

   137 		};

   138 

   139 public:

   140 	static IMPORT_C CObexBufObject* NewL(CBufBase* aDataBuf);

   141 	virtual IMPORT_C ~CObexBufObject();

   142 	IMPORT_C TInt WriteToFile(const TPtrC& aFileName);

   143 	

   144 	IMPORT_C void SetDataBufL(TObexBufferingDetails& aDetails);

   145 	IMPORT_C void SetDataBufL(CBufBase* aDataBuf);

   146 	IMPORT_C void SetDataBufL(const TPtrC& aFilename);

   147 	IMPORT_C void SetDataBufL(const TPtrC& aFilename, CBufBase* aDataBuf);

   148 	IMPORT_C void SetDataBufL(const TPtrC& aFilename, CBufBase& aDataBuf, const TFileBuffering aBufferingStrategy);

   149 	IMPORT_C CBufBase* DataBuf();

   150 	HBufC* FileName();

   151 

   152 private:

   153 	CObexBufObject();

   154 	void ConstructL(CBufBase* aDataBuf);

   155 	

   156 	void PrepareToSetBufferL();

   157 

   158 	void CopyFileL(const TDesC& aFilename);

   159 	TInt NewFileData(TInt aPos, TDes8& aDes);

   160 	void GetFileData(TInt aPos, TDes8& aDes);

   161 

   162 	// From CObexBaseObject

   163 	virtual void GetData(TInt aPos, TDes8& aDes);

   164 	virtual void NewData(TInt aPos, TDes8& aDes);

   165 	virtual TInt DataSize();

   166 	virtual void ResetData();

   167 

   168 	void CloseDataFile();

   169 	TInt OpenDataFile(const TDesC& aFilename);

   170 	void CloseFileServer();

   171 	TInt OpenFileServer();

   172 	TInt WriteBufferToFile(TBool aFinal);

   173 

   174 // Data

   175 private:

   176 	CBufBase* iBuf;

   177 	HBufC* iFilename;

   178 	RFs* iFileServ;

   179 	RFile* iFile;

   180 	TInt iBufOffset;

   181 	TInt iBuffered;

   182 	TInt iBufSegSize;

   183 

   184 // Added for double-buffering

   185 private:

   186 	// Owned

   187 	MObexFileWriter*	iWriter;

   188 	CBufBase*			iDoubleBuf;

   189 	};

   190 

   191 

   192 

   193 /**

   194 Wraps parameters which can affect the buffering method used by the

   195 CObexBufObject.

   196 This version provides a single memory buffer which holds the entire object.

   197 Subclasses will always use a memory buffer, but can override the way that

   198 Obex uses it.

   199 

   200 @publishedAll

   201 @released

   202 */

   203 NONSHARABLE_CLASS(TObexBufferingDetails)

   204 	{

   205 public:

   206 	/**

   207 	Versions (subclasses) of the buffering style object.

   208 	This enum should not be used outside the dll.

   209 	@internalComponent

   210 	*/

   211 	enum TVersion

   212 		{

   213 		EBasicBuffer,

   214 		EPureFile,

   215 		EFilenameBackedBuffer,

   216 		ERFileBackedBuffer,

   217 		ELastVersion

   218 		};

   219 	

   220 	IMPORT_C TObexBufferingDetails(CBufBase& aBuffer);

   221 	

   222 	TVersion Version();	// Return the version of this object

   223 	CBufBase* Buffer();

   224 

   225 protected:

   226 	TObexBufferingDetails(TVersion aVersion, CBufBase* aBuffer);

   227 

   228 private:

   229 	TVersion iVersion;

   230 	CBufBase* iBuffer;

   231 

   232 	// This data padding has been added to help prevent future binary compatibility breaks	

   233 	// Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used

   234 	TUint32     iPadding1; 

   235 	TUint32     iPadding2; 	

   236 	};

   237 

   238 

   239 /**

   240 Provides alternate behaviour for a CObexBufObject, allowing use of a file

   241 to hold the object in its entirety.  No memory buffer is used.  This is a

   242 special case option provided to cater for the MObexServerNotify interface

   243 which requires the use of CObexBufObject objects.  It is generally better to

   244 use a buffered variant.

   245 

   246 @publishedAll

   247 @released

   248 */

   249 NONSHARABLE_CLASS(TObexPureFileBuffer) : public TObexBufferingDetails

   250 	{

   251 public:

   252 	IMPORT_C TObexPureFileBuffer(const TPtrC& aFilename);

   253 	const TPtrC& Filename();

   254 

   255 private:

   256 	const TPtrC& iFilename;

   257 

   258 	// This data padding has been added to help prevent future binary compatibility breaks	

   259 	// Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used

   260 	TUint32     iPadding1; 

   261 	TUint32     iPadding2; 

   262 	};

   263 

   264 /**

   265 Provides alternate behaviour for a CObexBufObject, allowing use of a file

   266 to hold the object in its entirety.  Writes to this object are buffered through

   267 the supplied CBufBase derived object, which is never enlarged.  Once

   268 it is full, the data is flushed to the file.

   269 

   270 @publishedAll

   271 @released

   272 */

   273 NONSHARABLE_CLASS(TObexFilenameBackedBuffer) : public TObexBufferingDetails

   274 	{

   275 public:

   276 	IMPORT_C TObexFilenameBackedBuffer(CBufBase& aBuffer, const TPtrC& aFilename, CObexBufObject::TFileBuffering aBufferingStrategy);

   277 	const TPtrC& Filename();

   278 	CObexBufObject::TFileBuffering Strategy();

   279 	

   280 private:

   281 	const TPtrC& iFilename;

   282 	CObexBufObject::TFileBuffering iBufferingStrategy;

   283 

   284 	// This data padding has been added to help prevent future binary compatibility breaks	

   285 	// Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used

   286 	TUint32     iPadding1; 

   287 	TUint32     iPadding2; 	

   288 	};

   289 

   290 

   291 

   292 /**

   293 Provides alternate behaviour for a CObexBufObject, allowing use of a file

   294 to hold the object in its entirety.  Writes to this object are buffered through

   295 the supplied CBufBase derived object, which is never enlarged.  Once

   296 it is full, the data is flushed to the file.

   297 

   298 @publishedAll

   299 @released

   300 */

   301 NONSHARABLE_CLASS(TObexRFileBackedBuffer) : public TObexBufferingDetails

   302 	{

   303 public:

   304 	IMPORT_C TObexRFileBackedBuffer(CBufBase& aBuffer, RFile aFile, CObexBufObject::TFileBuffering aBufferingStrategy);

   305 	RFile File();

   306 	CObexBufObject::TFileBuffering Strategy();

   307 	

   308 private:

   309 	RFile iFile;

   310 	CObexBufObject::TFileBuffering iBufferingStrategy;

   311 

   312 	// This data padding has been added to help prevent future binary compatibility breaks	

   313 	// Neither iPadding1 nor iPadding2 have been zero'd because they are currently not used

   314 	TUint32     iPadding1; 

   315 	TUint32     iPadding2; 

   316 	};

   317 

   318 

   319 

   320 /**

   321 Concrete OBEX object with NULL data representation. Use when only the 

   322 headers of an object are required, and the data (if any) can safely be 

   323 discarded.

   324 

   325 @publishedAll

   326 @released

   327 */

   328 NONSHARABLE_CLASS(CObexNullObject) : public CObexBaseObject

   329 	{

   330 public:

   331 	IMPORT_C static CObexNullObject* NewL ();

   332 private:

   333 	// From CObexBaseObject

   334 	void ConstructL();

   335 	virtual void GetData (TInt aPos, TDes8& aDes);

   336 	virtual void NewData (TInt aPos, TDes8& aDes);

   337 	virtual TInt DataSize ();

   338 	virtual void ResetData ();

   339 	};

   340 

   341 #endif // __OBEXOBJECTS_H