1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #if !defined INCLUDED_CPPUHELPER_UNOURL_HXX 25 #define INCLUDED_CPPUHELPER_UNOURL_HXX 26 27 #include <memory> 28 29 #include "cppuhelper/cppuhelperdllapi.h" 30 31 namespace rtl { class OUString; } 32 33 namespace cppu { 34 35 /** A descriptor as part of a UNO URL (connection descriptor or protocol 36 descriptor). 37 38 Such a descriptor can also be useful outside the context of a full UNO URL. 39 For example, some functions take a string representing a connection or 40 protocol descriptor as input, and can use this class to parse the string. 41 */ 42 class CPPUHELPER_DLLPUBLIC UnoUrlDescriptor 43 { 44 public: 45 /** @internal 46 */ 47 class Impl; 48 49 /** Construct a descriptor from a string representation. 50 51 @param rDescriptor 52 The string representation of a descriptor. 53 54 @exception rtl::MalformedUriException 55 Thrown when the given string representation is invalid. 56 */ 57 explicit UnoUrlDescriptor(rtl::OUString const & rDescriptor); 58 59 /** @internal 60 */ 61 explicit UnoUrlDescriptor(std::auto_ptr< Impl > & rImpl); 62 63 UnoUrlDescriptor(UnoUrlDescriptor const & rOther); 64 65 ~UnoUrlDescriptor(); 66 67 UnoUrlDescriptor & operator =(UnoUrlDescriptor const & rOther); 68 69 /** Return the string representation of the descriptor. 70 71 @return 72 A reference to the string representation used to construct this 73 descriptor, without any modifications. The reference is valid for the 74 lifetime of this URL object. 75 */ 76 rtl::OUString const & getDescriptor() const; 77 78 /** Return the name component of the descriptor. 79 80 @return 81 A reference to the (case insensitive) name, in lower case form. The 82 reference is valid for the lifetime of this URL object. 83 */ 84 rtl::OUString const & getName() const; 85 86 /** Test whether the parameters contain a key. 87 88 @param 89 A (case insensitive) key. 90 91 @return 92 True if the parameters contain a matching key/value pair. 93 */ 94 bool hasParameter(rtl::OUString const & rKey) const; 95 96 /** Return the parameter value for a key. 97 98 @param 99 A (case insensitive) key. 100 101 @return 102 The (case sensitive) value associated with the given key, or an empty 103 string if there is no matching key/value pair. 104 */ 105 rtl::OUString getParameter(rtl::OUString const & rKey) const; 106 107 private: 108 std::auto_ptr< Impl > m_xImpl; 109 }; 110 111 /** Parse UNO URLs into their components. 112 113 The ABNF for UNO URLs is as follows (see RFCs 2234, 2396, also see 114 <http://udk.openoffice.org/common/man/spec/uno-url.html>): 115 116 uno-url = "UNO:" connection ";" protocol ";" object-name 117 connection = descriptor 118 protocol = descriptor 119 descriptor = name *("," parameter) 120 name = 1*alphanum 121 parameter = key "=" value 122 key = 1*alphanum 123 value = *vchar 124 valchar = unreserved / escaped / "$" / "&" / "+" / "/" / ":" / "?" / "@" 125 object-name = 1*ochar 126 ochar = unreserved / "$" / "&" / "+" / "," / "/" / ":" / "=" / "?" / "@" 127 128 Within a descriptor, the name and the keys are case insensitive, and within 129 the parameter list all keys must be distinct. 130 131 Parameter values are encoded using UTF-8. Note that parsing of parameter 132 values as done by UnoUrl and UnoUrlDescriptor is not strict: Invalid UTF-16 133 entities in the input, as well as broken escape sequences ("%" not followed 134 by two hex digits) are copied verbatim to the output, invalid bytes in the 135 converted UTF-8 data are considered individual Unicode characters, and 136 invalid UTF-16 entities in the resulting output (e.g., a high surrogate not 137 followed by a low surrogate) are not detected. 138 */ 139 class CPPUHELPER_DLLPUBLIC UnoUrl 140 { 141 public: 142 /** Construct a UNO URL from a string representation. 143 144 @param rUrl 145 The string representation of a UNO URL. 146 147 @exception rtl::MalformedUriException 148 Thrown when the given string representation is invalid. 149 */ 150 explicit UnoUrl(rtl::OUString const & rUrl); 151 152 UnoUrl(UnoUrl const & rOther); 153 154 ~UnoUrl(); 155 156 UnoUrl & operator =(UnoUrl const & rOther); 157 158 /** Return the connection descriptor component of the URL. 159 160 @return 161 A reference to the connection descriptor. The reference is valid for 162 the lifetime of this URL object. 163 */ 164 UnoUrlDescriptor const & getConnection() const; 165 166 /** Return the protocol descriptor component of the URL. 167 168 @return 169 A reference to the protocol descriptor. The reference is valid for the 170 lifetime of this URL object. 171 */ 172 UnoUrlDescriptor const & getProtocol() const; 173 174 /** Return the object-name component of the URL. 175 176 @return 177 A reference to the (case sensitive) object-name. The reference is valid 178 for the lifetime of this URL object. 179 */ 180 rtl::OUString const & getObjectName() const; 181 182 private: 183 class Impl; 184 185 std::auto_ptr< Impl > m_xImpl; 186 }; 187 188 } 189 190 #endif // INCLUDED_RTL_UNOURL_HXX 191