1 /*

     2 * Copyright (c) 2003-2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     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".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 

    20 /** 

    21 @file

    22 

    23 @publishedPartner

    24 @released

    25 */

    26 

    27 

    28 #ifndef __CAFVIRTUALPATHPTR_H__

    29 #define __CAFVIRTUALPATHPTR_H__

    30 

    31 #include <e32base.h>

    32 

    33 namespace ContentAccess

    34 	{

    35 	class CVirtualPath;

    36 

    37 	/** 

    38 	The character used to separate the URI from the UniqueId 

    39 	when the two are concatenated into a single descriptor 

    40 	*/

    41 	_LIT(KCafVirtualPathSeparator, "|");

    42 

    43 	/**	Identifies the location of a file and a particular content object inside it.

    44 

    45 	TVirtualPathPtr points to the two descriptors (the URI and UniqueId) used 

    46 	to initialise it. These descriptors must not be modified or destroyed while 

    47 	the TVirtualPathPtr object is in use. 

    48 	

    49 	The URI must be in the format specified in RFC2396, found at http://www.ietf.org/.

    50 

    51 	The UniqueId will be created by the Agent. Content is only ever

    52 	accessed by one agent so it is the agents responsibility to ensure the 

    53 	UniqueId is truly unique within the file.

    54 

    55 	It is also possible to flatten a virtual path into a single descriptor. The

    56 	ContentAccess::CVirtualPath class concatenates the URI, a separator, the KCafVirtualPathSeparator

    57 	character, and the UniqueId to form a single URI. TVirtualPathPtr can be used to 

    58 	decode this virtual path into the URI and the content object UniqueId. The 

    59 	concatenated URI and UniqueId take the format:

    60 	@code

    61 		<URI><KCafVirtualPathSeparator><UniqueID>

    62 	@endcode

    63 	

    64 	An example of this format is shown below:		

    65 	@code

    66 	// Create a CVirtualPath object to point to OBJECT1 inside file.dcf

    67 	CVirtualPath *path = CVirtualPath::NewL(_L("C:\\directory\file.dcf"), _L("OBJECT1"));

    68 

    69 	// convert the URI and unique ID into a single URI.

    70 	TVirtualPathPtr aPath = path->GetCombinedUriUniqueId();

    71 	@endcode

    72 	@note

    73 	If a URI is supplied which contains multiple KCafVirtualPathSeparator characters 

    74 	the rightmost KCafVirtualPathSeparator character will be taken as marking the end

    75 	of the URI and the start of the UniqueId. When multiple KCafVirtualPathSeparator

    76 	characters are present, under certain situations this will result in an invalid 

    77 	URI and UniqueId being created for the virtual path and can lead to an undefined failure.

    78 

    79 	@publishedPartner

    80 	@released

    81 	*/

    82 	class TVirtualPathPtr

    83 		{

    84 	public:

    85 		/** Constructor used when the URI and UniqueId fields are separate 

    86 		@param aUri The location of the file

    87 		@param aUniqueId The location of the content within the file

    88 		*/

    89 		IMPORT_C TVirtualPathPtr(const TDesC& aUri, const TDesC& aUniqueId);

    90 

    91 		/** Constructor used for a concatenated URI and UniqueId.

    92 		

    93 		Note that the descriptor here may be just a URI or it could be a URI

    94 		concatenated with the file's UniqueId. If it is a concatenated URI and 

    95 		UniqueId the URI and UniqueId will be seperated by the KCafVirtualPathSeparator character.

    96 		For more information see above.

    97 		@param aCombinedUriUniqueId The location of the content object

    98 		*/

    99 		IMPORT_C TVirtualPathPtr(const TDesC& aCombinedUriUniqueId);

   100 

   101 		/** Copy constructor */

   102 		IMPORT_C TVirtualPathPtr(const TVirtualPathPtr& aPtr);

   103 

   104 		/** The location of the file containing the content object 

   105 		@return The location of the file

   106 		*/

   107 		IMPORT_C const TDesC& URI() const;

   108 

   109 		/** UniqueId supplied by a CAF Agent to identify the object within the 

   110 		file.  

   111 		@return The location of the content within the file

   112 		*/

   113 		IMPORT_C const TDesC& UniqueId() const;

   114 

   115 		/** Assignment operator */

   116 		IMPORT_C TVirtualPathPtr& operator = (const TVirtualPathPtr& aVirtualPath);

   117 	

   118 		/** Assignment operator converts a single descriptor to a TVirtualPathPtr.

   119 		If the descriptor is just a URI, the TVirtualPathPtr will point to the KDefaultContentObject within that file.

   120 		If it is a concatenated URI and UniqueId the URI and UniqueId will be seperated by the KCafVirtualPathSeparator. 

   121 		character as detailed in the description above.   

   122 		*/

   123 		IMPORT_C TVirtualPathPtr& operator = (const TDesC& aCombinedUriUniqueId);

   124 

   125 

   126 	private:

   127 		// The Set() function is only used by CVirtualPath

   128 		friend class CVirtualPath;

   129 

   130 		/** Used to redirect the TVirtualPathPtr to point at a different set of descriptors */

   131 		void Set(const TDesC& aUri, const TDesC& aUniqueId);

   132 

   133 	private:

   134 		TPtrC iUri;

   135 		TPtrC iUniqueId;

   136 		};

   137 	}

   138 

   139 #endif