udkapi/com/sun/star/uri/XUriReference.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    represents generic, mutable 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    <p>This interface only handles generic URI references (both absolute and
  29    relative).  For specific URI schemes, there will be additional interfaces
  30    that offer extra, scheme-specific functionality.</p>
  31
  32    @see com::sun::star::uri::UriReferenceFactory
  33    which allows to create URI reference objects that support
  34    com::sun::star::uri::XUriReference and additional,
  35    scheme-specific interfaces.
  36
  37    @since OOo 2.0
  38  */
  39 published interface XUriReference: com::sun::star::uno::XInterface {
  40     /**
  41        returns the textual representation of the complete URI reference.
  42
  43        @returns
  44        the textual representation of the complete URI reference.  The exact
  45        spelling of the URI reference is retained.
  46      */
  47     string getUriReference();
  48
  49     /**
  50        returns whether this URI reference is absolute or relative.
  51
  52        <p>A URI is absolute if it has a scheme.</p>
  53
  54        @returns
  55        `TRUE` if this URI reference is absolute, `FALSE` if it is relative.
  56      */
  57     boolean isAbsolute();
  58
  59     /**
  60        returns the scheme part of this (absolute) URI reference.
  61
  62        @returns
  63        the textual representation of the scheme part (with the exact spelling
  64        retained; without the delimiting &ldquo;<code>:</code>&rdquo;), if this
  65        is an absolute URI reference; otherwise, an empty `string` is
  66        returned.
  67      */
  68     string getScheme();
  69
  70     /**
  71        returns the scheme-specific part of this URI reference.
  72
  73        <p>For an absolute URI reference, the scheme-specific part is everything
  74        after the scheme part and the delimiting &ldquo;<code>:</code>&rdquo;,
  75        and before the optional &ldquo;<code>#</code>&rdquo; and fragment part.
  76        For a relative URI reference, the scheme-specific part is everything
  77        before the optional &ldquo;<code>#</code>&rdquo; and fragment part.</p>
  78
  79        @returns
  80        the textual representation of the scheme-specific part (with the exact
  81        spelling retained).
  82      */
  83     string getSchemeSpecificPart();
  84
  85     /**
  86        returns whether this URI reference is hierarchical or opaque, in the sense of RFC&nbsp2396.
  87
  88        <p>An absolute URI reference is hierarchical if its scheme-specific part
  89        starts with &ldquo;<code>/</code>&rdquo;.  A relative URI reference is
  90        always hierarchical.</p>
  91
  92        @returns
  93        `TRUE` if this URI reference is hierarchical, `FALSE` if it is opaque.
  94
  95        @deprecated RFC&nbsp;3986 no longer differentiates between hierarchical and opaque URIs.
  96      */
  97     boolean isHierarchical();
  98
  99     /**
 100        returns whether this URI reference has an authority part.
 101
 102        @returns
 103        `TRUE` if this URI reference has an authority part.
 104      */
 105     boolean hasAuthority();
 106
 107     /**
 108        returns the authority part of this URI reference.
 109
 110        @returns
 111        the textual representation of the authority part (with the exact spelling
 112        retained), if this is a URI reference that has an authority
 113        part; otherwise, an empty `string` is returned.
 114      */
 115     string getAuthority();
 116
 117     /**
 118        returns the path part of this URI reference.
 119
 120        @returns
 121        the textual representation of the path part (with the exact spelling
 122        retained).
 123      */
 124     string getPath();
 125
 126     /**
 127        returns whether this URI reference has a relative path.
 128
 129        @returns
 130        `TRUE` if this URI reference has a relative path.
 131      */
 132     boolean hasRelativePath();
 133
 134     /**
 135        returns the number of path segments of this URI reference.
 136
 137        <p>For a URI reference with
 138        an empty path, the number of path segments is zero.  For a
 139        URI reference with an absolute, non-empty path, the number of path
 140        segments equals the number of &ldquo;<code>/</code>&rdquo; delimiters.
 141        For a URI reference with a relative, non-empty path, the
 142        number of path segments equals the number of &ldquo;<code>/</code>&rdquo;
 143        delimiters, plus one.</p>
 144
 145        @returns
 146        the number of path segments.
 147      */
 148     long getPathSegmentCount();
 149
 150     /**
 151        returns a given path segment of this URI reference.
 152
 153        @param index
 154        the index of the path segment, starting at zero.
 155
 156        @returns
 157        the textual representation of the given path segment (with the exact
 158        spelling retained, without any delimiting &ldquo;<code>/</code>&rdquo;),
 159        if this URI reference has that many path segments;
 160        otherwise, and in particular if <code>index</code> is negative, an empty
 161        `string` is returned.
 162      */
 163     string getPathSegment([in] long index);
 164
 165     /**
 166        returns whether this URI reference has a query part.
 167
 168        @returns
 169        `TRUE` if this URI reference has a query part.
 170      */
 171     boolean hasQuery();
 172
 173     /**
 174        returns the query part of this URI reference.
 175
 176        @returns
 177        the textual representation of the query part (with the exact spelling
 178        retained; without the delimiting &ldquo;<code>?</code>&rdquo;), if this
 179        is a URI reference that has a query part; otherwise, an
 180        empty `string` is returned.
 181      */
 182     string getQuery();
 183
 184     /**
 185        returns whether this URI reference has a fragment part.
 186
 187        @returns
 188        `TRUE` if this URI reference has a fragment part.
 189      */
 190     boolean hasFragment();
 191
 192     /**
 193        returns the fragment part of this URI reference.
 194
 195        @returns
 196        the textual representation of the fragment part (with the exact spelling
 197        retained; without the delimiting &ldquo;<code>#</code>&rdquo;), if this
 198        is a URI reference that has a fragment part; otherwise, an empty
 199        `string` is returned.
 200      */
 201     string getFragment();
 202
 203     /**
 204        sets the fragment part of this URI reference.
 205
 206        @param fragment
 207        the textual representation of the new fragment part.  The exact spelling
 208        will be preserved, and no escaping is performed.
 209      */
 210     void setFragment([in] string fragment);
 211
 212     /**
 213        clears the fragment part of this URI reference.
 214      */
 215     void clearFragment();
 216 };
 217
 218 }; }; }; };
 219
 220 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */