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