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