svtools/inc/urihelper.hxx

   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: urihelper.hxx,v $
  10  * $Revision: 1.7 $
  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
  31 #ifndef SVTOOLS_URIHELPER_HXX
  32 #define SVTOOLS_URIHELPER_HXX
  33
  34 #include "svtools/svtdllapi.h"
  35 #include "com/sun/star/uno/Reference.hxx"
  36 #include <com/sun/star/uno/RuntimeException.hpp>
  37 #include <rtl/textenc.h>
  38 #include <tools/link.hxx>
  39 #include <tools/solar.h>
  40 #include <tools/urlobj.hxx>
  41
  42 namespace com { namespace sun { namespace star {
  43     namespace uno { class XComponentContext; }
  44     namespace uri { class XUriReference; }
  45 } } }
  46 namespace rtl { class OUString; }
  47 class ByteString;
  48 class CharClass;
  49 class UniString;
  50
  51 //============================================================================
  52 namespace URIHelper {
  53
  54 /**
  55    @ATT
  56    Calling this function with defaulted arguments rMaybeFileHdl = Link() and
  57    bCheckFileExists = true often leads to results that are not intended:
  58    Whenever the given rTheBaseURIRef is a file URL, the given rTheRelURIRef is
  59    relative, and rTheRelURIRef could also be smart-parsed as a non-file URL
  60    (e.g., the relative URL "foo/bar" can be smart-parsed as "http://foo/bar"),
  61    then SmartRel2Abs called with rMaybeFileHdl = Link() and bCheckFileExists =
  62    true returns the non-file URL interpretation.  To avoid this, either pass
  63    some non-null rMaybeFileHdl if you want to check generated file URLs for
  64    existence (see URIHelper::GetMaybeFileHdl), or use bCheckFileExists = false
  65    if you want to generate file URLs without checking for their existence.
  66 */
  67 SVT_DLLPUBLIC UniString
  68 SmartRel2Abs(INetURLObject const & rTheBaseURIRef,
  69              ByteString const & rTheRelURIRef,
  70              Link const & rMaybeFileHdl = Link(),
  71              bool bCheckFileExists = true,
  72              bool bIgnoreFragment = false,
  73              INetURLObject::EncodeMechanism eEncodeMechanism
  74                  = INetURLObject::WAS_ENCODED,
  75              INetURLObject::DecodeMechanism eDecodeMechanism
  76                  = INetURLObject::DECODE_TO_IURI,
  77              rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8,
  78              bool bRelativeNonURIs = false,
  79              INetURLObject::FSysStyle eStyle = INetURLObject::FSYS_DETECT);
  80
  81 /**
  82    @ATT
  83    Calling this function with defaulted arguments rMaybeFileHdl = Link() and
  84    bCheckFileExists = true often leads to results that are not intended:
  85    Whenever the given rTheBaseURIRef is a file URL, the given rTheRelURIRef is
  86    relative, and rTheRelURIRef could also be smart-parsed as a non-file URL
  87    (e.g., the relative URL "foo/bar" can be smart-parsed as "http://foo/bar"),
  88    then SmartRel2Abs called with rMaybeFileHdl = Link() and bCheckFileExists =
  89    true returns the non-file URL interpretation.  To avoid this, either pass
  90    some non-null rMaybeFileHdl if you want to check generated file URLs for
  91    existence (see URIHelper::GetMaybeFileHdl), or use bCheckFileExists = false
  92    if you want to generate file URLs without checking for their existence.
  93 */
  94 SVT_DLLPUBLIC UniString
  95 SmartRel2Abs(INetURLObject const & rTheBaseURIRef,
  96              UniString const & rTheRelURIRef,
  97              Link const & rMaybeFileHdl = Link(),
  98              bool bCheckFileExists = true,
  99              bool bIgnoreFragment = false,
 100              INetURLObject::EncodeMechanism eEncodeMechanism
 101                  = INetURLObject::WAS_ENCODED,
 102              INetURLObject::DecodeMechanism eDecodeMechanism
 103                  = INetURLObject::DECODE_TO_IURI,
 104              rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8,
 105              bool bRelativeNonURIs = false,
 106              INetURLObject::FSysStyle eStyle = INetURLObject::FSYS_DETECT);
 107
 108 //============================================================================
 109 SVT_DLLPUBLIC void SetMaybeFileHdl(Link const & rTheMaybeFileHdl);
 110
 111 //============================================================================
 112 SVT_DLLPUBLIC Link GetMaybeFileHdl();
 113
 114 /**
 115    Converts a URI reference to a relative one, ignoring certain differences (for
 116    example, treating file URLs for case-ignoring file systems
 117    case-insensitively).
 118
 119    @param context a component context; must not be null
 120
 121    @param baseUriReference a base URI reference
 122
 123    @param uriReference a URI reference
 124
 125    @return a URI reference representing the given uriReference relative to the
 126    given baseUriReference; if the given baseUriReference is not an absolute,
 127    hierarchical URI reference, or the given uriReference is not a valid URI
 128    reference, null is returned
 129
 130    @exception std::bad_alloc if an out-of-memory condition occurs
 131
 132    @exception com::sun::star::uno::RuntimeException if any error occurs
 133  */
 134 SVT_DLLPUBLIC com::sun::star::uno::Reference< com::sun::star::uri::XUriReference >
 135 normalizedMakeRelative(
 136     com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext >
 137     const & context,
 138     rtl::OUString const & baseUriReference, rtl::OUString const & uriReference);
 139
 140 /**
 141    A variant of normalizedMakeRelative with a simplified interface.
 142
 143    Internally calls normalizedMakeRelative with the default component context.
 144
 145    @param baseUriReference a base URI reference, passed to
 146    normalizedMakeRelative
 147
 148    @param uriReference a URI reference, passed to normalizedMakeRelative
 149
 150    @return if the XUriReference returnd by normalizedMakeRelative is empty,
 151    uriReference is returned unmodified; otherwise, the result of calling
 152    XUriReference::getUriReference on the XUriReference returnd by
 153    normalizedMakeRelative is returned
 154
 155    @exception std::bad_alloc if an out-of-memory condition occurs
 156
 157    @exception com::sun::star::uno::RuntimeException if any error occurs
 158
 159    @deprecated
 160    No code should rely on the default component context.
 161 */
 162 SVT_DLLPUBLIC rtl::OUString simpleNormalizedMakeRelative(
 163     rtl::OUString const & baseUriReference, rtl::OUString const & uriReference);
 164
 165 //============================================================================
 166 SVT_DLLPUBLIC UniString
 167 FindFirstURLInText(UniString const & rText,
 168                    xub_StrLen & rBegin,
 169                    xub_StrLen & rEnd,
 170                    CharClass const & rCharClass,
 171                    INetURLObject::EncodeMechanism eMechanism
 172                        = INetURLObject::WAS_ENCODED,
 173                    rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8,
 174                    INetURLObject::FSysStyle eStyle
 175                        = INetURLObject::FSYS_DETECT);
 176
 177 //============================================================================
 178 /** Remove any password component from both absolute and relative URLs.
 179
 180     @ATT  The current implementation will not remove a password from a
 181     relative URL that has an authority component (e.g., the password is not
 182     removed from the relative ftp URL <//user:password@domain/path>).  But
 183     since our functions to translate between absolute and relative URLs never
 184     produce relative URLs with authority components, this is no real problem.
 185
 186     @ATT  For relative URLs (or anything not recognized as an absolute URI),
 187     the current implementation will return the input unmodified, not applying
 188     any translations implied by the encode/decode parameters.
 189
 190     @param rURI  An absolute or relative URI reference.
 191
 192     @param eEncodeMechanism  See the general discussion for INetURLObject set-
 193     methods.
 194
 195     @param eDecodeMechanism  See the general discussion for INetURLObject get-
 196     methods.
 197
 198     @param eCharset  See the general discussion for INetURLObject get- and
 199     set-methods.
 200
 201     @return  The input URI with any password component removed.
 202  */
 203 SVT_DLLPUBLIC UniString
 204 removePassword(UniString const & rURI,
 205                INetURLObject::EncodeMechanism eEncodeMechanism
 206                    = INetURLObject::WAS_ENCODED,
 207                INetURLObject::DecodeMechanism eDecodeMechanism
 208                    = INetURLObject::DECODE_TO_IURI,
 209                rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
 210
 211 //============================================================================
 212 /** Query the notational conventions used in the file system provided by some
 213     file content provider.
 214
 215     @param rFileUrl  This file URL determines which file content provider is
 216     used to query the desired information.  (The UCB's usual mapping from URLs
 217     to content providers is used.)
 218
 219     @param bAddConvenienceStyles  If true, the return value contains not only
 220     the style bit corresponding to the queried content provider's conventions,
 221     but may also contain additional style bits that make using this function
 222     more convenient in certain situations.  Currently, the effect is that
 223     FSYS_UNX is extended with FSYS_VOS, and both FSYS_DOS and FSYS_MAC are
 224     extended with FSYS_VOS and FSYS_UNX (i.e., the---unambiguous---detection
 225     of VOS style and Unix style file system paths is always enabled); also, in
 226     case the content provider's conventions cannot be determined, FSYS_DETECT
 227     is returned instead of FSysStyle(0).
 228
 229     @return  The style bit corresponding to the queried content provider's
 230     conventions, or FSysStyle(0) if these cannot be determined.
 231  */
 232 SVT_DLLPUBLIC INetURLObject::FSysStyle queryFSysStyle(UniString const & rFileUrl,
 233                                         bool bAddConvenienceStyles = true)
 234     throw (com::sun::star::uno::RuntimeException);
 235
 236 }
 237
 238 #endif // SVTOOLS_URIHELPER_HXX