summaryrefslogtreecommitdiffstats
path: root/udkapi/com/sun/star/uri/XUriReferenceFactory.idl
blob: e87542aa4f58a1efcf9528d9fbb67915b4e22423 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

#ifndef __com_sun_star_uri_XUriReferenceFactory_idl__
#define __com_sun_star_uri_XUriReferenceFactory_idl__

#include <com/sun/star/uno/XInterface.idl>
#include <com/sun/star/uri/RelativeUriExcessParentSegments.idl>
#include <com/sun/star/uri/XUriReference.idl>

module com { module sun { module star { module uri {

/**
   creates URI references.

   <p>See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC&nbsp;3986</a> for a
   description of URI references and related terms.</p>

   @since OOo 2.0
 */
published interface XUriReferenceFactory: com::sun::star::uno::XInterface {
    /**
       parses the textual representation of a URI reference.

       @param uriReference
       the textual representation of a URI reference.

       @returns
       an object that supports
       com::sun::star::uri::XUriReference (and possibly also
       additional, scheme-specific interfaces), if the given input can be parsed
       into a URI reference; otherwise, `NULL` is returned.
     */
    XUriReference parse([in] string uriReference);

    /**
       resolves a relative URI reference to absolute form.

       @param baseUriReference
       the base URI reference.  If the given <code>uriReference</code> is a
       same-document reference, <code>baseUriReference</code> is used as a
       reference to the current document.

       @param uriReference
       any URI reference.  Backwards-compatible relative URI references starting
       with a scheme component (see RFC&nbsp;3986, Sections 5.2.2 and&nbsp;5.4,2)
       are not supported; instead, they are interpreted as absolute
       URI references.

       @param processAdditionalSpecialSegments
       if `TRUE`, special segments (&ldquo;<code>.</code>&rdquo; and
       &ldquo;<code>..</code>&rdquo;) within the path of the base URI (except
       for the last, cut-off segment), and within an already absolute <code>uriReference</code>, are
       processed as required by
       RFC&nbsp;3986.  If `FALSE`, such special segments
       are treated like ordinary segments.
       Conformance with RFC&nbsp;3986 requires `TRUE` to be passed.

       @param excessParentSegments
       details how excess special parent segments
       (&ldquo;<code>..</code>&rdquo;) are handled.
       Conformance with RFC&nbsp;3986 requires REMOVE to be passed.

       @returns
       a fresh object that supports
       com::sun::star::uri::XUriReference (and possibly also
       additional, scheme-specific interfaces), if the given
       <code>uriReference</code> can be resolved
       to an absolute URI reference, relative to the given
       <code>baseUriReference</code>; otherwise, `NULL` is returned.
       Especially, if <code>baseUriReference</code> is `NULL`, or is not an
       absolute URI reference, or if <code>uriReference</code> is
       `NULL`, then `NULL` is always returned.
     */
    XUriReference makeAbsolute(
        [in] XUriReference baseUriReference, [in] XUriReference uriReference,
        [in] boolean processAdditionalSpecialSegments,
        [in] RelativeUriExcessParentSegments excessParentSegments);

    /**
       changes an absolute URI reference to relative form.

       @param baseUriReference
       the base URI reference.

       @param uriReference
       any URI reference.

       @param preferAuthorityOverRelativePath
       controls how a relative URI reference is generated when both
       <code>baseUriReference</code> (e.g.,
       &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
       <code>uriReference</code> (e.g.,
       &ldquo;<code>scheme://auth//c/d</code>&rdquo;) have the same scheme and
       authority components, and the path component of <code>uriReference</code>
       starts with &ldquo;<code>//</code>&rdquo;.  If `TRUE`, the generated
       relative URI reference includes an authority component (e.g.,
       &ldquo;<code>//auth//c/d</code>&rdquo;); if `FALSE`, the generated
       relative URI reference has a relative path (e.g.,
       &ldquo;<code>..//c/d</code>&rdquo;).

       @param preferAbsoluteOverRelativePath
       controls how a relative URI reference is generated when both
       <code>baseUriReference</code> (e.g.,
       &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
       <code>uriReference</code> (e.g.,
       &ldquo;<code>scheme://auth/c/d</code>&rdquo;) have the same scheme and
       authority components (if present), but share no common path segments.  If
       `TRUE`, the generated relative URI reference has an absolute path (e.g.,
       &ldquo;<code>/c/d</code>&rdquo;); if `FALSE`, the generated relative URI
       reference has a relative path (e.g., &ldquo;<code>../c/d</code>&rdquo;).

       @param encodeRetainedSpecialSegments
       if `TRUE`, special segments (&ldquo;<code>.</code>&rdquo; and
       &ldquo;<code>..</code>&rdquo;) that are already present in the path
       component of the given <code>uriReference</code> and which end up in a
       relative path returned from this method, are encoded (as
       &ldquo;<code>%2E</code>&rdquo; and &ldquo;<code>%2E%2E</code>&rdquo;,
       respectively).

       @returns
       a fresh object that supports
       com::sun::star::uri::XUriReference, if the given
       <code>uriReference</code> is either already relative, or has a relative
       path, or is of a different scheme than the given
       <code>baseUriReference</code>, or can be changed to a relative URI
       reference, relative to the given <code>baseUriReference</code>;
       otherwise, `NULL` is returned.  Especially, if
       <code>baseUriReference</code> is `NULL`, or is not an absolute
       URI reference, or if <code>uriReference</code> is `NULL`,
       then `NULL` is always returned.
     */
    XUriReference makeRelative(
        [in] XUriReference baseUriReference, [in] XUriReference uriReference,
        [in] boolean preferAuthorityOverRelativePath,
        [in] boolean preferAbsoluteOverRelativePath,
        [in] boolean encodeRetainedSpecialSegments);
};

}; }; }; };

#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */