blob: 0fabe1e170ecae76595562b13d23e7841b47b67b [file] [log] [blame]
* 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
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
#include "./types_fwd.hpp"
#include "./error.hpp"
#include <iosfwd>
struct pn_url_t;
namespace proton {
/// An error encountered during URL parsing.
PN_CPP_CLASS_EXTERN url_error : public error {
/// @cond INTERNAL
/// Construct a URL error with a message.
PN_CPP_EXTERN explicit url_error(const std::string&);
/// @endcond
/// A Proton URL.
/// Proton URLs take the form
/// `<scheme>://<username>:<password>@<host>:<port>/<path>`.
/// - Scheme can be `amqp` or `amqps`. Host is a DNS name or IP
/// address (v4 or v6).
/// - Port can be a number or a symbolic service name such as `amqp`.
/// - Path is normally used as a link source or target address. On a
/// broker it typically corresponds to a queue or topic name.
class url {
static const std::string AMQP; ///< "amqp" prefix
static const std::string AMQPS; ///< "amqps" prefix
// XXX No constructor for an empty URL?
// XXX What is the default 'defaults' behavior?
/// Parse `url_str` as an AMQP URL.
/// @note Converts automatically from string.
/// @throw url_error if URL is invalid.
PN_CPP_EXTERN url(const std::string& url_str);
/// @cond INTERNAL
/// XXX I want to understand why this is important to keep.
/// **Experimental** - Parse `url_str` as an AMQP URL. If
/// `defaults` is true, fill in defaults for missing values.
/// Otherwise, return an empty string for missing values.
/// @note Converts automatically from string.
/// @throw url_error if URL is invalid.
PN_CPP_EXTERN url(const std::string& url_str, bool defaults);
/// @endcond
/// Copy a URL.
PN_CPP_EXTERN url(const url&);
/// Copy a URL.
PN_CPP_EXTERN url& operator=(const url&);
/// True if the URL is empty.
PN_CPP_EXTERN bool empty() const;
/// Returns the URL as a string
PN_CPP_EXTERN operator std::string() const;
/// @name URL fields
/// @{
/// `amqp` or `amqps`.
PN_CPP_EXTERN std::string scheme() const;
/// The user name for authentication.
PN_CPP_EXTERN std::string user() const;
// XXX Passwords in URLs are dumb.
/// The password.
PN_CPP_EXTERN std::string password() const;
/// The host name or IP address.
PN_CPP_EXTERN std::string host() const;
/// `port` can be a number or a symbolic name such as "amqp".
PN_CPP_EXTERN std::string port() const;
/// `port_int` is the numeric value of the port.
PN_CPP_EXTERN uint16_t port_int() const;
/// host_port returns just the `host:port` part of the URL
PN_CPP_EXTERN std::string host_port() const;
// XXX is this not confusing (or incorrect)? The path starts with
// the first / after //.
/// `path` is everything after the final "/".
PN_CPP_EXTERN std::string path() const;
/// @}
pn_url_t* url_;
/// @cond INTERNAL
friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const url&);
// XXX Why is it important to have this?
/// Parse `url` from istream. This automatically fills in
/// defaults for missing values.
/// @note An invalid url is indicated by setting
/// std::stream::fail(), NOT by throwing url_error.
friend PN_CPP_EXTERN std::istream& operator>>(std::istream&, url&);
/// @endcond
} // proton
#endif // PROTON_URL_HPP