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