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@4: @publishedAll 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 williamr@2: williamr@2: #include 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: 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: */ 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