2 * Copyright (c) 2003-2006 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
29 #ifndef __CAFVIRTUALPATH_H__
30 #define __CAFVIRTUALPATH_H__
34 #include <caf/virtualpathptr.h>
39 namespace ContentAccess
41 class TVirtualPathPtr;
43 /** A virtual path describes the location of the file (URI) and the location of
44 a content object within that file (Unique Id).
46 The URI must conform to the standard defined in RFC2396, found at http://www.ietf.org/.
48 CVirtualPath makes a copy of the URI and UniqueId used to identify a particular content
51 The TVirtualPathPtr cast operator allows the CVirtualPath object to be used with
52 CAF functions requiring a TVirtualPathPtr.
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.
58 <URI><KCafVirtualPathSeparator><UniqueID>
61 An example of this format is shown below:
63 // Create a CVirtualPath object to point to OBJECT1 inside file.dcf
64 CVirtualPath *path = CVirtualPath::NewL(_L("C:\\directory\file.dcf"), _L("OBJECT1"));
66 // convert the URI and unique ID into a single URI.
67 TVirtualPathPtr aPath = path->GetCombinedUriUniqueId();
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.
79 class CVirtualPath : public CBase
82 /** Create a CVirtualPath object from a TVirtualPathPtr
83 @param aPtr The location of the content object
84 @return a new CVirtualPath object
86 IMPORT_C static CVirtualPath* NewL(const TVirtualPathPtr& aPtr);
88 /** Create a virtual path object from a combined Uri and UniqueId
90 This constructs a CVirtual path from a single descriptor.
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
99 IMPORT_C static CVirtualPath* NewL(const TDesC& aCombinedUriUniqueId);
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
106 IMPORT_C static CVirtualPath* NewL(const TDesC& aURI, const TDesC& aUniqueId);
108 /** Construct and read a CVirtualPath object from a stream
109 @param aStream The stream to read frin
111 IMPORT_C static CVirtualPath* NewL(RReadStream& aStream);
114 virtual ~CVirtualPath();
116 /** The location of the file containing the content object
117 @return The location of the file
119 IMPORT_C const TDesC& URI() const;
121 /** UniqueId supplied by a CAF Agent to identify the object within the
123 @return The uniqueId of the object within the file
125 IMPORT_C const TDesC& UniqueId() const;
127 /** Allows the class to write itself to a stream
128 @param aStream The stream to write to
130 IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
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
136 IMPORT_C const TDesC& GetCombinedUriUniqueId();
138 /** Cast operator allowing the CVirtualPath to be used as a TVirtualPathPtr
139 @return a TVirtualPathPtr with the same value as this object
141 inline operator const TVirtualPathPtr& () const;
144 CVirtualPath(const TVirtualPathPtr& aPtr);
146 /** Allow derived classes to call 2nd phase constructor
150 /** Used to continue initialisation and setup iCombinedPtr */
151 void CreateCombinedUriUniqueIdL(const TDesC& aUri, const TDesC& aUniqueId);
153 void InternalizeL(RReadStream& aStream);
159 HBufC* iCombinedUriUniqueId;
160 TPtrC iCombinedUriUniqueIdPtr;
161 TVirtualPathPtr iVirtualPathPtr;
165 // Cast operator for treating a CVirtualPath as a TVirtualPathPtr
166 inline CVirtualPath::operator const TVirtualPathPtr& () const
168 return iVirtualPathPtr;