udkapi/com/sun/star/uri/XUriReferenceFactory.idl

   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
  35 module 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&nbsp;2396</a> for a
  41    description of URI references and related terms.</p>
  42
  43    @since OOo 2.0.0
  44  */
  45 published 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&nbsp;2396, Section&nbsp;5.2,
  71        step&nbsp;3) are not supported; instead, they are interpreted as absolute
  72        URI references.
  73
  74        @param processSpecialBaseSegments
  75        if <TRUE/>, special segments (&ldquo;<code>.</code>&rdquo; and
  76        &ldquo;<code>..</code>&rdquo;) within the path of the base URI (except
  77        for the last, cut-off segment) are processed as suggested by
  78        RFC&nbsp;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        (&ldquo;<code>..</code>&rdquo;) 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        &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
 114        <code>uriReference</code> (e.g.,
 115        &ldquo;<code>scheme://auth//c/d</code>&rdquo;) have the same scheme and
 116        authority components, and the path component of <code>uriReference</code>
 117        starts with &ldquo;<code>//</code>&rdquo;.  If <TRUE/>, the generated
 118        relative URI reference includes an authority component (e.g.,
 119        &ldquo;<code>//auth//c/d</code>&rdquo;); if <FALSE/>, the generated
 120        relative URI reference has a relative path (e.g.,
 121        &ldquo;<code>..//c/d</code>&rdquo;).
 122
 123        @param preferAbsoluteOverRelativePath
 124        controls how a relative URI reference is generated when both
 125        <code>baseUriReference</code> (e.g.,
 126        &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
 127        <code>uriReference</code> (e.g.,
 128        &ldquo;<code>scheme://auth/c/d</code>&rdquo;) 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        &ldquo;<code>/c/d</code>&rdquo;); if <FALSE/>, the generated relative URI
 132        reference has a relative path (e.g., &ldquo;<code>../c/d</code>&rdquo;).
 133
 134        @param encodeRetainedSpecialSegments
 135        if <TRUE/>, special segments (&ldquo;<code>.</code>&rdquo; and
 136        &ldquo;<code>..</code>&rdquo;) 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        &ldquo;<code>%2E</code>&rdquo; and &ldquo;<code>%2E%2E</code>&rdquo;,
 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