williamr@2: /*
williamr@2: * Copyright (c) 2003-2006 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /** 
williamr@2: @file
williamr@2: 
williamr@2: @publishedPartner
williamr@2: @released
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef __CAFVIRTUALPATH_H__
williamr@2: #define __CAFVIRTUALPATH_H__
williamr@2: 
williamr@2: #include <e32base.h>
williamr@2: 
williamr@2: #include <caf/virtualpathptr.h>
williamr@2: 
williamr@2: class RReadStream;
williamr@2: class RWriteStream;
williamr@2: 
williamr@2: namespace ContentAccess
williamr@2: 	{
williamr@2: 	class TVirtualPathPtr;
williamr@2: 
williamr@2: 	/**  A virtual path describes the location of the file (URI) and the location of
williamr@2: 	a content object within that file (Unique Id). 
williamr@2: 	
williamr@2: 	The URI must conform to the standard defined in RFC2396, found at http://www.ietf.org/.
williamr@2: 	
williamr@2: 	CVirtualPath makes a copy of the URI and UniqueId used to identify a particular content
williamr@2: 	object within a file.
williamr@2: 
williamr@2: 	The TVirtualPathPtr cast operator allows the CVirtualPath object to be used with 
williamr@2: 	CAF functions requiring a TVirtualPathPtr.
williamr@2: 
williamr@2: 	The GetCombinedUriUniqueId() function allows it to "flatten" a virtual 
williamr@2: 	path into a single URI. The combined virtual path will be the URI concatenated with the UniqueId
williamr@2: 	seperated by the KCafVirtualPathSeparator character taking the format. 
williamr@2: 	@code
williamr@2: 		<URI><KCafVirtualPathSeparator><UniqueID>
williamr@2: 	@endcode
williamr@2: 	
williamr@2: 	An example of this format is shown below:		
williamr@2: 	@code
williamr@2: 	// Create a CVirtualPath object to point to OBJECT1 inside file.dcf
williamr@2: 	CVirtualPath *path = CVirtualPath::NewL(_L("C:\\directory\file.dcf"), _L("OBJECT1"));
williamr@2: 
williamr@2: 	// convert the URI and unique ID into a single URI.
williamr@2: 	TVirtualPathPtr aPath = path->GetCombinedUriUniqueId();
williamr@2: 	@endcode
williamr@2: 	@note
williamr@2: 	If a URI is supplied which contains multiple KCafVirtualPathSeparator characters 
williamr@2: 	the rightmost KCafVirtualPathSeparator character will be taken as marking the end
williamr@2: 	of the URI and the start of the UniqueId. When multiple KCafVirtualPathSeparator
williamr@2: 	characters are present, under certain situations this will result in an invalid 
williamr@2: 	URI and UniqueId being created for the virtual path and can lead to an undefined failure.
williamr@2: 
williamr@2: 	@publishedPartner
williamr@2: 	@released
williamr@2: 	*/
williamr@2: 	class CVirtualPath : public CBase
williamr@2: 		{
williamr@2: 	public:
williamr@2: 		/** Create a CVirtualPath object from a TVirtualPathPtr 
williamr@2: 		@param aPtr The location of the content object
williamr@2: 		@return a new CVirtualPath object
williamr@2: 		*/
williamr@2: 		IMPORT_C static CVirtualPath* NewL(const TVirtualPathPtr& aPtr);
williamr@2: 
williamr@2: 		/** Create a virtual path object from a combined Uri and UniqueId 
williamr@2: 		
williamr@2: 		This constructs a CVirtual path from a single descriptor. 
williamr@2: 		
williamr@2: 		Note that the descriptor here may be just a URI or it could be a URI
williamr@2: 		concatenated with the file's UniqueId. If it is a concatenated URI and 
williamr@2: 		UniqueId the URI and UniqueId will be seperated by the KCasfVirtualPathSeparator character.
williamr@2: 		For more information see above.
williamr@2: 		@param aCombinedUriUniqueId The location of the content object
williamr@2: 		@return a new CVirtualPath object
williamr@2: 		*/
williamr@2: 		IMPORT_C static CVirtualPath* NewL(const TDesC& aCombinedUriUniqueId);
williamr@2: 
williamr@2: 		/** Create a virtual path object for a specific content object within a file 
williamr@2: 		@param aURI The location of the file
williamr@2: 		@param aUniqueId The location of the content within the file
williamr@2: 		@return a new CVirtualPath object
williamr@2: 		*/
williamr@2: 		IMPORT_C static CVirtualPath* NewL(const TDesC& aURI, const TDesC& aUniqueId);
williamr@2: 		
williamr@2: 		/** Construct and read a CVirtualPath object from a stream 
williamr@2: 		@param aStream The stream to read frin
williamr@2: 		*/
williamr@2: 		IMPORT_C static CVirtualPath* NewL(RReadStream& aStream);
williamr@2: 
williamr@2: 
williamr@2: 		virtual ~CVirtualPath();
williamr@2: 
williamr@2: 		/** The location of the file containing the content object 
williamr@2: 		@return The location of the file
williamr@2: 		*/
williamr@2: 		IMPORT_C const TDesC& URI() const;
williamr@2: 
williamr@2: 		/** UniqueId supplied by a CAF Agent to identify the object within the 
williamr@2: 		file.  
williamr@2: 		@return The uniqueId of the object within the file
williamr@2: 		*/
williamr@2: 		IMPORT_C const TDesC& UniqueId() const;
williamr@2: 		
williamr@2: 		/** Allows the class to write itself to a stream 
williamr@2: 		@param aStream	The stream to write to
williamr@2: 		*/
williamr@2: 		IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
williamr@2: 		
williamr@2: 		/** Convert the CVirtualPath to a single URI representing a particular 
williamr@2: 		content object. The URI and UniqueId will be separated by a KCafVirtualPathSeparator()
williamr@2: 		@return A descriptor contaning the URI and UniqueId concatenated together
williamr@2: 		*/
williamr@2: 		IMPORT_C const TDesC& GetCombinedUriUniqueId();
williamr@2: 
williamr@2: 		/** Cast operator allowing the CVirtualPath to be used as a TVirtualPathPtr 
williamr@2: 		@return a TVirtualPathPtr with the same value as this object
williamr@2: 		*/
williamr@2: 		inline operator const TVirtualPathPtr& () const;
williamr@2: 
williamr@2: 	private:
williamr@2: 		CVirtualPath(const TVirtualPathPtr& aPtr);	
williamr@2: 
williamr@2: 		/** Allow derived classes to call 2nd phase constructor
williamr@2: 		*/
williamr@2: 		void ConstructL();
williamr@2: 
williamr@2: 		/** Used to continue initialisation and setup iCombinedPtr */
williamr@2: 		void CreateCombinedUriUniqueIdL(const TDesC& aUri, const TDesC& aUniqueId);
williamr@2: 
williamr@2: 		void InternalizeL(RReadStream& aStream);
williamr@2: 
williamr@2: 	private:
williamr@2: 				
williamr@2: 		HBufC* iURI;
williamr@2: 		HBufC* iUniqueId;
williamr@2: 		HBufC* iCombinedUriUniqueId;
williamr@2: 		TPtrC iCombinedUriUniqueIdPtr;
williamr@2: 		TVirtualPathPtr iVirtualPathPtr;
williamr@2: 		};
williamr@2: 		
williamr@2: 
williamr@2: 	// Cast operator for treating a CVirtualPath as a TVirtualPathPtr
williamr@2: 	inline CVirtualPath::operator const TVirtualPathPtr& () const
williamr@2: 			{
williamr@2: 			return iVirtualPathPtr;
williamr@2: 			}
williamr@2: 	}
williamr@2: 
williamr@2: #endif