#ifndef ZYPP_URL_URLBASE_H
#define ZYPP_URL_URLBASE_H
-#include <zypp/url/UrlUtils.h>
-#include <zypp/base/PtrTypes.h>
+#include "zypp/url/UrlUtils.h"
+#include "zypp/base/PtrTypes.h"
//////////////////////////////////////////////////////////////////////
// ---------------------------------------------------------------
/**
- * Url::toString() view options.
+ * Url::asString() view options.
*
* A instance of this class represents a bit-wise combination
* of view option constants.
/**
* Create instance with default combination of view options.
*/
- ViewOption(): opt(DEFAULTS.opt)
- {}
+ ViewOption();
/**
}
private:
- ViewOption(int o): opt(o) {}
+ ViewOption(int option);
int opt;
};
*
* The UrlBase class implements default behaviour for URL
* manipulations and a base for implementation of scheme-
- * specialized URL's for the Url class.
+ * specialized URLs for the Url class.
*
*/
class UrlBase
* \brief Construct new object and initializes it with
* specified URL components.
*
- * \param scheme A scheme name.
- * \param authority A authority component data (encoded).
- * \param pathdata A path component data (encoded).
- * \param querystr A query string (encoded).
- * \param fragment A fragment component (encoded),
+ * \param scheme The scheme name.
+ * \param authority The encoded authority component data.
+ * \param pathdata The encoded path component data.
+ * \param querystr The encoded query string component.
+ * \param fragment The encoded fragment string component.
+ * \throws UrlNotAllowedException if one of the components
+ * is not allowed for the scheme.
+ * \throws UrlBadComponentException if one of the components
+ * contains an invalid character.
*/
UrlBase(const std::string &scheme,
const std::string &authority,
/**
* \brief Initializes current object with new URL components.
*
- * \param scheme A scheme name.
- * \param authority A authority component data (encoded).
- * \param pathdata A path component data (encoded).
- * \param querystr A query string (encoded).
- * \param fragment A fragment component (encoded),
+ * \param scheme The scheme name.
+ * \param authority The encoded authority component data.
+ * \param pathdata The encoded path component data.
+ * \param querystr The encoded query string component.
+ * \param fragment The encoded fragment string component.
+ * \throws UrlNotAllowedException if one of the components
+ * is not allowed in the scheme.
+ * \throws UrlBadComponentException if one of the components
+ * contains an invalid character.
*/
virtual void
init(const std::string &scheme,
* or compatible to).
*
* For example, if your derived class implements special
- * features of LDAP URL's, this method may return "ldap"
+ * features of LDAP URLs, this method may return "ldap"
* and "ldaps" scheme names.
*
* The UrlBase class returns an empty vector, that signals
- * that it is useable with all URL's.
+ * that it is useable with all URLs.
*
* \return A vector with scheme names known by this object.
*/
* \return A default string representation of the Url object.
*/
virtual std::string
- toString() const;
+ asString() const;
/**
* Returns a string representation of the Url object.
*
* To include a password in the resulting Url string, use:
* \code
- * url.toString(url::ViewOptions() +
- * url::ViewOptions::WITH_PASSWORD);
- * \endcode
- *
- * or its equivalent:
- *
- * \code
- * url.toString(url::ViewOptions::DEFAULTS +
+ * url.asString(url.getViewOptions() +
* url::ViewOptions::WITH_PASSWORD);
* \endcode
*
* \return A string representation of the Url object.
*/
virtual std::string
- toString(const zypp::url::ViewOptions &opts) const;
+ asString(const zypp::url::ViewOptions &opts) const;
// -----------------
* Returns the username from the URL authority.
* \param eflag Flag if the usename should be percent-decoded or not.
* \return The username sub-component from the URL authority.
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual std::string
getUsername(EEncoding eflag) const;
* Returns the password from the URL authority.
* \param eflag Flag if the password should be percent-decoded or not.
* \return The password sub-component from the URL authority.
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual std::string
getPassword(EEncoding eflag) const;
/**
* Returns the hostname or IP from the URL authority.
*
- * In case the Url contains an IP number, it may be surrounded
+ * In case the Url contains an IPv6 number, it is be surrounded
* by "[" and "]" characters, for example "[::1]" for an IPv6
* localhost address.
*
* \param eflag Flag if the host should be percent-decoded or not.
* \return The host sub-component from the URL authority.
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual std::string
getHost(EEncoding eflag) const;
/**
- * Returns the port from the URL authority.
+ * Returns the port number from the URL authority.
* \return The port sub-component from the URL authority.
*/
virtual std::string
* Returns the path name from the URL.
* \param eflag Flag if the path should be decoded or not.
* \return The path name sub-component without path parameters
- * from Path-Data component of the URL.
+ * from path data component of the URL.
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual std::string
getPathName(EEncoding eflag) const;
/**
- * Returns the path parameters from the URL.
+ * Returns the encoded path parameters from the URL.
* \return The encoded path parameters from the URL.
*/
virtual std::string
getPathParams() const;
/**
- * Returns a vector with path parameter substrings.
+ * Returns a vector with encoded path parameter substrings.
*
* The default path parameter separator is the \c ',' character.
* A schema specific object may overide the default separators.
* by default into a vector containing the substrings "foo=1" and
* "bar=2".
*
- * \return The path parameters splited into a vector of substrings.
+ * \return The encoded path parameters vector.
*/
virtual zypp::url::ParamVec
getPathParamsVec() const;
* \param eflag Flag if the path parameter keys and values should
* be decoded or not.
* \return The path parameters key and values as a string map.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual zypp::url::ParamMap
getPathParamsMap(EEncoding eflag) const;
* \param eflag Flag if the path parameter keys and values should
* be decoded or not.
* \return The value for the path parameter key or empty string.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual std::string
getPathParam(const std::string ¶m, EEncoding eflag) const;
* Returns the encoded query string component of the URL.
*
* The query string is returned without first "?" (separator)
- * character. Further "?" characters as in e.g. LDAP URL's
+ * character. Further "?" characters as in e.g. LDAP URLs
* remains in the returned string.
*
* \return The encoded query string component of the URL.
* \param eflag Flag if the query string keys and values should
* be decoded or not.
* \return The query string as a key/value string map.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual zypp::url::ParamMap
getQueryStringMap(EEncoding eflag) const;
* \param eflag Flag if the query parameter keys and values should
* be decoded or not.
* \return The value for the query parameter key or empty string.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual std::string
getQueryParam(const std::string ¶m, EEncoding eflag) const;
* Returns the encoded fragment component of the URL.
* \param eflag Flag if the fragment should be percent-decoded or not.
* \return The encoded fragment component of the URL.
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual std::string
getFragment(EEncoding eflag) const;
/**
* \brief Set the scheme name in the URL.
* \param scheme The new scheme name.
+ * \throws UrlBadComponentException if the \p scheme
+ * contains an invalid character or is empty.
*/
virtual void
setScheme(const std::string &scheme);
* "//" separator characters (just "user:pass@host:port").
*
* \param authority The authority component string.
+ * \throws UrlNotAllowedException if the \p authority
+ * has to be empty in for the current scheme.
+ * \throws UrlBadComponentException if the \p authority
+ * contains an invalid character.
+ * \throws UrlParsingException if \p authority parsing fails.
*/
virtual void
setAuthority(const std::string &authority);
* \brief Set the username in the URL authority.
* \param user The new username.
* \param eflag If the \p username is encoded or not.
+ * \throws UrlNotAllowedException if the \p user
+ * has to be empty in for the current scheme.
+ * \throws UrlBadComponentException if the \p user
+ * contains an invalid character.
*/
virtual void
setUsername(const std::string &user,
* \brief Set the password in the URL authority.
* \param pass The new password.
* \param eflag If the \p password is encoded or not.
+ * \throws UrlNotAllowedException if the \p pass
+ * has to be empty in for the current scheme.
+ * \throws UrlBadComponentException if the \p pass
+ * contains an invalid character.
*/
virtual void
setPassword(const std::string &pass,
* within square brackets (RFC3513, Sect. 2.2).
*
* A hostname may contain national alphanumeric UTF8 characters
- * (letters other than ASCII a-z0-9), that will be encoded.
+ * (letters other than ASCII a-zA-Z), that will be encoded.
* This function allows to specify both, a encoded or decoded
* hostname.
*
* Other IP literals in "[v ... ]" square bracket format are not
* supported by the implementation in UrlBase class.
*
- * \param host The new hostname or IP.
+ * \param host The new hostname or IP address.
+ * \throws UrlNotAllowedException if the \p host
+ * has to be empty in for the current scheme.
+ * \throws UrlBadComponentException if the \p host is invalid.
*/
virtual void
setHost(const std::string &host);
/**
* \brief Set the port number in the URL authority.
* \param port The new port number.
+ * \throws UrlNotAllowedException if the \p port
+ * has to be empty in for the current scheme.
+ * \throws UrlBadComponentException if the \p port is invalid.
*/
virtual void
setPort(const std::string &port);
* parameters separated by the ";" separator character.
*
* \param pathdata The encoded path data component string.
+ * \throws UrlBadComponentException if the \p pathdata
+ * contains an invalid character.
*/
virtual void
setPathData(const std::string &pathdata);
* \brief Set the path name.
* \param path The new path name.
* \param eflag If the \p path name is encoded or not.
+ * \throws UrlBadComponentException if the \p path name
+ * contains an invalid character.
*/
virtual void
setPathName(const std::string &path,
/**
* \brief Set the path parameters.
* \param params The new encoded path parameter string.
+ * \throws UrlBadComponentException if the path \p params
+ * contains an invalid character.
*/
virtual void
setPathParams(const std::string ¶ms);
/**
* \brief Set the path parameters.
* \param pvec The vector with encoded path parameters.
+ * \throws UrlBadComponentException if the \p pvec
+ * contains an invalid character.
*/
virtual void
setPathParamsVec(const zypp::url::ParamVec &pvec);
/**
* \brief Set the path parameters.
* \param pmap The map with decoded path parameters.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
*/
virtual void
setPathParamsMap(const zypp::url::ParamMap &pmap);
* \brief Set or add value for the specified path parameter.
* \param param The decoded path parameter name.
* \param value The decoded path parameter value.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual void
setPathParam(const std::string ¶m, const std::string &value);
/**
* \brief Set the query string in the URL.
*
+ * The \p querystr string parameter is supposed
+ * to not to contain the "?" URL query separator
+ * character (use just a "foo=bar&x=22" instead
+ * of "?foo=bar&x=22").
+ *
* \param querystr The new encoded query string.
+ * \throws UrlBadComponentException if the \p querystr
+ * contains an invalid character.
*/
virtual void
setQueryString(const std::string &querystr);
/**
* \brief Set the query parameters.
* \param qvec The vector with encoded query parameters.
+ * \throws UrlBadComponentException if the \p qvec
+ * contains an invalid character.
*/
virtual void
setQueryStringVec(const zypp::url::ParamVec &qvec);
/**
* \brief Set the query parameters.
* \param qmap The map with decoded query parameters.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
*/
virtual void
setQueryStringMap(const zypp::url::ParamMap &qmap);
* \brief Set or add value for the specified query parameter.
* \param param The decoded query parameter name.
* \param value The decoded query parameter value.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
*/
virtual void
setQueryParam(const std::string ¶m, const std::string &value);
+ /**
+ * \brief remove the specified query parameter.
+ * \param param The decoded query parameter name.
+ * \throws UrlNotSupportedException if parameter parsing
+ * is not supported for a URL (scheme).
+ * \throws UrlDecodingException if the decoded result string
+ * would contain a '\\0' character.
+ */
+ virtual void
+ delQueryParam(const std::string ¶m);
+
// -----------------
/**
* \brief Set the fragment string in the URL.
* \param fragment The new fragment string.
* \param eflag If the \p fragment is encoded or not.
+ * \throws UrlBadComponentException if the \p querystr
+ * contains an invalid character.
*/
virtual void
setFragment(const std::string &fragment,
* - Common path parameter separators:
* - \a \c sep_pathparams \c ";"
* Separator used to split path parameters from path name.
+ * Setting it to empty string disables splitting of path
+ * name and path parameters. Set also rx_pathparams to an
+ * empty string.
* - \a \c psep_pathparam \c ","
* Separator between path parameters.
* - \a \c vsep_pathparam \c "="
std::string
config(const std::string &opt) const;
- //protected:
- // friend class Url;
/**
* Set the value of a UrlBase configuration variable.
*
* Return the view options of the current object.
*
* This method is used to query the view options
- * used by the Url::toString() method.
+ * used by the asString() method.
*
* \return The current view option combination.
*/
* Change the view options of the current object.
*
* This method is used to change the view options
- * used by the Url::toString() method.
+ * used by the asString() method.
*
* \param vopts New view options combination.
*/
protected:
/**
- * Utility method to cleanup a path name.
+ * Utility method to cleanup an encoded path name.
*
- * By default, this method replaces multiple occurences
- * of the "/" characeter from the begining of the path,
- * so the cleaned path begins with at most one "/".
+ * By default, this method makes sure, that the first slash
+ * in the path is not encoded, and that the second slash
+ * before the first path segment, is encoded (to "%2F").
+ * It modifies the path in the url, for example:
+ * "ftp://host//aaa//bbb" to "ftp://host/%2Faaa//bbb"
+ * or as encoded path only also "%2f/name" to "/%2fname".
*
- * This operation is required in some cases to not to
- * missinterpret multiple "/" occurences as an empty
- * URL authority.
+ * This operation is required to fulfill the path-absolute
+ * rule of RFC3986, if there is no authority. It avoids the
+ * missinterpretation of the path as an authority separator.
*
- * \param path A path name to cleanup.
- * \return A path begining with at most one "/" character.
+ * It is not required if there is an authority ("//" behind
+ * the "scheme:"), that is in the path-abempty rule, but it
+ * is used e.g. in ftp url's defined by RFC1738.
+ *
+ * We apply this operation in both cases (for all paths),
+ * but if \p authority is true, the encoding of the second
+ * slash depends on the schema configuration (for ftp only).
+ *
+ * \param path The encoded path name to cleanup.
+ * \param authority Whether the url contains authority or not.
+ * \return A modified encoded path.
+ */
+ virtual std::string
+ cleanupPathName(const std::string &path, bool authority) const;
+
+ /**
+ * Utility method to cleanup an encoded path name.
+ *
+ * This variant of the method checks if the host component
+ * in the url is empty or not to differentiate if there is
+ * an authority.
+ *
+ * \param path The encoded path name to cleanup.
+ * \return A modified encoded path.
*/
virtual std::string
- cleanupPathName(const std::string &path);
+ cleanupPathName(const std::string &path) const;
/**
* \brief Verifies specified host or IP.
*
+ * It verifies, if the specified \p host parameter contains
+ * a hostname, an IPv4 address in dotted-decimal form or an
+ * IPv6 address literal encapsulated within square brackets
+ * (RFC3513, Sect. 2.2).
+ *
+ * A hostname in the \p host parameter, may contain national
+ * alphanumeric UTF8 characters (letters other than ASCII
+ * a-zA-Z) and allows to specify both, a encoded or decoded
+ * hostname.
+ *
* This function does not perform any hostname lookups and
- * supports only IPv6 addresses in "[ ... ]" notation.
+ * supports only IPv6 addresses in "[ ... ]" notation. The
+ * "[v ... ]" square bracket format is not supported by
+ * this implementation.
*
* \param host The host name or IP to verify.
* \return True, if host seems to be valid.
*/
virtual bool
- isValidHost(const std::string &host);
+ isValidHost(const std::string &host) const;
/**
* \brief Verifies specified port number.
* \return True, if port number is valid.
*/
virtual bool
- isValidPort(const std::string &port);
+ isValidPort(const std::string &port) const;
private:
UrlBaseData *m_data;
projects / platform / upstream / libzypp.git / blobdiff