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