include/svl/urihelper.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_SVL_URIHELPER_HXX
  21 #define INCLUDED_SVL_URIHELPER_HXX
  22
  23 #include <com/sun/star/uno/Reference.hxx>
  24 #include <rtl/textenc.h>
  25 #include <svl/svldllapi.h>
  26 #include <tools/link.hxx>
  27 #include <tools/urlobj.hxx>
  28
  29 namespace com { namespace sun { namespace star {
  30     namespace uno { class XComponentContext; }
  31     namespace uri { class XUriReference; }
  32 } } }
  33
  34 class CharClass;
  35
  36 namespace URIHelper {
  37
  38 /**
  39    @ATT
  40    Calling this function with defaulted arguments rMaybeFileHdl = Link() and
  41    bCheckFileExists = true often leads to results that are not intended:
  42    Whenever the given rTheBaseURIRef is a file URL, the given rTheRelURIRef is
  43    relative, and rTheRelURIRef could also be smart-parsed as a non-file URL
  44    (e.g., the relative URL "foo/bar" can be smart-parsed as "http://foo/bar"),
  45    then SmartRel2Abs called with rMaybeFileHdl = Link() and bCheckFileExists =
  46    true returns the non-file URL interpretation.  To avoid this, either pass
  47    some non-null rMaybeFileHdl if you want to check generated file URLs for
  48    existence (see URIHelper::GetMaybeFileHdl), or use bCheckFileExists = false
  49    if you want to generate file URLs without checking for their existence.
  50 */
  51 SVL_DLLPUBLIC OUString SmartRel2Abs(INetURLObject const & rTheBaseURIRef,
  52                                     OUString const & rTheRelURIRef,
  53                                     Link<OUString *, bool> const & rMaybeFileHdl = Link<OUString *, bool>(),
  54                                     bool bCheckFileExists = true,
  55                                     bool bIgnoreFragment = false,
  56                                     INetURLObject::EncodeMechanism eEncodeMechanism = INetURLObject::EncodeMechanism::WasEncoded,
  57                                     INetURLObject::DecodeMechanism eDecodeMechanism = INetURLObject::DecodeMechanism::ToIUri,
  58                                     rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8,
  59                                     FSysStyle eStyle = FSysStyle::Detect);
  60
  61 SVL_DLLPUBLIC void SetMaybeFileHdl(Link<OUString *, bool> const & rTheMaybeFileHdl);
  62
  63 SVL_DLLPUBLIC Link<OUString *, bool> const & GetMaybeFileHdl();
  64
  65 /**
  66    Converts a URI reference to a relative one, ignoring certain differences (for
  67    example, treating file URLs for case-ignoring file systems
  68    case-insensitively).
  69
  70    @param context a component context; must not be null
  71
  72    @param baseUriReference a base URI reference
  73
  74    @param uriReference a URI reference
  75
  76    @return a URI reference representing the given uriReference relative to the
  77    given baseUriReference; if the given baseUriReference is not an absolute,
  78    hierarchical URI reference, or the given uriReference is not a valid URI
  79    reference, null is returned
  80
  81    @exception std::bad_alloc if an out-of-memory condition occurs
  82
  83    @exception css::uno::RuntimeException if any error occurs
  84  */
  85 SVL_DLLPUBLIC css::uno::Reference< css::uri::XUriReference >
  86 normalizedMakeRelative(
  87     css::uno::Reference< css::uno::XComponentContext > const & context,
  88     OUString const & baseUriReference,
  89     OUString const & uriReference);
  90
  91 /**
  92    A variant of normalizedMakeRelative with a simplified interface.
  93
  94    Internally calls normalizedMakeRelative with the default component context.
  95
  96    @param baseUriReference a base URI reference, passed to
  97    normalizedMakeRelative
  98
  99    @param uriReference a URI reference, passed to normalizedMakeRelative
 100
 101    @return if the XUriReference returned by normalizedMakeRelative is empty,
 102    uriReference is returned unmodified; otherwise, the result of calling
 103    XUriReference::getUriReference on the XUriReference returned by
 104    normalizedMakeRelative is returned
 105
 106    @exception std::bad_alloc if an out-of-memory condition occurs
 107
 108    @exception css::uno::RuntimeException if any error occurs
 109
 110    @deprecated
 111    No code should rely on the default component context.
 112 */
 113 SVL_DLLPUBLIC OUString simpleNormalizedMakeRelative( OUString const & baseUriReference,
 114                                                      OUString const & uriReference);
 115
 116 SVL_DLLPUBLIC OUString FindFirstURLInText(OUString const & rText,
 117                                           sal_Int32 & rBegin,
 118                                           sal_Int32 & rEnd,
 119                                           CharClass const & rCharClass,
 120                                           INetURLObject::EncodeMechanism eMechanism = INetURLObject::EncodeMechanism::WasEncoded,
 121                                           rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
 122
 123 /** Remove any password component from both absolute and relative URLs.
 124
 125     @ATT  The current implementation will not remove a password from a
 126     relative URL that has an authority component (e.g., the password is not
 127     removed from the relative ftp URL <//user:password@domain/path>).  But
 128     since our functions to translate between absolute and relative URLs never
 129     produce relative URLs with authority components, this is no real problem.
 130
 131     @ATT  For relative URLs (or anything not recognized as an absolute URI),
 132     the current implementation will return the input unmodified, not applying
 133     any translations implied by the encode/decode parameters.
 134
 135     @param rURI  An absolute or relative URI reference.
 136
 137     @param eEncodeMechanism  See the general discussion for INetURLObject set-
 138     methods.
 139
 140     @param eDecodeMechanism  See the general discussion for INetURLObject get-
 141     methods.
 142
 143     @param eCharset  See the general discussion for INetURLObject get- and
 144     set-methods.
 145
 146     @return  The input URI with any password component removed.
 147  */
 148 SVL_DLLPUBLIC OUString removePassword(OUString const & rURI,
 149                                       INetURLObject::EncodeMechanism eEncodeMechanism,
 150                                       INetURLObject::DecodeMechanism eDecodeMechanism = INetURLObject::DecodeMechanism::ToIUri,
 151                                       rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
 152
 153 /** Resolve a URL's host component domain name in IDNA syntax to plain DNS
 154     syntax.
 155
 156     For details, see RFC 5890 "Internationalized Domain Names for Applications
 157     (IDNA): Definitions and Document Framework."
 158
 159     @param: url  An arbitrary string, should be a URI.
 160
 161     @return  If the input matches the syntax of a hierarchical URL, and it has
 162     a host component that matches the IDNA2008 domain name syntax, and that
 163     domain name contains any U-labels, return a version of the input URL with
 164     the host component resolved to plain DNS syntax.  Otherwise, return the
 165     input unchanged.
 166 */
 167 SVL_DLLPUBLIC OUString resolveIdnaHost(OUString const & url);
 168
 169 }
 170
 171 #endif // INCLUDED_SVL_URIHELPER_HXX
 172
 173 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */