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#ifndef __com_sun_star_util_XURLTransformer_idl__
24#define __com_sun_star_util_XURLTransformer_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30#ifndef __com_sun_star_util_URL_idl__
31#include <com/sun/star/util/URL.idl>
32#endif
33
34
35//=============================================================================
36
37module com {  module sun {  module star {  module util {
38
39//=============================================================================
40
41/** supports parsing and assembling of URLs
42
43    @see URL
44    @see URLTransformer
45 */
46published interface XURLTransformer: com::sun::star::uno::XInterface
47{
48	//-------------------------------------------------------------------------
49	/** parses the string in <member>URL::Complete</member> which should contain
50        a syntactically complete URL.
51
52        <p>
53		The implementation is allowed to correct minor failures in <member>URL::Complete</member>
54		if the meaning of the URL remain unchanged. Parts of the URL are stored in the other
55		fields of <var>aURL</var>.
56		</p>
57
58        @param aURL
59                the URL which include the complete string notation and will contain
60                all parsed parts of it after finishing this call. <member>URL::Complete</member>
61				can be overwritten if the implementation corrected minor failures.
62
63        @returns
64			<TRUE/> if parsing was successfully (means if given URL was syntactically correct)
65            or <FALSE/> otherwise.
66	 */
67	boolean parseStrict( [inout] com::sun::star::util::URL aURL );
68
69	//-------------------------------------------------------------------------
70	/** parses the string in <member>URL::Complete</member>, which may contain
71		a syntactically complete URL or is specified by the provided protocol
72
73        <p>
74		The implementation can use smart functions to correct or interpret
75		<member>URL::Complete</member> if it is not a syntactically complete URL.
76		The parts of the URL are stored in the other fields of <var>aURL</var>.
77		</p>
78
79        @param aURL
80                the URL which include the string notation and will contain
81                all parsed parts of it after finishing this call. This includes
82				<member>URL::Complete</member>.
83
84        @param sSmartProtocol
85                optional information which protocol specification should be used to parse
86				member<member>URL::Complete</member>. If empty the implementation can use a
87				protocol which fit best.
88
89        @returns
90				<TRUE/> if parsing was successful (means if <member>URL::Complete</member> could
91				be syntactically correct) or <FALSE/> otherwise.
92	 */
93    boolean parseSmart(
94        [inout] com::sun::star::util::URL aURL,
95        [in] string sSmartProtocol );
96
97	//-------------------------------------------------------------------------
98    /** assembles the parts of the URL specified by <var>aURL</var> and
99        stores it into <member>URL::Complete</member>
100
101        @param aURL
102                the URL which contains alls necessary information in a structured form. The
103                member <member>URL::Complete</member> contains the URL in string notation after
104				the operation finished successfully. Otherwise the content of <member>URL::complete</member>
105				is not defined.
106
107        @returns
108			<TRUE/> if assembling was successfully or <FALSE/> otherwise.
109	 */
110	boolean assemble( [inout] com::sun::star::util::URL aURL );
111
112	//-------------------------------------------------------------------------
113    /** returns a representation of the URL for UI purposes only
114
115        <p>
116        Sometimes it can be useful to show an URL on an user interface
117        in a more "human readable" form. Such URL can't be used on any API
118        call, but make it easier for the user to understand it.
119        </p>
120
121        @param aURL
122                URL in structured form which should be shown at the UI
123
124        @param bWithPassword
125                specifies whether the password will be included in the encoding
126                or not. Usually passwords should never be shown at the user
127                interface.
128
129        @returns
130				a string representing the <var>aURL</var> if it is syntactically correct. A empty string if <var>aURL</var>
131				is not syntactically correct.
132	 */
133    string getPresentation(
134        [in] com::sun::star::util::URL aURL,
135        [in] boolean bWithPassword );
136};
137
138//=============================================================================
139
140}; }; }; };
141
142#endif
143