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