1 obexobjects.h

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 

    17 

    18 /**

    19  @file

    20  @publishedAll

    21  @released

    22 */

    23 

    24 #ifndef __OBEXOBJECTS_H

    25 #define __OBEXOBJECTS_H

    26 

    27 #include <obextypes.h>

    28 #include <obexbaseobject.h>

    29 #include <f32file.h>

    30 

    31 class MObexFileWriter;

    32 class TObexBufferingDetails;

    33 

    34 /**

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

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

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

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

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

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

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

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

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

    44 two.

    45 

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

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

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

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

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

    51 user.

    52 

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

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

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

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

    57 the application.

    58 

    59 This class is not designed for user derivation.

    60 

    61 @publishedAll

    62 @released

    63 */

    64 NONSHARABLE_CLASS(CObexFileObject) : public CObexBaseObject

    65 	{

    66 public:

    67 	static IMPORT_C CObexFileObject* NewL();

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

    69 	virtual IMPORT_C ~CObexFileObject();

    70 	IMPORT_C void InitFromFileL(const TDesC& aFile);

    71 

    72 private:

    73 	void ConstructL(const TDesC &aDataFile);

    74 	void SetDataFileL(const TDesC& aDesc);

    75 	const TDesC& DataFile();

    76 	TBool RenameFile(const TDesC& aDesC);

    77 	void SetTempFilePath(const TDesC& aPath);

    78 	void QueryTempFilePath(TDes& aPath);

    79 	// From CObexBaseObject

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

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

    82 	virtual TInt DataSize();

    83 	virtual void ResetData();

    84 // Data

    85 private:

    86 	RFs iFs;

    87 	TParse iDataFile;

    88 	RFile iFile;

    89 	TBuf<KObexObjectDescriptionSize> iTempFilePath;

    90 	};

    91 

    92 

    93 

    94 /**

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

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

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

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

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

   100 CBaseBuf to free it when no longer required.

   101 

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

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

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

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

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

   107 

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

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

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

   111 upcalls.

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

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

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

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

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

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

   118 

   119 This class is not designed for user derivation.

   120 

   121 @publishedAll

   122 @released

   123 */

   124 NONSHARABLE_CLASS(CObexBufObject) : public CObexBaseObject

   125 	{

   126 public:

   127 	/**

   128 	Obex file buffering method.

   129 	

   130 	@publishedAll

   131 	@released

   132 	*/

   133 	enum TFileBuffering

   134 		{

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

   136 		ESingleBuffering,

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

   138 		EDoubleBuffering

   139 		};

   140 

   141 public:

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

   143 	virtual IMPORT_C ~CObexBufObject();

   144 	IMPORT_C TInt WriteToFile(const TPtrC& aFileName);

   145 	

   146 	IMPORT_C void SetDataBufL(TObexBufferingDetails& aDetails);

   147 	IMPORT_C void SetDataBufL(CBufBase* aDataBuf);

   148 	IMPORT_C void SetDataBufL(const TPtrC& aFilename);

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

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

   151 	IMPORT_C CBufBase* DataBuf();

   152 	HBufC* FileName();

   153 

   154 private:

   155 	CObexBufObject();

   156 	void ConstructL(CBufBase* aDataBuf);

   157 	

   158 	void PrepareToSetBufferL();

   159 

   160 	void CopyFileL(const TDesC& aFilename);

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

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

   163 

   164 	// From CObexBaseObject

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

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

   167 	virtual TInt DataSize();

   168 	virtual void ResetData();

   169 

   170 	void CloseDataFile();

   171 	TInt OpenDataFile(const TDesC& aFilename);

   172 	void CloseFileServer();

   173 	TInt OpenFileServer();

   174 	TInt WriteBufferToFile(TBool aFinal);

   175 

   176 // Data

   177 private:

   178 	CBufBase* iBuf;

   179 	HBufC* iFilename;

   180 	RFs* iFileServ;

   181 	RFile* iFile;

   182 	TInt iBufOffset;

   183 	TInt iBuffered;

   184 	TInt iBufSegSize;

   185 

   186 // Added for double-buffering

   187 private:

   188 	// Owned

   189 	MObexFileWriter*	iWriter;

   190 	CBufBase*			iDoubleBuf;

   191 	};

   192 

   193 

   194 

   195 /**

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

   197 CObexBufObject.

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

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

   200 Obex uses it.

   201 

   202 @publishedAll

   203 @released

   204 */

   205 NONSHARABLE_CLASS(TObexBufferingDetails)

   206 	{

   207 public:

   208 	/**

   209 	Versions (subclasses) of the buffering style object.

   210 	@internalComponent

   211 	*/

   212 	enum TVersion

   213 		{

   214 		EBasicBuffer,

   215 		EPureFile,

   216 		EFilenameBackedBuffer,

   217 		ERFileBackedBuffer,

   218 		ELastVersion

   219 		};

   220 	

   221 	IMPORT_C TObexBufferingDetails(CBufBase& aBuffer);

   222 	

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

   224 	CBufBase* Buffer();

   225 

   226 protected:

   227 	TObexBufferingDetails(TVersion aVersion, CBufBase* aBuffer);

   228 

   229 private:

   230 	TVersion iVersion;

   231 	CBufBase* iBuffer;

   232 

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

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

   235 	TUint32     iPadding1; 

   236 	TUint32     iPadding2; 	

   237 	};

   238 

   239 

   240 /**

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

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

   243 special case option provided to cater for the MObexServerNotify interface

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

   245 use a buffered variant.

   246 

   247 @publishedAll

   248 @released

   249 */

   250 NONSHARABLE_CLASS(TObexPureFileBuffer) : public TObexBufferingDetails

   251 	{

   252 public:

   253 	IMPORT_C TObexPureFileBuffer(const TPtrC& aFilename);

   254 	const TPtrC& Filename();

   255 

   256 private:

   257 	const TPtrC& iFilename;

   258 

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

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

   261 	TUint32     iPadding1; 

   262 	TUint32     iPadding2; 

   263 	};

   264 

   265 /**

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

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

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

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

   270 

   271 @publishedAll

   272 @released

   273 */

   274 NONSHARABLE_CLASS(TObexFilenameBackedBuffer) : public TObexBufferingDetails

   275 	{

   276 public:

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

   278 	const TPtrC& Filename();

   279 	CObexBufObject::TFileBuffering Strategy();

   280 	

   281 private:

   282 	const TPtrC& iFilename;

   283 	CObexBufObject::TFileBuffering iBufferingStrategy;

   284 

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

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

   287 	TUint32     iPadding1; 

   288 	TUint32     iPadding2; 	

   289 	};

   290 

   291 

   292 

   293 /**

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

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

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

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

   298 

   299 @publishedAll

   300 @released

   301 */

   302 NONSHARABLE_CLASS(TObexRFileBackedBuffer) : public TObexBufferingDetails

   303 	{

   304 public:

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

   306 	RFile File();

   307 	CObexBufObject::TFileBuffering Strategy();

   308 	

   309 private:

   310 	RFile iFile;

   311 	CObexBufObject::TFileBuffering iBufferingStrategy;

   312 

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

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

   315 	TUint32     iPadding1; 

   316 	TUint32     iPadding2; 

   317 	};

   318 

   319 

   320 

   321 /**

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

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

   324 discarded.

   325 

   326 @publishedAll

   327 @released

   328 */

   329 NONSHARABLE_CLASS(CObexNullObject) : public CObexBaseObject

   330 	{

   331 public:

   332 	IMPORT_C static CObexNullObject* NewL ();

   333 private:

   334 	// From CObexBaseObject

   335 	void ConstructL();

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

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

   338 	virtual TInt DataSize ();

   339 	virtual void ResetData ();

   340 	};

   341 

   342 #endif // __OBEXOBJECTS_H