offapi/com/sun/star/util/XURLTransformer.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XURLTransformer.idl,v $
  10  * $Revision: 1.9 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_util_XURLTransformer_idl__
  31 #define __com_sun_star_util_XURLTransformer_idl__
  32
  33 #ifndef __com_sun_star_uno_XInterface_idl__
  34 #include <com/sun/star/uno/XInterface.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_util_URL_idl__
  38 #include <com/sun/star/util/URL.idl>
  39 #endif
  40
  41
  42 //=============================================================================
  43
  44 module com {  module sun {  module star {  module util {
  45
  46 //=============================================================================
  47
  48 /** supports parsing and assembling of URLs
  49
  50     @see URL
  51     @see URLTransformer
  52  */
  53 published interface XURLTransformer: com::sun::star::uno::XInterface
  54 {
  55     //-------------------------------------------------------------------------
  56     /** parses the string in <member>URL::Complete</member> which should contain
  57         a syntactically complete URL.
  58
  59         <p>
  60         The implementation is allowed to correct minor failures in <member>URL::Complete</member>
  61         if the meaning of the URL remain unchanged. Parts of the URL are stored in the other
  62         fields of <var>aURL</var>.
  63         </p>
  64
  65         @param aURL
  66                 the URL which include the complete string notation and will contain
  67                 all parsed parts of it after finishing this call. <member>URL::Complete</member>
  68                 can be overwritten if the implementation corrected minor failures.
  69
  70         @returns
  71             <TRUE/> if parsing was successfully (means if given URL was syntactically correct)
  72             or <FALSE/> otherwhise.
  73      */
  74     boolean parseStrict( [inout] com::sun::star::util::URL aURL );
  75
  76     //-------------------------------------------------------------------------
  77     /** parses the string in <member>URL::Complete</member>, which may contain
  78         a syntactically complete URL or is specified by the provided protocol
  79
  80         <p>
  81         The implementation can use smart functions to correct or interpret
  82         <member>URL::Complete</member> if it is not a syntactically complete URL.
  83         The parts of the URL are stored in the other fields of <var>aURL</var>.
  84         </p>
  85
  86         @param aURL
  87                 the URL which include the string notation and will contain
  88                 all parsed parts of it after finishing this call. This includes
  89                 <member>URL::Complete</member>.
  90
  91         @param sSmartProtocol
  92                 optional information which protocol specification should be used to parse
  93                 member<member>URL::Complete</member>. If empty the implementation can use a
  94                 protocol which fit best.
  95
  96         @returns
  97                 <TRUE/> if parsing was successful (means if <member>URL::Complete</member> could
  98                 be syntactically correct) or <FALSE/> otherwise.
  99      */
 100     boolean parseSmart(
 101         [inout] com::sun::star::util::URL aURL,
 102         [in] string sSmartProtocol );
 103
 104     //-------------------------------------------------------------------------
 105     /** assembles the parts of the URL specified by <var>aURL</var> and
 106         stores it into <member>URL::Complete</member>
 107
 108         @param aURL
 109                 the URL which contains alls neccessary information in a structured form. The
 110                 member <member>URL::Complete</member> contains the URL in string notation after
 111                 the operation finished successfully. Otherwise the content of <member>URL::complete</member>
 112                 is not defined.
 113
 114         @returns
 115             <TRUE/> if assembling was successfully or <FALSE/> otherwise.
 116      */
 117     boolean assemble( [inout] com::sun::star::util::URL aURL );
 118
 119     //-------------------------------------------------------------------------
 120     /** returns a representation of the URL for UI purposes only
 121
 122         <p>
 123         Sometimes it can be usefull to show an URL on an user interface
 124         in a more "human readable" form. Such URL can't be used on any API
 125         call, but make it easier for the user to understand it.
 126         </p>
 127
 128         @param aURL
 129                 URL in structured form which should be shown at the UI
 130
 131         @param bWithPassword
 132                 specifies whether the password will be included in the encoding
 133                 or not. Usually passwords should never be shown at the user
 134                 interface.
 135
 136         @returns
 137                 a string representing the <var>aURL</var> if it is syntactically correct. A empty string if <var>aURL</var>
 138                 is not syntactically correct.
 139      */
 140     string getPresentation(
 141         [in] com::sun::star::util::URL aURL,
 142         [in] boolean bWithPassword );
 143 };
 144
 145 //=============================================================================
 146
 147 }; }; }; };
 148
 149 #endif