1/************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28#ifndef __com_sun_star_uri_XUriReferenceFactory_idl__ 29#define __com_sun_star_uri_XUriReferenceFactory_idl__ 30 31#include <com/sun/star/uno/XInterface.idl> 32#include <com/sun/star/uri/RelativeUriExcessParentSegments.idl> 33#include <com/sun/star/uri/XUriReference.idl> 34 35module com { module sun { module star { module uri { 36 37/** 38 creates URI references. 39 40 <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a> for a 41 description of URI references and related terms.</p> 42 43 @since OOo 2.0 44 */ 45published interface XUriReferenceFactory: com::sun::star::uno::XInterface { 46 /** 47 parses the textual representation of a URI reference. 48 49 @param uriReference 50 the textual representation of a URI reference. 51 52 @returns 53 an object that supports 54 <type scope="com::sun::star::uri">XUriReference</type> (and possibly also 55 additional, scheme-specific interfaces), if the given input can be parsed 56 into a URI reference; otherwise, <NULL/> is returned. 57 */ 58 XUriReference parse([in] string uriReference); 59 60 /** 61 resolves a relative URI reference to absolute form. 62 63 @param baseUriReference 64 the base URI reference. If the given <code>uriReference</code> is a 65 same-document reference, <code>baseUriReference</code> is used as a 66 reference to the current document. 67 68 @param uriReference 69 any URI reference. Backwards-compatible relative URI references starting 70 with a scheme component (see RFC 2396, Section 5.2, 71 step 3) are not supported; instead, they are interpreted as absolute 72 URI references. 73 74 @param processSpecialBaseSegments 75 if <TRUE/>, special segments (“<code>.</code>” and 76 “<code>..</code>”) within the path of the base URI (except 77 for the last, cut-off segment) are processed as suggested by 78 RFC 2396. If <FALSE/>, special segments within the path of the base 79 URI are treated like ordinary segments. 80 81 @param excessParentSegments 82 details how excess special parent segments 83 (“<code>..</code>”) are handled. 84 85 @returns 86 a fresh object that supports 87 <type scope="com::sun::star::uri">XUriReference</type> (and possibly also 88 additional, scheme-specific interfaces), if the given 89 <code>uriReference</code> is either already absolute, or can be resolved 90 to an absolute URI reference, relative to the given 91 <code>baseUriReference</code>; otherwise, <NULL/> is returned. 92 Especially, if <code>baseUriReference</code> is <NULL/>, or is not an 93 absolute, hierarchical URI reference, or if <code>uriReference</code> is 94 <NULL/>, then <NULL/> is always returned. 95 */ 96 XUriReference makeAbsolute( 97 [in] XUriReference baseUriReference, [in] XUriReference uriReference, 98 [in] boolean processSpecialBaseSegments, 99 [in] RelativeUriExcessParentSegments excessParentSegments); 100 101 /** 102 changes an absolute URI refrence to relative form. 103 104 @param baseUriReference 105 the base URI reference. 106 107 @param uriReference 108 any URI reference. 109 110 @param preferAuthorityOverRelativePath 111 controls how a relative URI reference is generated when both 112 <code>baseUriReference</code> (e.g., 113 “<code>scheme://auth/a/b</code>”) and 114 <code>uriReference</code> (e.g., 115 “<code>scheme://auth//c/d</code>”) have the same scheme and 116 authority components, and the path component of <code>uriReference</code> 117 starts with “<code>//</code>”. If <TRUE/>, the generated 118 relative URI reference includes an authority component (e.g., 119 “<code>//auth//c/d</code>”); if <FALSE/>, the generated 120 relative URI reference has a relative path (e.g., 121 “<code>..//c/d</code>”). 122 123 @param preferAbsoluteOverRelativePath 124 controls how a relative URI reference is generated when both 125 <code>baseUriReference</code> (e.g., 126 “<code>scheme://auth/a/b</code>”) and 127 <code>uriReference</code> (e.g., 128 “<code>scheme://auth/c/d</code>”) have the same scheme and 129 authority components (if present), but share no common path segments. If 130 <TRUE/>, the generated relative URI reference has an absolute path (e.g., 131 “<code>/c/d</code>”); if <FALSE/>, the generated relative URI 132 reference has a relative path (e.g., “<code>../c/d</code>”). 133 134 @param encodeRetainedSpecialSegments 135 if <TRUE/>, special segments (“<code>.</code>” and 136 “<code>..</code>”) that are already present in the path 137 component of the given <code>uriReference</code> and which end up in a 138 relative path returned from this method, are encoded (as 139 “<code>%2E</code>” and “<code>%2E%2E</code>”, 140 respectively). 141 142 @returns 143 a fresh object that supports 144 <type scope="com::sun::star::uri">XUriReference</type>, if the given 145 <code>uriReference</code> is either already relative, or is not 146 hierarchical, or is of a different scheme than the given 147 <code>baseUriReference</code>, or can be changed to a relative URI 148 reference, relative to the given <code>baseUriReference</code>; 149 otherwise, <NULL/> is returned. Especially, if 150 <code>baseUriReference</code> is <NULL/>, or is not an absolute, 151 hierarchical URI reference, or if <code>uriReference</code> is <NULL/>, 152 then <NULL/> is always returned. 153 */ 154 XUriReference makeRelative( 155 [in] XUriReference baseUriReference, [in] XUriReference uriReference, 156 [in] boolean preferAuthorityOverRelativePath, 157 [in] boolean preferAbsoluteOverRelativePath, 158 [in] boolean encodeRetainedSpecialSegments); 159}; 160 161}; }; }; }; 162 163#endif 164