epoc32/include/caf/virtualpath.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     1 /*
     2 * Copyright (c) 2003-2006 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of the License "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description: 
    15 *
    16 */
    17 
    18 
    19 
    20 /** 
    21 @file
    22 
    23 @publishedPartner
    24 @released
    25 */
    26 
    27 
    28 
    29 #ifndef __CAFVIRTUALPATH_H__
    30 #define __CAFVIRTUALPATH_H__
    31 
    32 #include <e32base.h>
    33 
    34 #include <caf/virtualpathptr.h>
    35 
    36 class RReadStream;
    37 class RWriteStream;
    38 
    39 namespace ContentAccess
    40 	{
    41 	class TVirtualPathPtr;
    42 
    43 	/**  A virtual path describes the location of the file (URI) and the location of
    44 	a content object within that file (Unique Id). 
    45 	
    46 	The URI must conform to the standard defined in RFC2396, found at http://www.ietf.org/.
    47 	
    48 	CVirtualPath makes a copy of the URI and UniqueId used to identify a particular content
    49 	object within a file.
    50 
    51 	The TVirtualPathPtr cast operator allows the CVirtualPath object to be used with 
    52 	CAF functions requiring a TVirtualPathPtr.
    53 
    54 	The GetCombinedUriUniqueId() function allows it to "flatten" a virtual 
    55 	path into a single URI. The combined virtual path will be the URI concatenated with the UniqueId
    56 	seperated by the KCafVirtualPathSeparator character taking the format. 
    57 	@code
    58 		<URI><KCafVirtualPathSeparator><UniqueID>
    59 	@endcode
    60 	
    61 	An example of this format is shown below:		
    62 	@code
    63 	// Create a CVirtualPath object to point to OBJECT1 inside file.dcf
    64 	CVirtualPath *path = CVirtualPath::NewL(_L("C:\\directory\file.dcf"), _L("OBJECT1"));
    65 
    66 	// convert the URI and unique ID into a single URI.
    67 	TVirtualPathPtr aPath = path->GetCombinedUriUniqueId();
    68 	@endcode
    69 	@note
    70 	If a URI is supplied which contains multiple KCafVirtualPathSeparator characters 
    71 	the rightmost KCafVirtualPathSeparator character will be taken as marking the end
    72 	of the URI and the start of the UniqueId. When multiple KCafVirtualPathSeparator
    73 	characters are present, under certain situations this will result in an invalid 
    74 	URI and UniqueId being created for the virtual path and can lead to an undefined failure.
    75 
    76 	@publishedPartner
    77 	@released
    78 	*/
    79 	class CVirtualPath : public CBase
    80 		{
    81 	public:
    82 		/** Create a CVirtualPath object from a TVirtualPathPtr 
    83 		@param aPtr The location of the content object
    84 		@return a new CVirtualPath object
    85 		*/
    86 		IMPORT_C static CVirtualPath* NewL(const TVirtualPathPtr& aPtr);
    87 
    88 		/** Create a virtual path object from a combined Uri and UniqueId 
    89 		
    90 		This constructs a CVirtual path from a single descriptor. 
    91 		
    92 		Note that the descriptor here may be just a URI or it could be a URI
    93 		concatenated with the file's UniqueId. If it is a concatenated URI and 
    94 		UniqueId the URI and UniqueId will be seperated by the KCasfVirtualPathSeparator character.
    95 		For more information see above.
    96 		@param aCombinedUriUniqueId The location of the content object
    97 		@return a new CVirtualPath object
    98 		*/
    99 		IMPORT_C static CVirtualPath* NewL(const TDesC& aCombinedUriUniqueId);
   100 
   101 		/** Create a virtual path object for a specific content object within a file 
   102 		@param aURI The location of the file
   103 		@param aUniqueId The location of the content within the file
   104 		@return a new CVirtualPath object
   105 		*/
   106 		IMPORT_C static CVirtualPath* NewL(const TDesC& aURI, const TDesC& aUniqueId);
   107 		
   108 		/** Construct and read a CVirtualPath object from a stream 
   109 		@param aStream The stream to read frin
   110 		*/
   111 		IMPORT_C static CVirtualPath* NewL(RReadStream& aStream);
   112 
   113 
   114 		virtual ~CVirtualPath();
   115 
   116 		/** The location of the file containing the content object 
   117 		@return The location of the file
   118 		*/
   119 		IMPORT_C const TDesC& URI() const;
   120 
   121 		/** UniqueId supplied by a CAF Agent to identify the object within the 
   122 		file.  
   123 		@return The uniqueId of the object within the file
   124 		*/
   125 		IMPORT_C const TDesC& UniqueId() const;
   126 		
   127 		/** Allows the class to write itself to a stream 
   128 		@param aStream	The stream to write to
   129 		*/
   130 		IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
   131 		
   132 		/** Convert the CVirtualPath to a single URI representing a particular 
   133 		content object. The URI and UniqueId will be separated by a KCafVirtualPathSeparator()
   134 		@return A descriptor contaning the URI and UniqueId concatenated together
   135 		*/
   136 		IMPORT_C const TDesC& GetCombinedUriUniqueId();
   137 
   138 		/** Cast operator allowing the CVirtualPath to be used as a TVirtualPathPtr 
   139 		@return a TVirtualPathPtr with the same value as this object
   140 		*/
   141 		inline operator const TVirtualPathPtr& () const;
   142 
   143 	private:
   144 		CVirtualPath(const TVirtualPathPtr& aPtr);	
   145 
   146 		/** Allow derived classes to call 2nd phase constructor
   147 		*/
   148 		void ConstructL();
   149 
   150 		/** Used to continue initialisation and setup iCombinedPtr */
   151 		void CreateCombinedUriUniqueIdL(const TDesC& aUri, const TDesC& aUniqueId);
   152 
   153 		void InternalizeL(RReadStream& aStream);
   154 
   155 	private:
   156 				
   157 		HBufC* iURI;
   158 		HBufC* iUniqueId;
   159 		HBufC* iCombinedUriUniqueId;
   160 		TPtrC iCombinedUriUniqueIdPtr;
   161 		TVirtualPathPtr iVirtualPathPtr;
   162 		};
   163 		
   164 
   165 	// Cast operator for treating a CVirtualPath as a TVirtualPathPtr
   166 	inline CVirtualPath::operator const TVirtualPathPtr& () const
   167 			{
   168 			return iVirtualPathPtr;
   169 			}
   170 	}
   171 
   172 #endif