include/cppuhelper/unourl.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 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_CPPUHELPER_UNOURL_HXX
  25 #define INCLUDED_CPPUHELPER_UNOURL_HXX
  26
  27 #include "sal/config.h"
  28
  29 #include "cppuhelper/cppuhelperdllapi.h"
  30
  31 namespace rtl
  32 {
  33 class OUString;
  34 }
  35
  36 namespace cppu
  37 {
  38 /** A descriptor as part of a UNO URL (connection descriptor or protocol
  39     descriptor).
  40
  41     Such a descriptor can also be useful outside the context of a full UNO URL.
  42     For example, some functions take a string representing a connection or
  43     protocol descriptor as input, and can use this class to parse the string.
  44  */
  45 class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC UnoUrlDescriptor
  46 {
  47 public:
  48     class Impl;
  49
  50     /** Construct a descriptor from a string representation.
  51
  52         @param rDescriptor
  53         The string representation of a descriptor.
  54
  55         @exception rtl::MalformedUriException
  56         Thrown when the given string representation is invalid.
  57      */
  58     explicit UnoUrlDescriptor(rtl::OUString const& rDescriptor);
  59
  60     UnoUrlDescriptor(UnoUrlDescriptor const& rOther);
  61
  62     ~UnoUrlDescriptor();
  63
  64     UnoUrlDescriptor& operator=(UnoUrlDescriptor const& rOther);
  65
  66     /** Return the string representation of the descriptor.
  67
  68         @return
  69         A reference to the string representation used to construct this
  70         descriptor, without any modifications.  The reference is valid for the
  71         lifetime of this URL object.
  72      */
  73     rtl::OUString const& getDescriptor() const;
  74
  75     /** Return the name component of the descriptor.
  76
  77         @return
  78         A reference to the (case insensitive) name, in lower case form.  The
  79         reference is valid for the lifetime of this URL object.
  80      */
  81     rtl::OUString const& getName() const;
  82
  83     /** Test whether the parameters contain a key.
  84
  85         @param
  86         rKey A (case insensitive) key.
  87
  88         @return
  89         True if the parameters contain a matching key/value pair.
  90      */
  91     bool hasParameter(rtl::OUString const& rKey) const;
  92
  93     /** Return the parameter value for a key.
  94
  95         @param
  96         rKey A (case insensitive) key.
  97
  98         @return
  99         The (case sensitive) value associated with the given key, or an empty
 100         string if there is no matching key/value pair.
 101      */
 102     rtl::OUString getParameter(rtl::OUString const& rKey) const;
 103
 104 private:
 105     Impl* m_pImpl;
 106 };
 107
 108 /** Parse UNO URLs into their components.
 109
 110     The ABNF for UNO URLs is as follows (see RFCs 2234, 2396, also see
 111     <http://udk.openoffice.org/common/man/spec/uno-url.html>):
 112
 113     uno-url = "UNO:" connection ";" protocol ";" object-name
 114     connection = descriptor
 115     protocol = descriptor
 116     descriptor = name *("," parameter)
 117     name = 1*alphanum
 118     parameter = key "=" value
 119     key = 1*alphanum
 120     value = *vchar
 121     valchar = unreserved / escaped / "$" / "&" / "+" / "/" / ":" / "?" / "@"
 122     object-name = 1*ochar
 123     ochar = unreserved / "$" / "&" / "+" / "," / "/" / ":" / "=" / "?" / "@"
 124
 125     Within a descriptor, the name and the keys are case insensitive, and within
 126     the parameter list all keys must be distinct.
 127
 128     Parameter values are encoded using UTF-8.  Note that parsing of parameter
 129     values as done by UnoUrl and UnoUrlDescriptor is not strict:  Invalid UTF-16
 130     entities in the input, as well as broken escape sequences ("%" not followed
 131     by two hex digits) are copied verbatim to the output, invalid bytes in the
 132     converted UTF-8 data are considered individual Unicode characters, and
 133     invalid UTF-16 entities in the resulting output (e.g., a high surrogate not
 134     followed by a low surrogate) are not detected.
 135  */
 136 class SAL_WARN_UNUSED CPPUHELPER_DLLPUBLIC UnoUrl
 137 {
 138 public:
 139     /** Construct a UNO URL from a string representation.
 140
 141         @param rUrl
 142         The string representation of a UNO URL.
 143
 144         @exception rtl::MalformedUriException
 145         Thrown when the given string representation is invalid.
 146      */
 147     explicit UnoUrl(rtl::OUString const& rUrl);
 148
 149     UnoUrl(UnoUrl const& rOther);
 150
 151     ~UnoUrl();
 152
 153     UnoUrl& operator=(UnoUrl const& rOther);
 154
 155     /** Return the connection descriptor component of the URL.
 156
 157         @return
 158         A reference to the connection descriptor.  The reference is valid for
 159         the lifetime of this URL object.
 160      */
 161     UnoUrlDescriptor const& getConnection() const;
 162
 163     /** Return the protocol descriptor component of the URL.
 164
 165         @return
 166         A reference to the protocol descriptor.  The reference is valid for the
 167         lifetime of this URL object.
 168      */
 169     UnoUrlDescriptor const& getProtocol() const;
 170
 171     /** Return the object-name component of the URL.
 172
 173         @return
 174         A reference to the (case sensitive) object-name.  The reference is valid
 175         for the lifetime of this URL object.
 176      */
 177     rtl::OUString const& getObjectName() const;
 178
 179 private:
 180     class Impl;
 181
 182     Impl* m_pImpl;
 183 };
 184 }
 185
 186 #endif // INCLUDED_RTL_UNOURL_HXX
 187
 188 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */