1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_uri_XUriReferenceFactory_idl__
25#define __com_sun_star_uri_XUriReferenceFactory_idl__
26
27#include <com/sun/star/uno/XInterface.idl>
28#include <com/sun/star/uri/RelativeUriExcessParentSegments.idl>
29#include <com/sun/star/uri/XUriReference.idl>
30
31module com { module sun { module star { module uri {
32
33/**
34   creates URI references.
35
36   <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC&nbsp;2396</a> for a
37   description of URI references and related terms.</p>
38
39   @since OpenOffice 2.0
40 */
41published interface XUriReferenceFactory: com::sun::star::uno::XInterface {
42    /**
43       parses the textual representation of a URI reference.
44
45       @param uriReference
46       the textual representation of a URI reference.
47
48       @returns
49       an object that supports
50       <type scope="com::sun::star::uri">XUriReference</type> (and possibly also
51       additional, scheme-specific interfaces), if the given input can be parsed
52       into a URI reference; otherwise, <NULL/> is returned.
53     */
54    XUriReference parse([in] string uriReference);
55
56    /**
57       resolves a relative URI reference to absolute form.
58
59       @param baseUriReference
60       the base URI reference.  If the given <code>uriReference</code> is a
61       same-document reference, <code>baseUriReference</code> is used as a
62       reference to the current document.
63
64       @param uriReference
65       any URI reference.  Backwards-compatible relative URI references starting
66       with a scheme component (see RFC&nbsp;2396, Section&nbsp;5.2,
67       step&nbsp;3) are not supported; instead, they are interpreted as absolute
68       URI references.
69
70       @param processSpecialBaseSegments
71       if <TRUE/>, special segments (&ldquo;<code>.</code>&rdquo; and
72       &ldquo;<code>..</code>&rdquo;) within the path of the base URI (except
73       for the last, cut-off segment) are processed as suggested by
74       RFC&nbsp;2396.  If <FALSE/>, special segments within the path of the base
75       URI are treated like ordinary segments.
76
77       @param excessParentSegments
78       details how excess special parent segments
79       (&ldquo;<code>..</code>&rdquo;) are handled.
80
81       @returns
82       a fresh object that supports
83       <type scope="com::sun::star::uri">XUriReference</type> (and possibly also
84       additional, scheme-specific interfaces), if the given
85       <code>uriReference</code> is either already absolute, or can be resolved
86       to an absolute URI reference, relative to the given
87       <code>baseUriReference</code>; otherwise, <NULL/> is returned.
88       Especially, if <code>baseUriReference</code> is <NULL/>, or is not an
89       absolute, hierarchical URI reference, or if <code>uriReference</code> is
90       <NULL/>, then <NULL/> is always returned.
91     */
92    XUriReference makeAbsolute(
93        [in] XUriReference baseUriReference, [in] XUriReference uriReference,
94        [in] boolean processSpecialBaseSegments,
95        [in] RelativeUriExcessParentSegments excessParentSegments);
96
97    /**
98       changes an absolute URI reference to relative form.
99
100       @param baseUriReference
101       the base URI reference.
102
103       @param uriReference
104       any URI reference.
105
106       @param preferAuthorityOverRelativePath
107       controls how a relative URI reference is generated when both
108       <code>baseUriReference</code> (e.g.,
109       &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
110       <code>uriReference</code> (e.g.,
111       &ldquo;<code>scheme://auth//c/d</code>&rdquo;) have the same scheme and
112       authority components, and the path component of <code>uriReference</code>
113       starts with &ldquo;<code>//</code>&rdquo;.  If <TRUE/>, the generated
114       relative URI reference includes an authority component (e.g.,
115       &ldquo;<code>//auth//c/d</code>&rdquo;); if <FALSE/>, the generated
116       relative URI reference has a relative path (e.g.,
117       &ldquo;<code>..//c/d</code>&rdquo;).
118
119       @param preferAbsoluteOverRelativePath
120       controls how a relative URI reference is generated when both
121       <code>baseUriReference</code> (e.g.,
122       &ldquo;<code>scheme://auth/a/b</code>&rdquo;) and
123       <code>uriReference</code> (e.g.,
124       &ldquo;<code>scheme://auth/c/d</code>&rdquo;) have the same scheme and
125       authority components (if present), but share no common path segments.  If
126       <TRUE/>, the generated relative URI reference has an absolute path (e.g.,
127       &ldquo;<code>/c/d</code>&rdquo;); if <FALSE/>, the generated relative URI
128       reference has a relative path (e.g., &ldquo;<code>../c/d</code>&rdquo;).
129
130       @param encodeRetainedSpecialSegments
131       if <TRUE/>, special segments (&ldquo;<code>.</code>&rdquo; and
132       &ldquo;<code>..</code>&rdquo;) that are already present in the path
133       component of the given <code>uriReference</code> and which end up in a
134       relative path returned from this method, are encoded (as
135       &ldquo;<code>%2E</code>&rdquo; and &ldquo;<code>%2E%2E</code>&rdquo;,
136       respectively).
137
138       @returns
139       a fresh object that supports
140       <type scope="com::sun::star::uri">XUriReference</type>, if the given
141       <code>uriReference</code> is either already relative, or is not
142       hierarchical, or is of a different scheme than the given
143       <code>baseUriReference</code>, or can be changed to a relative URI
144       reference, relative to the given <code>baseUriReference</code>;
145       otherwise, <NULL/> is returned.  Especially, if
146       <code>baseUriReference</code> is <NULL/>, or is not an absolute,
147       hierarchical URI reference, or if <code>uriReference</code> is <NULL/>,
148       then <NULL/> is always returned.
149     */
150    XUriReference makeRelative(
151        [in] XUriReference baseUriReference, [in] XUriReference uriReference,
152        [in] boolean preferAuthorityOverRelativePath,
153        [in] boolean preferAbsoluteOverRelativePath,
154        [in] boolean encodeRetainedSpecialSegments);
155};
156
157}; }; }; };
158
159#endif
160