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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 module com { module sun { module star { module uri {
  21
  22 /**
  23    creates URI references.
  24
  25    <p>See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a> for a
  26    description of URI references and related terms.</p>
  27
  28    @since OOo 2.0
  29  */
  30 published interface XUriReferenceFactory: com::sun::star::uno::XInterface {
  31     /**
  32        parses the textual representation of a URI reference.
  33
  34        @param uriReference
  35        the textual representation of a URI reference.
  36
  37        @returns
  38        an object that supports
  39        com::sun::star::uri::XUriReference (and possibly also
  40        additional, scheme-specific interfaces), if the given input can be parsed
  41        into a URI reference; otherwise, `NULL` is returned.
  42      */
  43     XUriReference parse([in] string uriReference);
  44
  45     /**
  46        resolves a relative URI reference to absolute form.
  47
  48        @param baseUriReference
  49        the base URI reference.  If the given <code>uriReference</code> is a
  50        same-document reference, <code>baseUriReference</code> is used as a
  51        reference to the current document.
  52
  53        @param uriReference
  54        any URI reference.  Backwards-compatible relative URI references starting
  55        with a scheme component (see RFC&nbsp;3986, Sections 5.2.2 and&nbsp;5.4,2)
  56        are not supported; instead, they are interpreted as absolute
  57        URI references.
  58
  59        @param processAdditionalSpecialSegments
  60        if `TRUE`, special segments (&ldquo;<code>.</code>&rdquo; and
  61        &ldquo;<code>..</code>&rdquo;) within the path of the base URI (except
  62        for the last, cut-off segment), and within an already absolute <code>uriReference</code>, are
  63        processed as required by
  64        RFC&nbsp;3986.  If `FALSE`, such special segments
  65        are treated like ordinary segments.
  66        Conformance with RFC&nbsp;3986 requires `TRUE` to be passed.
  67
  68        @param excessParentSegments
  69        details how excess special parent segments
  70        (&ldquo;<code>..</code>&rdquo;) are handled.
  71        Conformance with RFC&nbsp;3986 requires REMOVE to be passed.
  72
  73        @returns
  74        a fresh object that supports
  75        com::sun::star::uri::XUriReference (and possibly also
  76        additional, scheme-specific interfaces), if the given
  77        <code>uriReference</code> can be resolved
  78        to an absolute URI reference, relative to the given
  79        <code>baseUriReference</code>; otherwise, `NULL` is returned.
  80        Especially, if <code>baseUriReference</code> is `NULL`, or is not an
  81        absolute URI reference, or if <code>uriReference</code> is
  82        `NULL`, then `NULL` is always returned.
  83      */
  84     XUriReference makeAbsolute(
  85         [in] XUriReference baseUriReference, [in] XUriReference uriReference,
  86         [in] boolean processAdditionalSpecialSegments,
  87         [in] RelativeUriExcessParentSegments excessParentSegments);
  88
  89     /**
  90        changes an absolute URI reference to relative form.
  91
  92        @param baseUriReference
  93        the base URI reference.
  94
  95        @param uriReference
  96        any URI reference.
  97
  98        @param preferAuthorityOverRelativePath
  99        controls how a relative URI reference is generated when both
 100        <code>baseUriReference</code> (e.g.,
 101        &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
 102        <code>uriReference</code> (e.g.,
 103        &ldquo;<code>scheme://auth//c/d</code>&rdquo;) have the same scheme and
 104        authority components, and the path component of <code>uriReference</code>
 105        starts with &ldquo;<code>//</code>&rdquo;.  If `TRUE`, the generated
 106        relative URI reference includes an authority component (e.g.,
 107        &ldquo;<code>//auth//c/d</code>&rdquo;); if `FALSE`, the generated
 108        relative URI reference has a relative path (e.g.,
 109        &ldquo;<code>..//c/d</code>&rdquo;).
 110
 111        @param preferAbsoluteOverRelativePath
 112        controls how a relative URI reference is generated when both
 113        <code>baseUriReference</code> (e.g.,
 114        &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
 115        <code>uriReference</code> (e.g.,
 116        &ldquo;<code>scheme://auth/c/d</code>&rdquo;) have the same scheme and
 117        authority components (if present), but share no common path segments.  If
 118        `TRUE`, the generated relative URI reference has an absolute path (e.g.,
 119        &ldquo;<code>/c/d</code>&rdquo;); if `FALSE`, the generated relative URI
 120        reference has a relative path (e.g., &ldquo;<code>../c/d</code>&rdquo;).
 121
 122        @param encodeRetainedSpecialSegments
 123        if `TRUE`, special segments (&ldquo;<code>.</code>&rdquo; and
 124        &ldquo;<code>..</code>&rdquo;) that are already present in the path
 125        component of the given <code>uriReference</code> and which end up in a
 126        relative path returned from this method, are encoded (as
 127        &ldquo;<code>%2E</code>&rdquo; and &ldquo;<code>%2E%2E</code>&rdquo;,
 128        respectively).
 129
 130        @returns
 131        a fresh object that supports
 132        com::sun::star::uri::XUriReference, if the given
 133        <code>uriReference</code> is either already relative, or has a relative
 134        path, or is of a different scheme than the given
 135        <code>baseUriReference</code>, or can be changed to a relative URI
 136        reference, relative to the given <code>baseUriReference</code>;
 137        otherwise, `NULL` is returned.  Especially, if
 138        <code>baseUriReference</code> is `NULL`, or is not an absolute
 139        URI reference, or if <code>uriReference</code> is `NULL`,
 140        then `NULL` is always returned.
 141      */
 142     XUriReference makeRelative(
 143         [in] XUriReference baseUriReference, [in] XUriReference uriReference,
 144         [in] boolean preferAuthorityOverRelativePath,
 145         [in] boolean preferAbsoluteOverRelativePath,
 146         [in] boolean encodeRetainedSpecialSegments);
 147 };
 148
 149 }; }; }; };
 150
 151 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */