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