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