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: #ifndef __CAFVIRTUALPATHPTR_H__ williamr@2: #define __CAFVIRTUALPATHPTR_H__ williamr@2: williamr@2: #include williamr@2: williamr@2: namespace ContentAccess williamr@2: { williamr@2: class CVirtualPath; williamr@2: williamr@2: /** williamr@2: The character used to separate the URI from the UniqueId williamr@2: when the two are concatenated into a single descriptor williamr@2: */ williamr@2: _LIT(KCafVirtualPathSeparator, "|"); williamr@2: williamr@2: /** Identifies the location of a file and a particular content object inside it. williamr@2: williamr@2: TVirtualPathPtr points to the two descriptors (the URI and UniqueId) used williamr@2: to initialise it. These descriptors must not be modified or destroyed while williamr@2: the TVirtualPathPtr object is in use. williamr@2: williamr@2: The URI must be in the format specified in RFC2396, found at http://www.ietf.org/. williamr@2: williamr@2: The UniqueId will be created by the Agent. Content is only ever williamr@2: accessed by one agent so it is the agents responsibility to ensure the williamr@2: UniqueId is truly unique within the file. williamr@2: williamr@2: It is also possible to flatten a virtual path into a single descriptor. The williamr@2: ContentAccess::CVirtualPath class concatenates the URI, a separator, the KCafVirtualPathSeparator williamr@2: character, and the UniqueId to form a single URI. TVirtualPathPtr can be used to williamr@2: decode this virtual path into the URI and the content object UniqueId. The williamr@2: concatenated URI and UniqueId take 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: @publishedPartner williamr@2: @released williamr@2: */ williamr@2: class TVirtualPathPtr williamr@2: { williamr@2: public: williamr@2: /** Constructor used when the URI and UniqueId fields are separate williamr@2: @param aUri The location of the file williamr@2: @param aUniqueId The location of the content within the file williamr@2: */ williamr@2: IMPORT_C TVirtualPathPtr(const TDesC& aUri, const TDesC& aUniqueId); williamr@2: williamr@2: /** Constructor used for a concatenated URI and UniqueId. 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 KCafVirtualPathSeparator character. williamr@2: For more information see above. williamr@2: @param aCombinedUriUniqueId The location of the content object williamr@2: */ williamr@2: IMPORT_C TVirtualPathPtr(const TDesC& aCombinedUriUniqueId); williamr@2: williamr@2: /** Copy constructor */ williamr@2: IMPORT_C TVirtualPathPtr(const TVirtualPathPtr& aPtr); 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 location of the content within the file williamr@2: */ williamr@2: IMPORT_C const TDesC& UniqueId() const; williamr@2: williamr@2: /** Assignment operator */ williamr@2: IMPORT_C TVirtualPathPtr& operator = (const TVirtualPathPtr& aVirtualPath); williamr@2: williamr@2: /** Assignment operator converts a single descriptor to a TVirtualPathPtr. williamr@2: If the descriptor is just a URI, the TVirtualPathPtr will point to the KDefaultContentObject within that file. williamr@2: If it is a concatenated URI and UniqueId the URI and UniqueId will be seperated by the KCafVirtualPathSeparator. williamr@2: character as detailed in the description above. williamr@2: */ williamr@2: IMPORT_C TVirtualPathPtr& operator = (const TDesC& aCombinedUriUniqueId); williamr@2: williamr@2: williamr@2: private: williamr@2: // The Set() function is only used by CVirtualPath williamr@2: friend class CVirtualPath; williamr@2: williamr@2: /** Used to redirect the TVirtualPathPtr to point at a different set of descriptors */ williamr@2: void Set(const TDesC& aUri, const TDesC& aUniqueId); williamr@2: williamr@2: private: williamr@2: TPtrC iUri; williamr@2: TPtrC iUniqueId; williamr@2: }; williamr@2: } williamr@2: williamr@2: #endif