1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24#ifndef __com_sun_star_uri_XUriReferenceFactory_idl__ 25#define __com_sun_star_uri_XUriReferenceFactory_idl__ 26 27#include <com/sun/star/uno/XInterface.idl> 28#include <com/sun/star/uri/RelativeUriExcessParentSegments.idl> 29#include <com/sun/star/uri/XUriReference.idl> 30 31module com { module sun { module star { module uri { 32 33/** 34 creates URI references. 35 36 <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a> for a 37 description of URI references and related terms.</p> 38 39 @since OpenOffice 2.0 40 */ 41published interface XUriReferenceFactory: com::sun::star::uno::XInterface { 42 /** 43 parses the textual representation of a URI reference. 44 45 @param uriReference 46 the textual representation of a URI reference. 47 48 @returns 49 an object that supports 50 <type scope="com::sun::star::uri">XUriReference</type> (and possibly also 51 additional, scheme-specific interfaces), if the given input can be parsed 52 into a URI reference; otherwise, <NULL/> is returned. 53 */ 54 XUriReference parse([in] string uriReference); 55 56 /** 57 resolves a relative URI reference to absolute form. 58 59 @param baseUriReference 60 the base URI reference. If the given <code>uriReference</code> is a 61 same-document reference, <code>baseUriReference</code> is used as a 62 reference to the current document. 63 64 @param uriReference 65 any URI reference. Backwards-compatible relative URI references starting 66 with a scheme component (see RFC 2396, Section 5.2, 67 step 3) are not supported; instead, they are interpreted as absolute 68 URI references. 69 70 @param processSpecialBaseSegments 71 if <TRUE/>, special segments (“<code>.</code>” and 72 “<code>..</code>”) within the path of the base URI (except 73 for the last, cut-off segment) are processed as suggested by 74 RFC 2396. If <FALSE/>, special segments within the path of the base 75 URI are treated like ordinary segments. 76 77 @param excessParentSegments 78 details how excess special parent segments 79 (“<code>..</code>”) are handled. 80 81 @returns 82 a fresh object that supports 83 <type scope="com::sun::star::uri">XUriReference</type> (and possibly also 84 additional, scheme-specific interfaces), if the given 85 <code>uriReference</code> is either already absolute, or can be resolved 86 to an absolute URI reference, relative to the given 87 <code>baseUriReference</code>; otherwise, <NULL/> is returned. 88 Especially, if <code>baseUriReference</code> is <NULL/>, or is not an 89 absolute, hierarchical URI reference, or if <code>uriReference</code> is 90 <NULL/>, then <NULL/> is always returned. 91 */ 92 XUriReference makeAbsolute( 93 [in] XUriReference baseUriReference, [in] XUriReference uriReference, 94 [in] boolean processSpecialBaseSegments, 95 [in] RelativeUriExcessParentSegments excessParentSegments); 96 97 /** 98 changes an absolute URI refrence to relative form. 99 100 @param baseUriReference 101 the base URI reference. 102 103 @param uriReference 104 any URI reference. 105 106 @param preferAuthorityOverRelativePath 107 controls how a relative URI reference is generated when both 108 <code>baseUriReference</code> (e.g., 109 “<code>scheme://auth/a/b</code>”) and 110 <code>uriReference</code> (e.g., 111 “<code>scheme://auth//c/d</code>”) have the same scheme and 112 authority components, and the path component of <code>uriReference</code> 113 starts with “<code>//</code>”. If <TRUE/>, the generated 114 relative URI reference includes an authority component (e.g., 115 “<code>//auth//c/d</code>”); if <FALSE/>, the generated 116 relative URI reference has a relative path (e.g., 117 “<code>..//c/d</code>”). 118 119 @param preferAbsoluteOverRelativePath 120 controls how a relative URI reference is generated when both 121 <code>baseUriReference</code> (e.g., 122 “<code>scheme://auth/a/b</code>”) and 123 <code>uriReference</code> (e.g., 124 “<code>scheme://auth/c/d</code>”) have the same scheme and 125 authority components (if present), but share no common path segments. If 126 <TRUE/>, the generated relative URI reference has an absolute path (e.g., 127 “<code>/c/d</code>”); if <FALSE/>, the generated relative URI 128 reference has a relative path (e.g., “<code>../c/d</code>”). 129 130 @param encodeRetainedSpecialSegments 131 if <TRUE/>, special segments (“<code>.</code>” and 132 “<code>..</code>”) that are already present in the path 133 component of the given <code>uriReference</code> and which end up in a 134 relative path returned from this method, are encoded (as 135 “<code>%2E</code>” and “<code>%2E%2E</code>”, 136 respectively). 137 138 @returns 139 a fresh object that supports 140 <type scope="com::sun::star::uri">XUriReference</type>, if the given 141 <code>uriReference</code> is either already relative, or is not 142 hierarchical, or is of a different scheme than the given 143 <code>baseUriReference</code>, or can be changed to a relative URI 144 reference, relative to the given <code>baseUriReference</code>; 145 otherwise, <NULL/> is returned. Especially, if 146 <code>baseUriReference</code> is <NULL/>, or is not an absolute, 147 hierarchical URI reference, or if <code>uriReference</code> is <NULL/>, 148 then <NULL/> is always returned. 149 */ 150 XUriReference makeRelative( 151 [in] XUriReference baseUriReference, [in] XUriReference uriReference, 152 [in] boolean preferAuthorityOverRelativePath, 153 [in] boolean preferAbsoluteOverRelativePath, 154 [in] boolean encodeRetainedSpecialSegments); 155}; 156 157}; }; }; }; 158 159#endif 160