/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* * This file is part of the LibreOffice project. * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. * * This file incorporates work covered by the following license notice: * * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed * with this work for additional information regarding copyright * ownership. The ASF licenses this file to you under the Apache * License, Version 2.0 (the "License"); you may not use this file * except in compliance with the License. You may obtain a copy of * the License at http://www.apache.org/licenses/LICENSE-2.0 .
*/ #ifndef INCLUDED_TOOLS_URLOBJ_HXX #define INCLUDED_TOOLS_URLOBJ_HXX
/** DOS notation (e.g., "a:\dir\file" and "\\server\dir\file").
*/
Dos = 0x4,
/** Detect the used notation.
@descr For the following descriptions, please note that whereas FSYS_DEFAULT includes all style bits, combinations of only a few style bits are also possible, and are also described.
@descr When used to translate a file system path to a file URL, the subset of the following productions for which the appropriate style bit is set are checked in order (using the conventions of RFC 2234, RFC 2396, and RFC 2732; UCS4 stands for any UCS4 character):
Production T3 (UNC; FSysStyle::Dos only): "\\" [host] ["\" *UCS4] becomes "file://" host "/" *UCS4 replacing "\" by "/" within <*UCS4>
Production T4 (Unix-like DOS; FSysStyle::Dos only): ALPHA ":" ["/" *UCS4] becomes "file:///" ALPHA ":/" *UCS4 replacing "\" by "/" within <*UCS4>
Production T5 (DOS; FSysStyle::Dos only): ALPHA ":" ["\" *UCS4] becomes "file:///" ALPHA ":/" *UCS4 replacing "\" by "/" within <*UCS4>
Production T6 (any): *UCS4 becomes "file:///" *UCS4 replacing the delimiter by "/" within <*UCS4>. The delimiter is that character from the set { "/", "\" } which appears most often in <*UCS4> (if FSysStyle::Unix is not among the style bits, "/" is removed from the set; if FSysStyle::Dos is not among the style bits, "\" is removed from the set). If two or more characters appear the same number of times, the character mentioned first in that set is chosen. If the first character of <*UCS4> is the delimiter, that character is not copied.
@descr When used to translate a file URL to a file system path, the following productions are checked in order (using the conventions of RFC 2234, RFC 2396, and RFC 2732):
Production F1 (VOS; FSysStyle::Vos): "file://" host "/" fpath ["#" fragment] becomes "//" host "/" fpath
Production F2 (DOS; FSysStyle::Dos): "file:///" ALPHA ":" ["/" fpath] ["#" fragment] becomes ALPHA ":" ["\" fpath] replacing "/" by "\" in <fpath>
class SAL_WARN_UNUSED TOOLS_DLLPUBLIC INetURLObject
{ public: // Get- and Set-Methods:
/** The way input strings that represent (parts of) URIs are interpreted in set-methods.
@descr UTF-32 characters in the range 0x80--0x10FFFF are replaced by sequences of escape sequences, representing the UTF-8 coded characters.
@descr Along with an EncodeMechanism parameter, the set-methods all take an rtl_TextEncoding parameter, which is ignored unless the EncodeMechanism is EncodeMechanism::WasEncoded.
*/ enumclass EncodeMechanism
{ /** All escape sequences that are already present are ignored, and are interpreted as literal sequences of three characters.
*/
All,
/** Sequences of escape sequences, that represent characters from the specified character set and that can be converted to UTF-32 characters, are first decoded. If they have to be encoded, they are converted to UTF-8 characters and are than translated into (sequences of) escape sequences. Other escape sequences are copied verbatim (but using upper case hex digits).
*/
WasEncoded,
/** All escape sequences that are already present are copied verbatim (but using upper case hex digits).
*/
NotCanonical
};
/** The way strings that represent (parts of) URIs are returned from get- methods.
@descr Along with a DecodeMechanism parameter, the get-methods all take an rtl_TextEncoding parameter, which is ignored unless the DecodeMechanism is DecodeMechanism::WithCharset or DecodeMechanism::Unambiguous.
*/ enumclass DecodeMechanism
{ /** The (part of the) URI is returned unchanged. Since URIs are written using a subset of US-ASCII, the returned string is guaranteed to contain only US-ASCII characters.
*/
NONE,
/** All sequences of escape sequences that represent UTF-8 coded UTF-32 characters with a numerical value greater than 0x7F, are replaced by the respective UTF-16 characters. All other escape sequences are not decoded.
*/
ToIUri,
/** All (sequences of) escape sequences that represent characters from the specified character set, and that can be converted to UTF-32, are replaced by the respective UTF-16 characters. All other escape sequences are not decoded.
*/
WithCharset,
/** All (sequences of) escape sequences that represent characters from the specified character set, that can be converted to UTF-32, and that (in the case of ASCII characters) can safely be decoded without altering the meaning of the (part of the) URI, are replaced by the respective UTF-16 characters. All other escape sequences are not decoded.
*/
Unambiguous
};
/** @descr If rTheRelURIRef cannot be converted to an absolute URL (because of syntactic reasons), either rTheRelURIRef or an empty string is returned: If all of the parameters eEncodeMechanism, eDecodeMechanism and eCharset have their respective default values, then rTheRelURIRef is returned unmodified; otherwise, an empty string is returned.
*/ static OUString
GetAbsURL(std::u16string_view rTheBaseURIRef,
OUString const & rTheRelURIRef,
EncodeMechanism eEncodeMechanism = EncodeMechanism::WasEncoded,
DecodeMechanism eDecodeMechanism = DecodeMechanism::ToIUri,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
/** Check if the scheme is one of the WebDAV scheme * we know about. * * @return true is one other scheme either public scheme or private scheme.
*/ bool isAnyKnownWebDAVScheme() const;
/** Return the URL 'prefix' for a given scheme.
@param eTheScheme One of the supported URL schemes.
@return The 'prefix' of URLs of the given scheme.
*/ staticconst OUString & GetScheme(INetProtocol eTheScheme);
/** Return the human-readable name for a given scheme.
@param eTheScheme One of the supported URL schemes.
@return The protocol name of URLs of the given scheme.
*/ staticconst OUString & GetSchemeName(INetProtocol eTheScheme);
/** A constant to address the last segment in various methods dealing with hierarchical paths.
@descr It is often more efficient to address the last segment using this constant, than to determine its ordinal value using getSegmentCount().
*/ enum { LAST_SEGMENT = -1 };
/** The number of segments in the hierarchical path.
@descr Using RFC 2396 and RFC 2234, a hierarchical path is of the form
hierarchical-path = 1*("/" segment)
segment = name *(";" param)
name = [base ["." extension]]
base = 1*pchar
extension = *<any pchar except ".">
param = *pchar
@param bIgnoreFinalSlash If true, a final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@return The number of segments in the hierarchical path. If the path is not hierarchical, 0 is returned.
*/
sal_Int32 getSegmentCount(bool bIgnoreFinalSlash = true) const;
/** Remove a segment from the hierarchical path.
@param nIndex The non-negative index of the segment, or LAST_SEGMENT if addressing the last segment.
@param bIgnoreFinalSlash If true, a final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@return True if the segment has successfully been removed (and the resulting URI is still valid). If the path is not hierarchical, or the specified segment does not exist, false is returned. If false is returned, the object is not modified.
*/ bool removeSegment(sal_Int32 nIndex = LAST_SEGMENT, bool bIgnoreFinalSlash = true);
/** Insert a new segment into the hierarchical path. A final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@param rTheName The name part of the new segment. The new segment will contain no parameters.
@param bAppendFinalSlash If the new segment is appended at the end of the hierarchical path, this parameter specifies whether to add a final slash after it or not.
@param nIndex The non-negative index of the segment before which to insert the new segment. LAST_SEGMENT or an nIndex that equals getSegmentCount() inserts the new segment at the end of the hierarchical path.
@param eMechanism See the general discussion for set-methods.
@param eCharset See the general discussion for set-methods.
@return True if the segment has successfully been inserted (and the resulting URI is still valid). If the path is not hierarchical, or the specified place to insert the new segment does not exist, false is returned. If false is returned, the object is not modified.
*/ bool insertName(std::u16string_view rTheName, bool bAppendFinalSlash = false,
sal_Int32 nIndex = LAST_SEGMENT,
EncodeMechanism eMechanism = EncodeMechanism::WasEncoded,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
/** Get the name of a segment of the hierarchical path.
@param nIndex The non-negative index of the segment, or LAST_SEGMENT if addressing the last segment.
@param bIgnoreFinalSlash If true, a final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@param eMechanism See the general discussion for get-methods.
@param eCharset See the general discussion for get-methods.
@return The name part of the specified segment. If the path is not hierarchical, or the specified segment does not exits, an empty string is returned.
*/
OUString getName(sal_Int32 nIndex = LAST_SEGMENT, bool bIgnoreFinalSlash = true,
DecodeMechanism eMechanism = DecodeMechanism::ToIUri,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8) const;
/** Set the name of the last segment (preserving any parameters and any query or fragment part).
@param rTheName The new name.
@param eMechanism See the general discussion for get-methods.
@param eCharset See the general discussion for get-methods.
@return True if the name has successfully been modified (and the resulting URI is still valid). If the path is not hierarchical, or a last segment does not exist, false is returned. If false is returned, the object is not modified.
*/ bool setName(std::u16string_view rTheName,
EncodeMechanism eMechanism = EncodeMechanism::WasEncoded,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
/** Get the base of the name of a segment.
@param nIndex The non-negative index of the segment, or LAST_SEGMENT if addressing the last segment.
@param bIgnoreFinalSlash If true, a final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@param eMechanism See the general discussion for get-methods.
@param eCharset See the general discussion for get-methods.
@return The base part of the specified segment. If the path is not hierarchical, or the specified segment does not exits, an empty string is returned.
*/
OUString getBase(sal_Int32 nIndex = LAST_SEGMENT, bool bIgnoreFinalSlash = true,
DecodeMechanism eMechanism = DecodeMechanism::ToIUri,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8) const;
/** Set the base of the name of a segment (preserving the extension). A final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@param rTheBase The new base.
@param nIndex The non-negative index of the segment, or LAST_SEGMENT if addressing the last segment.
@param eMechanism See the general discussion for set-methods.
@param eCharset See the general discussion for set-methods.
@return True if the base has successfully been modified (and the resulting URI is still valid). If the path is not hierarchical, or the specified segment does not exist, false is returned. If false is returned, the object is not modified.
*/ bool setBase(std::u16string_view rTheBase,
sal_Int32 nIndex = LAST_SEGMENT,
EncodeMechanism eMechanism = EncodeMechanism::WasEncoded,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
/** Determine whether the name of the last segment has an extension.
@return True if the name of the specified segment has an extension. If the path is not hierarchical, or the specified segment does not exist, false is returned.
*/ bool hasExtension() const;
/** Get the extension of the name of a segment.
@param nIndex The non-negative index of the segment, or LAST_SEGMENT if addressing the last segment.
@param bIgnoreFinalSlash If true, a final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@param eMechanism See the general discussion for get-methods.
@param eCharset See the general discussion for get-methods.
@return The extension part of the specified segment. If the path is not hierarchical, or the specified segment does not exits, an empty string is returned.
*/
OUString getExtension(sal_Int32 nIndex = LAST_SEGMENT, bool bIgnoreFinalSlash = true,
DecodeMechanism eMechanism = DecodeMechanism::ToIUri,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8) const;
/** Set the extension of the name of a segment (replacing an already existing extension).
@param rTheExtension The new extension.
@param nIndex The non-negative index of the segment, or LAST_SEGMENT if addressing the last segment.
@param bIgnoreFinalSlash If true, a final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@param eCharset See the general discussion for set-methods.
@return True if the extension has successfully been modified (and the resulting URI is still valid). If the path is not hierarchical, or the specified segment does not exist, false is returned. If false is returned, the object is not modified.
*/ bool setExtension(std::u16string_view rTheExtension,
sal_Int32 nIndex = LAST_SEGMENT, bool bIgnoreFinalSlash = true,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8);
/** Remove the extension of the name of a segment.
@param nIndex The non-negative index of the segment, or LAST_SEGMENT if addressing the last segment.
@param bIgnoreFinalSlash If true, a final slash at the end of the hierarchical path does not denote an empty segment, but is ignored.
@return True if the extension has successfully been removed (and the resulting URI is still valid), or if the name did not have an extension. If the path is not hierarchical, or the specified segment does not exist, false is returned. If false is returned, the object is not modified.
*/ bool removeExtension(sal_Int32 nIndex = LAST_SEGMENT, bool bIgnoreFinalSlash = true);
/** Determine whether the hierarchical path ends in a final slash.
@return True if the hierarchical path ends in a final slash. If the path is not hierarchical, false is returned.
*/ bool hasFinalSlash() const;
/** Make the hierarchical path end in a final slash (if it does not already do so).
@return True if a final slash has successfully been appended (and the resulting URI is still valid), or if the hierarchical path already ended in a final slash. If the path is not hierarchical, false is returned. If false is returned, the object is not modified.
*/ bool setFinalSlash();
/** Remove a final slash from the hierarchical path.
@return True if a final slash has successfully been removed (and the resulting URI is still valid), or if the hierarchical path already did not end in a final slash. If the path is not hierarchical, false is returned. If false is returned, the object is not modified.
*/ bool removeFinalSlash();
/** Return the file system path represented by a file URL (ignoring any fragment part).
@param eStyle The notation of the returned file system path.
@param pDelimiter Upon successful return, this parameter can return the character that is the 'main' delimiter within the returned file system path (e.g., "/" for Unix, "\" for DOS). This is especially useful for routines that later try to shorten the returned file system path at a 'good' position, e.g. to fit it into some limited display space.
@return The file system path represented by this file URL. If this file URL does not represent a file system path according to the specified notation, or if this is not a file URL at all, an empty string is returned.
*/
OUString getFSysPath(FSysStyle eStyle, sal_Unicode * pDelimiter = nullptr) const;
// Data URLs:
std::unique_ptr<SvMemoryStream> getData() const;
@param rText Some text (for its interpretation, see the general discussion for set-methods).
@param ePart The part says which characters are 'forbidden' and must be encoded (replaced by escape sequences). Characters outside the US- ASCII range are always 'forbidden.'
@param eMechanism See the general discussion for set-methods.
@param eCharset See the general discussion for set-methods.
@return The text, encoded according to the given mechanism and charset ('forbidden' characters replaced by escape sequences).
*/ static OUString encode( std::u16string_view rText, Part ePart,
EncodeMechanism eMechanism,
rtl_TextEncoding eCharset
= RTL_TEXTENCODING_UTF8);
/** Decode some text.
@param rText Some (encoded) text.
@param eMechanism See the general discussion for get-methods.
@param eCharset See the general discussion for get-methods.
@return The text, decoded according to the given mechanism and charset (escape sequences replaced by 'raw' characters).
*/ staticinline OUString decode(std::u16string_view rText,
DecodeMechanism eMechanism,
rtl_TextEncoding eCharset
= RTL_TEXTENCODING_UTF8);
@param eMechanism See the general discussion for get-methods.
@param eCharset See the general discussion for get-methods.
@return For a hierarchical URL, the last segment (everything after the last unencoded '/'). Note that this last segment may be empty. If the URL is not hierarchical, an empty string is returned.
*/
OUString GetLastName(DecodeMechanism eMechanism = DecodeMechanism::ToIUri,
rtl_TextEncoding eCharset = RTL_TEXTENCODING_UTF8) const;
/** Get the 'extension' of the last segment in the path.
@return For a hierarchical URL, everything after the first unencoded '.' in the last segment of the path. Note that this 'extension' may be empty. If the URL is not hierarchical, or if the last segment does not contain an unencoded '.', an empty string is returned.
*/
OUString GetFileExtension() const;
// INetProtocol::Macro, INetProtocol::Uno, INetProtocol::Slot, // vnd.sun.star.script, etc. All the types of URLs which shouldn't // be accepted from an outside controlled source bool IsExoticProtocol() const;
private: // General Structure:
class SAL_DLLPRIVATE SubString
{
sal_Int32 m_nBegin;
sal_Int32 m_nLength;
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
