1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/caf/virtualpathptr.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,139 @@
1.4 +/*
1.5 +* Copyright (c) 2003-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of the License "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +/**
1.24 +@file
1.25 +
1.26 +@publishedPartner
1.27 +@released
1.28 +*/
1.29 +
1.30 +
1.31 +#ifndef __CAFVIRTUALPATHPTR_H__
1.32 +#define __CAFVIRTUALPATHPTR_H__
1.33 +
1.34 +#include <e32base.h>
1.35 +
1.36 +namespace ContentAccess
1.37 + {
1.38 + class CVirtualPath;
1.39 +
1.40 + /**
1.41 + The character used to separate the URI from the UniqueId
1.42 + when the two are concatenated into a single descriptor
1.43 + */
1.44 + _LIT(KCafVirtualPathSeparator, "|");
1.45 +
1.46 + /** Identifies the location of a file and a particular content object inside it.
1.47 +
1.48 + TVirtualPathPtr points to the two descriptors (the URI and UniqueId) used
1.49 + to initialise it. These descriptors must not be modified or destroyed while
1.50 + the TVirtualPathPtr object is in use.
1.51 +
1.52 + The URI must be in the format specified in RFC2396, found at http://www.ietf.org/.
1.53 +
1.54 + The UniqueId will be created by the Agent. Content is only ever
1.55 + accessed by one agent so it is the agents responsibility to ensure the
1.56 + UniqueId is truly unique within the file.
1.57 +
1.58 + It is also possible to flatten a virtual path into a single descriptor. The
1.59 + ContentAccess::CVirtualPath class concatenates the URI, a separator, the KCafVirtualPathSeparator
1.60 + character, and the UniqueId to form a single URI. TVirtualPathPtr can be used to
1.61 + decode this virtual path into the URI and the content object UniqueId. The
1.62 + concatenated URI and UniqueId take the format:
1.63 + @code
1.64 + <URI><KCafVirtualPathSeparator><UniqueID>
1.65 + @endcode
1.66 +
1.67 + An example of this format is shown below:
1.68 + @code
1.69 + // Create a CVirtualPath object to point to OBJECT1 inside file.dcf
1.70 + CVirtualPath *path = CVirtualPath::NewL(_L("C:\\directory\file.dcf"), _L("OBJECT1"));
1.71 +
1.72 + // convert the URI and unique ID into a single URI.
1.73 + TVirtualPathPtr aPath = path->GetCombinedUriUniqueId();
1.74 + @endcode
1.75 + @note
1.76 + If a URI is supplied which contains multiple KCafVirtualPathSeparator characters
1.77 + the rightmost KCafVirtualPathSeparator character will be taken as marking the end
1.78 + of the URI and the start of the UniqueId. When multiple KCafVirtualPathSeparator
1.79 + characters are present, under certain situations this will result in an invalid
1.80 + URI and UniqueId being created for the virtual path and can lead to an undefined failure.
1.81 +
1.82 + @publishedPartner
1.83 + @released
1.84 + */
1.85 + class TVirtualPathPtr
1.86 + {
1.87 + public:
1.88 + /** Constructor used when the URI and UniqueId fields are separate
1.89 + @param aUri The location of the file
1.90 + @param aUniqueId The location of the content within the file
1.91 + */
1.92 + IMPORT_C TVirtualPathPtr(const TDesC& aUri, const TDesC& aUniqueId);
1.93 +
1.94 + /** Constructor used for a concatenated URI and UniqueId.
1.95 +
1.96 + Note that the descriptor here may be just a URI or it could be a URI
1.97 + concatenated with the file's UniqueId. If it is a concatenated URI and
1.98 + UniqueId the URI and UniqueId will be seperated by the KCafVirtualPathSeparator character.
1.99 + For more information see above.
1.100 + @param aCombinedUriUniqueId The location of the content object
1.101 + */
1.102 + IMPORT_C TVirtualPathPtr(const TDesC& aCombinedUriUniqueId);
1.103 +
1.104 + /** Copy constructor */
1.105 + IMPORT_C TVirtualPathPtr(const TVirtualPathPtr& aPtr);
1.106 +
1.107 + /** The location of the file containing the content object
1.108 + @return The location of the file
1.109 + */
1.110 + IMPORT_C const TDesC& URI() const;
1.111 +
1.112 + /** UniqueId supplied by a CAF Agent to identify the object within the
1.113 + file.
1.114 + @return The location of the content within the file
1.115 + */
1.116 + IMPORT_C const TDesC& UniqueId() const;
1.117 +
1.118 + /** Assignment operator */
1.119 + IMPORT_C TVirtualPathPtr& operator = (const TVirtualPathPtr& aVirtualPath);
1.120 +
1.121 + /** Assignment operator converts a single descriptor to a TVirtualPathPtr.
1.122 + If the descriptor is just a URI, the TVirtualPathPtr will point to the KDefaultContentObject within that file.
1.123 + If it is a concatenated URI and UniqueId the URI and UniqueId will be seperated by the KCafVirtualPathSeparator.
1.124 + character as detailed in the description above.
1.125 + */
1.126 + IMPORT_C TVirtualPathPtr& operator = (const TDesC& aCombinedUriUniqueId);
1.127 +
1.128 +
1.129 + private:
1.130 + // The Set() function is only used by CVirtualPath
1.131 + friend class CVirtualPath;
1.132 +
1.133 + /** Used to redirect the TVirtualPathPtr to point at a different set of descriptors */
1.134 + void Set(const TDesC& aUri, const TDesC& aUniqueId);
1.135 +
1.136 + private:
1.137 + TPtrC iUri;
1.138 + TPtrC iUniqueId;
1.139 + };
1.140 + }
1.141 +
1.142 +#endif