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