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

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