zypp/Url.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /**
  10  * \file zypp/Url.h
  11  */
  12 #ifndef   ZYPP_URL_H
  13 #define   ZYPP_URL_H
  14
  15 #include <zypp/url/UrlBase.h>
  16 #include <zypp/url/UrlUtils.h>
  17
  18
  19 //////////////////////////////////////////////////////////////////////
  20 namespace zypp
  21 { ////////////////////////////////////////////////////////////////////
  22
  23   class Url;
  24   namespace hotfix1050625 {
  25     std::string asString( const Url & url_r );
  26   }
  27   namespace filesystem {
  28     class Pathname;
  29   }
  30   using filesystem::Pathname;
  31
  32   /**
  33    * \class Url
  34    * \brief Url manipulation class.
  35    *
  36    * The generic URL (URI) syntax and its main components are defined in
  37    * RFC3986 (http://rfc.net/rfc3986.html) Section 3, "Syntax Components".
  38    * The scheme specific URL syntax and semantics is defined in the
  39    * specification of the particular scheme. See also RFC1738
  40    * (http://rfc.net/rfc1738.html), that defines specific syntax for
  41    * several URL schemes.
  42    *
  43    * This class provides methods to access and manipulate generic and
  44    * common scheme-specific URL components (or using the more general
  45    * term, URI components).
  46    * To consider the scheme-specifics of a URL, the Url class contains
  47    * a reference object pointing to a UrlBase or derived object, that
  48    * implements the scheme specifics.
  49    *
  50    * Using the Url::registerScheme() method, it is possible to register
  51    * a preconfigured or derived UrlBase object for a specific scheme
  52    * name. The registered object will be cloned to handle all URLs
  53    * containing the specified scheme name.
  54    *
  55    * \par RFC3986, Syntax Components:
  56    *
  57    * The generic URI syntax consists of a hierarchical sequence of
  58    * components referred to as the scheme, authority, path, query,
  59    * and fragment.
  60    *
  61    * \code
  62    *    URI         = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
  63    *
  64    *    hier-part   = "//" authority path-abempty
  65    *                / path-absolute
  66    *                / path-rootless
  67    *                / path-empty
  68    * \endcode
  69    *
  70    * The scheme and path components are required, though the path may be
  71    * empty (no characters).
  72    * When authority is present, the path must either be empty or begin
  73    * with a slash ("/") character.
  74    * When authority is not present, the path cannot begin with two slash
  75    * characters ("//").
  76    * These restrictions result in five different ABNF rules for a path
  77    * (Section 3.3), only one of which will match any given URI reference.
  78    *
  79    * The following are two example URIs and their component parts:
  80    * \code
  81    *      foo://example.com:8042/over/there?name=ferret#nose
  82    *      \_/   \______________/\_________/ \_________/ \__/
  83    *       |           |            |            |        |
  84    *    scheme     authority       path        query   fragment
  85    *       |   _____________________|__
  86    *      / \ /                        \
  87    *      urn:example:animal:ferret:nose
  88    * \endcode
  89    *
  90    */
  91   class Url
  92   {
  93   public:
  94     /**
  95      * Encoding flags.
  96      */
  97     typedef zypp::url::EEncoding    EEncoding;
  98
  99     /**
 100      * View options.
 101      */
 102     typedef zypp::url::ViewOptions  ViewOptions;
 103
 104
 105     ~Url();
 106     Url();
 107
 108     /**
 109      * Create a new Url object as shared copy of the given one.
 110      *
 111      * Upon return, both objects will point to the same underlying
 112      * object. This state will remain until one of the object is
 113      * modified.
 114      *
 115      * \param url The Url object to make a copy of.
 116      * \throws url::UrlException if copy fails (should not happen).
 117      */
 118     Url(const Url &url);
 119
 120
 121     /**
 122      * Create a new Url object as shared copy of the given reference.
 123      *
 124      * Upon return, both objects will point to the same underlying
 125      * object. This state will remain until one of the object is
 126      * modified.
 127      *
 128      * \param url The URL implementation reference to make a copy of.
 129      * \throws url::UrlException if reference is empty.
 130      */
 131     Url(const zypp::url::UrlRef &url);
 132
 133
 134     /**
 135      * \brief Construct a Url object from percent-encoded URL string.
 136      *
 137      * Parses the \p encodedUrl string using the parseUrl() method
 138      * and assigns the result to the newly created object.
 139      *
 140      * \param encodedUrl A percent-encoded URL string.
 141      * \throws url::UrlParsingException if parsing of the url fails.
 142      * \throws url::UrlNotAllowedException if one of the components
 143      *         is not allowed for the scheme.
 144      * \throws url::UrlBadComponentException if one of the components
 145      *         contains an invalid character.
 146      */
 147     Url(const std::string &encodedUrl);
 148
 149
 150     // -----------------
 151     /**
 152      * \brief Parse a percent-encoded URL string.
 153      *
 154      * Tries to parse the given string into generic URL components
 155      * and creates a clone of a scheme-specialized object or a new
 156      * UrlBase object.
 157      *
 158      * \param encodedUrl A percent-encoded URL string.
 159      * \return           A reference to a (derived) UrlBase object or
 160      *                   empty reference if the \p encodedUrl string
 161      *                   does not match the generic URL syntax.
 162      * \throws url::UrlNotAllowedException if one of the components
 163      *         is not allowed for the scheme.
 164      * \throws url::UrlBadComponentException if one of the components
 165      *         contains an invalid character.
 166      */
 167     static url::UrlRef
 168     parseUrl(const std::string &encodedUrl);
 169
 170
 171     // -----------------
 172     /**
 173      * \brief Assigns parsed percent-encoded URL string to the object.
 174      *
 175      * Parses \p encodedUrl string using the parseUrl() method
 176      * and assigns the result to the current object.
 177      *
 178      * \param encodedUrl A percent-encoded URL string.
 179      * \return A reference to this Url object.
 180      * \throws url::UrlParsingException if parsing of the url fails.
 181      * \throws url::UrlNotAllowedException if one of the components
 182      *         is not allowed for the scheme.
 183      * \throws url::UrlBadComponentException if one of the components
 184      *         contains an invalid character.
 185      */
 186     Url&
 187     operator = (const std::string &encodedUrl);
 188
 189
 190     /**
 191      * \brief Assign a shared copy of \p url to the current object.
 192      *
 193      * Upon return, both objects will point to the same underlying
 194      * object. This state will remain until one of the objects is
 195      * modified.
 196      *
 197      * \param url The Url object to make a copy of.
 198      * \return A reference to this Url object.
 199      */
 200     Url&
 201     operator = (const Url &url);
 202
 203
 204     // -----------------
 205     /**
 206      * \brief Register a scheme-specific implementation.
 207      *
 208      * \param scheme  A name of a scheme.
 209      * \param urlImpl A UrlBase object specialized for this scheme.
 210      * \return True, if the object claims to implement the scheme.
 211      */
 212     static bool
 213     registerScheme(const std::string &scheme,
 214                    url::UrlRef       urlImpl);
 215
 216     /**
 217      * \brief Returns all registered scheme names.
 218      * \return A vector with registered URL scheme names.
 219      */
 220     static zypp::url::UrlSchemes
 221     getRegisteredSchemes();
 222
 223     /**
 224      * \brief Returns if scheme name is registered.
 225      * \return True, if scheme name is registered.
 226      */
 227     static bool
 228     isRegisteredScheme(const std::string &scheme);
 229
 230
 231     // -----------------
 232     /**
 233      * \brief Returns scheme names known to this object.
 234      * \return A vector with scheme names known by this object.
 235      */
 236     zypp::url::UrlSchemes
 237     getKnownSchemes() const;
 238
 239
 240     /**
 241      * \brief Verifies the specified scheme name.
 242      *
 243      * Verifies the generic syntax of the specified \p scheme name
 244      * and if it is contained in the current object's list of known
 245      * schemes (see getKnownSchemes()) if the list is not empty.
 246      *
 247      * The default implementation in the UrlBase class returns an
 248      * emtpy list of known schemes, causing a check of the generic
 249      * syntax only.
 250      *
 251      * \return True, if generic scheme name syntax is valid and
 252      *         the scheme name is known to the current object.
 253      */
 254     bool
 255     isValidScheme(const std::string &scheme) const;
 256
 257
 258     /** hd cd dvd dir file iso */
 259     static bool schemeIsLocal( const std::string & scheme_r );
 260     /** \overload nonstatic version */
 261     bool schemeIsLocal() const { return schemeIsLocal( getScheme() ); }
 262
 263     /** nfs nfs4 smb cifs http https ftp sftp tftp */
 264     static bool schemeIsRemote( const std::string & scheme_r );
 265     /** \overload nonstatic version */
 266     bool schemeIsRemote() const { return schemeIsRemote( getScheme() ); }
 267
 268     /** cd dvd */
 269     static bool schemeIsVolatile( const std::string & scheme_r );
 270     /** \overload nonstatic version */
 271     bool schemeIsVolatile() const { return schemeIsVolatile( getScheme() ); }
 272
 273     /** http https ftp sftp tftp */
 274     static bool schemeIsDownloading( const std::string & scheme_r );
 275     /** \overload nonstatic version */
 276     bool schemeIsDownloading() const { return schemeIsDownloading( getScheme() ); }
 277
 278     /**
 279      * \brief Verifies the Url.
 280      *
 281      * Verifies if the current object contains a non-empty scheme
 282      * name. Additional semantical URL checks may be performed by
 283      * derived UrlBase objects.
 284      *
 285      * \return True, if the Url seems to be valid.
 286      */
 287     bool
 288     isValid() const;
 289
 290
 291     // -----------------
 292     /**
 293      * Returns a default string representation of the Url object.
 294      *
 295      * By default, a password in the URL will be hidden.
 296      *
 297      * \return A default string representation of the Url object.
 298      */
 299     std::string
 300     asString() const;
 301
 302     /**
 303      * Returns a string representation of the Url object.
 304      *
 305      * To include a password in the resulting Url string, use:
 306      * \code
 307      *    url.asString(url.getViewOptions() +
 308      *                 url::ViewOptions::WITH_PASSWORD);
 309      * \endcode
 310      *
 311      * \param opts  A combination of view options.
 312      * \return A string representation of the Url object.
 313      */
 314     std::string
 315     asString(const ViewOptions &opts) const;
 316
 317     /**
 318      * Returns a complete string representation of the Url object.
 319      *
 320      * This function ignores the configuration of the view options
 321      * in the current object (see setViewOption()) and forces to
 322      * return a string with all URL components included.
 323      *
 324      * \return A complete string representation of the Url object.
 325      */
 326     std::string
 327     asCompleteString() const;
 328
 329
 330     // -----------------
 331     /**
 332      * Returns the scheme name of the URL.
 333      * \return Scheme name of the current Url object.
 334      */
 335     std::string
 336     getScheme() const;
 337
 338
 339     // -----------------
 340     /**
 341      * Returns the encoded authority component of the URL.
 342      *
 343      * The returned authority string does not contain the leading
 344      * "//" separator characters, but just its "user:pass@host:port"
 345      * content only.
 346      *
 347      * \return The encoded authority component string.
 348      */
 349     std::string
 350     getAuthority() const;
 351
 352     /**
 353      * Returns the username from the URL authority.
 354      * \param eflag Flag if the usename should be percent-decoded or not.
 355      * \return The username sub-component from the URL authority.
 356      * \throws url::UrlDecodingException if the decoded result string
 357      *         would contain a '\\0' character.
 358      */
 359     std::string
 360     getUsername(EEncoding eflag = zypp::url::E_DECODED) const;
 361
 362     /**
 363      * Returns the password from the URL authority.
 364      * \param eflag Flag if the password should be percent-decoded or not.
 365      * \return The password sub-component from the URL authority.
 366      * \throws url::UrlDecodingException if the decoded result string
 367      *         would contain a '\\0' character.
 368      */
 369     std::string
 370     getPassword(EEncoding eflag = zypp::url::E_DECODED) const;
 371
 372     /**
 373      * Returns \c true if username \b and password are encoded in the authority component.
 374      */
 375     bool hasCredentialsInAuthority() const
 376     { return ! ( getUsername().empty() || getPassword().empty() ); }
 377
 378     /**
 379      * Returns the hostname or IP from the URL authority.
 380      *
 381      * In case the Url contains an IP number, it may be surrounded
 382      * by "[" and "]" characters, for example "[::1]" for an IPv6
 383      * localhost address.
 384      *
 385      * \param eflag Flag if the host should be percent-decoded or not.
 386      * \return The host sub-component from the URL authority.
 387      * \throws url::UrlDecodingException if the decoded result string
 388      *         would contain a '\\0' character.
 389      */
 390     std::string
 391     getHost(EEncoding eflag = zypp::url::E_DECODED) const;
 392
 393     /**
 394      * Returns the port from the URL authority.
 395      * \return The port sub-component from the URL authority.
 396      */
 397     std::string
 398     getPort() const;
 399
 400
 401     // -----------------
 402     /**
 403      * Returns the encoded path component of the URL.
 404      *
 405      * The path data contains the path name, optionally
 406      * followed by path parameters separated with a ";"
 407      * character, for example "/foo/bar;version=1.1".
 408      *
 409      * \return The encoded path component of the URL.
 410      */
 411     std::string
 412     getPathData() const;
 413
 414     /**
 415      * Returns the path name from the URL.
 416      * \param eflag Flag if the path should be decoded or not.
 417      * \return The path name sub-component without path parameters
 418      *  from Path-Data component of the URL.
 419      * \throws url::UrlDecodingException if the decoded result string
 420      *         would contain a '\\0' character.
 421      */
 422     std::string
 423     getPathName(EEncoding eflag = zypp::url::E_DECODED) const;
 424
 425     /**
 426      * Returns the path parameters from the URL.
 427      * \return The encoded path parameters from the URL.
 428      */
 429     std::string
 430     getPathParams() const;
 431
 432     /**
 433      * Returns a vector with path parameter substrings.
 434      *
 435      * The default path parameter separator is the \c ',' character.
 436      * A schema specific object may overide the default separators.
 437      *
 438      * For example, the path parameters string "foo=1,bar=2" is splited
 439      * by default into a vector containing the substrings "foo=1" and
 440      * "bar=2".
 441      *
 442      * \return The path parameters splited into a vector of substrings.
 443      */
 444     zypp::url::ParamVec
 445     getPathParamsVec() const;
 446
 447     /**
 448      * Returns a string map with path parameter keys and values.
 449      *
 450      * The default path parameter separator is the \c ',' character,
 451      * the default key/value separator for the path parameters is
 452      * the \c '=' character.
 453      * A schema specific object may overide the default separators.
 454      *
 455      * For example, the path parameters string "foo=1,bar=2" is splited
 456      * into a map containing "foo" = "1" and "bar" = "2" by default.
 457      *
 458      * \param eflag Flag if the path parameter keys and values should
 459      *               be decoded or not.
 460      * \return The path parameters key and values as a string map.
 461      * \throws url::UrlNotSupportedException if parameter parsing
 462      *         is not supported for a URL (scheme).
 463      * \throws url::UrlDecodingException if the decoded result string
 464      *         would contain a '\\0' character.
 465      */
 466     zypp::url::ParamMap
 467     getPathParamsMap(EEncoding eflag = zypp::url::E_DECODED) const;
 468
 469     /**
 470      * Return the value for the specified path parameter.
 471      *
 472      * For example, if the path parameters string is "foo=1,bar=2"
 473      * the method will return the substring "1" for the param key
 474      * "foo" and "2" for the param key "bar".
 475      *
 476      * \param param The path parameter key.
 477      * \param eflag Flag if the path parameter keys and values should
 478      *              be decoded or not.
 479      * \return The value for the path parameter key or empty string.
 480      * \throws url::UrlNotSupportedException if parameter parsing
 481      *         is not supported for a URL (scheme).
 482      * \throws url::UrlDecodingException if the decoded result string
 483      *         would contain a '\\0' character.
 484      */
 485     std::string
 486     getPathParam(const std::string &param,
 487                  EEncoding eflag = zypp::url::E_DECODED) const;
 488
 489
 490     // -----------------
 491     /**
 492      * Returns the encoded query string component of the URL.
 493      *
 494      * The query string is returned without first "?" (separator)
 495      * character. Further "?" characters as in e.g. LDAP URLs
 496      * remain in the returned string.
 497      *
 498      * \return The encoded query string component of the URL.
 499      */
 500     std::string
 501     getQueryString() const;
 502
 503     /**
 504      * Returns a vector with query string parameter substrings.
 505      *
 506      * The default query string parameter separator is the \c '&'
 507      * character.
 508      * A schema specific object may overide the default separators.
 509      *
 510      * For example, the query string "foo=1&bar=2" is splited by
 511      * default into a vector containing the substrings "foo=1" and
 512      * "bar=2".
 513      *
 514      * \return The query string splited into a vector of substrings.
 515      */
 516     zypp::url::ParamVec
 517     getQueryStringVec() const;
 518
 519     /**
 520      * Returns a string map with query parameter and their values.
 521      *
 522      * The default query string parameter separator is the \c ','
 523      * character, the default key/value separator the \c '=' character.
 524      * A schema specific object may overide the default separators.
 525      *
 526      * For example, the query string "foo=1&bar=2" is splited by
 527      * default into a map containing "foo" = "1" and "bar" = "2".
 528      *
 529      * \param eflag Flag if the query string keys and values should
 530      *               be decoded or not.
 531      * \return The query string as a key/value string map.
 532      * \throws url::UrlNotSupportedException if parameter parsing
 533      *         is not supported for a URL (scheme).
 534      * \throws url::UrlDecodingException if the decoded result string
 535      *         would contain a '\\0' character.
 536      */
 537     zypp::url::ParamMap
 538     getQueryStringMap(EEncoding eflag = zypp::url::E_DECODED) const;
 539
 540     /**
 541      * Return the value for the specified query parameter.
 542      *
 543      * For example, if the query string is "foo=1,bar=2" the method
 544      * will return the substring "1" for the param key "foo" and
 545      * "2" for the param key "bar".
 546      *
 547      * \param param The query parameter key.
 548      * \param eflag Flag if the query parameter keys and values should
 549      *              be decoded or not.
 550      * \return The value for the query parameter key or empty string.
 551      * \throws url::UrlNotSupportedException if parameter parsing
 552      *         is not supported for a URL (scheme).
 553      * \throws url::UrlDecodingException if the decoded result string
 554      *         would contain a '\\0' character.
 555      */
 556     std::string
 557     getQueryParam(const std::string &param,
 558                   EEncoding eflag = zypp::url::E_DECODED) const;
 559
 560
 561     // -----------------
 562     /**
 563      * Returns the encoded fragment component of the URL.
 564      * \param eflag Flag if the fragment should be percent-decoded or not.
 565      * \return The encoded fragment component of the URL.
 566      * \throws url::UrlDecodingException if the decoded result string
 567      *         would contain a '\\0' character.
 568      */
 569     std::string
 570     getFragment(EEncoding eflag = zypp::url::E_DECODED) const;
 571
 572
 573     // -----------------
 574     /**
 575      * \brief Set the scheme name in the URL.
 576      * \param scheme The new scheme name.
 577      * \throws url::UrlBadComponentException if the \p scheme
 578      *         contains an invalid character or is empty.
 579      */
 580     void
 581     setScheme(const std::string &scheme);
 582
 583
 584     // -----------------
 585     /**
 586      * \brief Set the authority component in the URL.
 587      *
 588      * The \p authority string shoud contain the "user:pass@host:port"
 589      * sub-components without any leading "//" separator characters.
 590      *
 591      * \param authority The encoded authority component string.
 592      * \throws url::UrlNotAllowedException if the \p authority
 593      *         has to be empty in for the current scheme.
 594      * \throws url::UrlBadComponentException if the \p authority
 595      *         contains an invalid character.
 596      * \throws url::UrlParsingException if \p authority parsing fails.
 597      */
 598     void
 599     setAuthority(const std::string &authority);
 600
 601     /**
 602      * \brief Set the username in the URL authority.
 603      * \param user  The new username.
 604      * \param eflag If the \p username is encoded or not.
 605      * \throws url::UrlNotAllowedException if the \p user
 606      *         has to be empty in for the current scheme
 607      * \throws url::UrlBadComponentException if the \p user
 608      *         contains an invalid character.
 609      */
 610     void
 611     setUsername(const std::string &user,
 612                 EEncoding         eflag = zypp::url::E_DECODED);
 613
 614     /**
 615      * \brief Set the password in the URL authority.
 616      * \param pass  The new password.
 617      * \param eflag If the \p password is encoded or not.
 618      * \throws url::UrlNotAllowedException if the \p pass
 619      *         has to be empty in for the current scheme.
 620      * \throws url::UrlBadComponentException if the \p pass
 621      *         contains an invalid character.
 622      */
 623     void
 624     setPassword(const std::string &pass,
 625                 EEncoding         eflag = zypp::url::E_DECODED);
 626
 627     /**
 628      * \brief Set the hostname or IP in the URL authority.
 629      *
 630      * The \p host parameter may contain a hostname, an IPv4 address
 631      * in dotted-decimal form or an IPv6 address literal encapsulated
 632      * within square brackets (RFC3513, Sect. 2.2).
 633      *
 634      * A hostname may contain national alphanumeric UTF8 characters
 635      * (letters other than ASCII a-z0-9), that will be encoded.
 636      * This function allows to specify both, a encoded or decoded
 637      * hostname.
 638      *
 639      * Other IP literals in "[v ... ]" square bracket format are not
 640      * supported by the implementation in UrlBase class.
 641      *
 642      * \param host The new hostname or IP address.
 643      * \throws url::UrlNotAllowedException if the \p host (authority)
 644      *         has to be empty in for the current scheme.
 645      * \throws url::UrlBadComponentException if the \p host is invalid.
 646      */
 647     void
 648     setHost(const std::string &host);
 649
 650     /**
 651      * \brief Set the port number in the URL authority.
 652      * \param port The new port number.
 653      * \throws url::UrlNotAllowedException if the \p port (authority)
 654      *         has to be empty in for the current scheme.
 655      * \throws url::UrlBadComponentException if the \p port is invalid.
 656      */
 657     void
 658     setPort(const std::string &port);
 659
 660
 661     // -----------------
 662     /**
 663      * \brief Set the path data component in the URL.
 664      *
 665      * By default, the \p pathdata string may include path
 666      * parameters separated by the ";" separator character.
 667      *
 668      * \param pathdata The encoded path data component string.
 669      * \throws url::UrlBadComponentException if the \p pathdata
 670      *         contains an invalid character.
 671      */
 672     void
 673     setPathData(const std::string &pathdata);
 674
 675     /**
 676      * \brief Set the path name.
 677      * \param path  The new path name.
 678      * \param eflag If the \p path name is encoded or not.
 679      * \throws url::UrlBadComponentException if the \p path name
 680      *         contains an invalid character.
 681      */
 682     void
 683     setPathName(const std::string &path,
 684                 EEncoding         eflag = zypp::url::E_DECODED);
 685     /** \overload */
 686     void
 687     setPathName(const Pathname &path,
 688                 EEncoding         eflag = zypp::url::E_DECODED);
 689     /** \overload */
 690     void
 691     setPathName(const char *path,
 692                 EEncoding         eflag = zypp::url::E_DECODED);
 693
 694     /**
 695      * \brief Extend the path name.
 696      */
 697     void appendPathName( const Pathname & path_r, EEncoding eflag_r = zypp::url::E_DECODED );
 698
 699     /**
 700      * \brief Set the path parameters.
 701      * \param params The new encoded path parameter string.
 702      * \throws url::UrlBadComponentException if the path \p params
 703      *         contains an invalid character.
 704      */
 705     void
 706     setPathParams(const std::string &params);
 707
 708     /**
 709      * \brief Set the path parameters.
 710      * \param pvec The vector with encoded path parameters.
 711      * \throws url::UrlBadComponentException if the \p pvec
 712      *         contains an invalid character.
 713      */
 714     void
 715     setPathParamsVec(const zypp::url::ParamVec &pvec);
 716
 717     /**
 718      * \brief Set the path parameters.
 719      * \param pmap The map with decoded path parameters.
 720      * \throws url::UrlNotSupportedException if parameter parsing
 721      *         is not supported for a URL (scheme).
 722      */
 723     void
 724     setPathParamsMap(const zypp::url::ParamMap &pmap);
 725
 726     /**
 727      * \brief Set or add value for the specified path parameter.
 728      * \param param The decoded path parameter name.
 729      * \param value The decoded path parameter value.
 730      * \throws url::UrlNotSupportedException if parameter parsing
 731      *         is not supported for a URL (scheme).
 732      * \throws url::UrlDecodingException if the decoded result string
 733      *         would contain a '\\0' character.
 734      */
 735     void
 736     setPathParam(const std::string &param, const std::string &value);
 737
 738
 739     // -----------------
 740     /**
 741      * \brief Set the query string in the URL.
 742      * \param querystr The new encoded query string.
 743      * \throws url::UrlBadComponentException if the \p querystr
 744      *         contains an invalid character.
 745      */
 746     void
 747     setQueryString(const std::string &querystr);
 748
 749     /**
 750      * \brief Set the query parameters.
 751      * \param qvec The vector with encoded query parameters.
 752      * \throws url::UrlBadComponentException if the \p qvec
 753      *         contains an invalid character.
 754      */
 755     void
 756     setQueryStringVec(const zypp::url::ParamVec &qvec);
 757
 758     /**
 759      * \brief Set the query parameters.
 760      * \param qmap The map with decoded query parameters.
 761      * \throws url::UrlNotSupportedException if parameter parsing
 762      *         is not supported for a URL (scheme).
 763      */
 764     void
 765     setQueryStringMap(const zypp::url::ParamMap &qmap);
 766
 767     /**
 768      * \brief Set or add value for the specified query parameter.
 769      * \param param The decoded query parameter name.
 770      * \param value The decoded query parameter value.
 771      * \throws url::UrlNotSupportedException if parameter parsing
 772      *         is not supported for a URL (scheme).
 773      * \throws url::UrlDecodingException if the decoded result string
 774      *         would contain a '\\0' character.
 775      */
 776     void
 777     setQueryParam(const std::string &param, const std::string &value);
 778
 779     /**
 780      * \brief remove the specified query parameter.
 781      * \param param The decoded query parameter name.
 782      * \throws url::UrlNotSupportedException if parameter parsing
 783      *         is not supported for a URL (scheme).
 784      * \throws url::UrlDecodingException if the decoded result string
 785      *         would contain a '\\0' character.
 786      */
 787     void
 788     delQueryParam(const std::string &param);
 789
 790
 791     // -----------------
 792     /**
 793      * \brief Set the fragment string in the URL.
 794      * \param fragment The new fragment string.
 795      * \param eflag If the \p fragment is encoded or not.
 796      * \throws url::UrlBadComponentException if the \p fragment
 797      *         contains an invalid character.
 798      */
 799     void
 800     setFragment(const std::string &fragment,
 801                 EEncoding         eflag = zypp::url::E_DECODED);
 802
 803
 804     // -----------------
 805     /**
 806      * Return the view options of the current object.
 807      *
 808      * This method is used to query the view options
 809      * used by the asString() method.
 810      *
 811      * \return The current view option combination.
 812      */
 813     ViewOptions
 814     getViewOptions() const;
 815
 816     /**
 817      * Change the view options of the current object.
 818      *
 819      * This method is used to change the view options
 820      * used by the asString() method.
 821      *
 822      * \param vopts New view options combination.
 823      */
 824     void
 825     setViewOptions(const ViewOptions &vopts);
 826
 827   private:
 828     friend std::string hotfix1050625::asString( const Url & url_r );
 829     url::UrlRef m_impl;
 830   };
 831
 832   std::ostream & operator<<( std::ostream & str, const Url & url );
 833
 834   /**
 835    * needed for std::set
 836    */
 837   bool operator<( const Url &lhs, const Url &rhs );
 838
 839   /**
 840    * needed for find
 841    */
 842   bool operator==( const Url &lhs, const Url &rhs );
 843
 844
 845   bool operator!=( const Url &lhs, const Url &rhs );
 846
 847   ////////////////////////////////////////////////////////////////////
 848 } // namespace zypp
 849 //////////////////////////////////////////////////////////////////////
 850
 851 #endif /* ZYPP_URL_H */
 852 /*
 853 ** vim: set ts=2 sts=2 sw=2 ai et:
 854 */