zypp/url/UrlBase.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /**
  10  * \file zypp/url/UrlBase.h
  11  */
  12 #ifndef   ZYPP_URL_URLBASE_H
  13 #define   ZYPP_URL_URLBASE_H
  14
  15 #include <zypp/url/UrlUtils.h>
  16 #include <zypp/base/PtrTypes.h>
  17
  18
  19 //////////////////////////////////////////////////////////////////////
  20 namespace zypp
  21 { ////////////////////////////////////////////////////////////////////
  22
  23   ////////////////////////////////////////////////////////////////////
  24   namespace url
  25   { //////////////////////////////////////////////////////////////////
  26
  27
  28     // ---------------------------------------------------------------
  29     /**
  30      * Url::asString() view options.
  31      *
  32      * A instance of this class represents a bit-wise combination
  33      * of view option constants.
  34      *
  35      * It provides ViewOption::operator+() and ViewOption::operator-()
  36      * to modify a view option combination and a ViewOption::has()
  37      * method, to check if a specified option is enabled or not.
  38      */
  39     struct ViewOption
  40     {
  41       /** @{ */
  42       /**
  43        * Option to include scheme name in the URL string.
  44        *
  45        * Disabling this option causes, that the URL string
  46        * contains the path, query and fragment components
  47        * only, for example just "/foo/bar.txt".
  48        *
  49        * This option is \b enabled by default.
  50        */
  51       static const ViewOption WITH_SCHEME;
  52       /**
  53        * Option to include username in the URL string.
  54        *
  55        * This option depends on a enabled WITH_SCHEME and
  56        * WITH_HOST options and is \b enabled by default.
  57        */
  58       static const ViewOption WITH_USERNAME;
  59       /**
  60        * Option to include password in the URL string.
  61        *
  62        * This option depends on a enabled WITH_SCHEME,
  63        * WITH_HOST and WITH_USERNAME options and is
  64        * \b disabled by default, causing to hide the
  65        * password in the URL authority.
  66        */
  67       static const ViewOption WITH_PASSWORD;
  68       /**
  69        * Option to include hostname in the URL string.
  70        *
  71        * This option depends on a enabled WITH_SCHEME
  72        * option and is \b enabled by default.
  73        */
  74       static const ViewOption WITH_HOST;
  75       /**
  76        * Option to include port number in the URL string.
  77        *
  78        * This option depends on a enabled WITH_SCHEME and
  79        * WITH_HOST options and is \b enabled by default.
  80        */
  81       static const ViewOption WITH_PORT;
  82       /**
  83        * Option to include path name in the URL string.
  84        *
  85        * This option is \b enabled by default.
  86        */
  87       static const ViewOption WITH_PATH_NAME;
  88       /**
  89        * Option to include path parameters in the URL string.
  90        *
  91        * This option depends on a enabled WITH_PATH_NAME
  92        * option and is \b disabled by default, causing to
  93        * hide the path parameters.
  94        */
  95       static const ViewOption WITH_PATH_PARAMS;
  96       /**
  97        * Option to include query string in the URL string.
  98        *
  99        * This option is \b enabled by default.
 100        */
 101       static const ViewOption WITH_QUERY_STR;
 102       /**
 103        * Option to include fragment string in the URL string.
 104        *
 105        * This option is \b enabled by default.
 106        */
 107       static const ViewOption WITH_FRAGMENT;
 108       /** @} */
 109
 110       /** @{ */
 111       /**
 112        * Explicitely include the URL authority separator "//".
 113        *
 114        * It causes, that the URL string includes an empty URL
 115        * authority, for example:
 116        * "file:///foo.txt" instead of just "file:/foo.txt".
 117        *
 118        * This option depends on a enabled WITH_SCHEME view
 119        * option and is enabled by default.
 120        */
 121       static const ViewOption EMPTY_AUTHORITY;
 122       /**
 123        * Explicitely include the "/" path character.
 124        *
 125        * It causes, that a "/" is added to the Url if the path
 126        * name is empty, for example:
 127        *
 128        * "http://localhost/" instead of just "http://localhost".
 129        *
 130        * This option depends on a enabled WITH_PATH_NAME view
 131        * option and is enabled by default.
 132        */
 133       static const ViewOption EMPTY_PATH_NAME;
 134       /**
 135        * Explicitely include the path parameters separator ";".
 136        *
 137        * It causes, that the URL allways contains the ";" path
 138        * parameters separator.
 139        *
 140        * This option depends on a enabled EMPTY_PATH_NAME view
 141        * option and is disabled by default.
 142        */
 143       static const ViewOption EMPTY_PATH_PARAMS;
 144       /**
 145        * Explicitely include the query string separator "?".
 146        *
 147        * It causes, that if the query string is requested using
 148        * the WITH_QUERY_STR option, the URL allways contains the
 149        * "?" query string separator, even if the query string is
 150        * empty.
 151        * This option depends on a enabled WITH_QUERY_STR view
 152        * option and is disabled by default.
 153        */
 154       static const ViewOption EMPTY_QUERY_STR;
 155       /**
 156        * Explicitely include the fragment string separator "#".
 157        *
 158        * It causes, that if the fragment string is requested using
 159        * the WITH_FRAGMENT option, the URL allways contains the "#"
 160        * fragment string separator, even if the fragment string is
 161        * empty.
 162        * This option depends on a enabled WITH_FRAGMENT view
 163        * option and is disabled by default.
 164        */
 165       static const ViewOption EMPTY_FRAGMENT;
 166       /** @} */
 167
 168       /** @{ */
 169       /**
 170        * Default combination of view options.
 171        *
 172        * By default, following view options are enabled:
 173        *   WITH_SCHEME,    WITH_USERNAME,    WITH_HOST,
 174        *   WITH_PORT,      WITH_PATH_NAME,   WITH_QUERY_STR,
 175        *   WITH_FRAGMENT,  EMPTY_AUTHORITY,  EMPTY_PATH_NAME.
 176        */
 177       static const ViewOption DEFAULTS;
 178       /** @} */
 179
 180
 181       /**
 182        * Create instance with default combination of view options.
 183        */
 184       ViewOption(): opt(DEFAULTS.opt)
 185       {}
 186
 187
 188       /**
 189        * Adds \p l and \p r to a new option combination.
 190        *
 191        * @return The new option combination.
 192        */
 193       friend inline ViewOption
 194       operator + (const ViewOption &l, const ViewOption &r)
 195       {
 196         return ViewOption(l.opt |  r.opt);
 197       }
 198
 199       /**
 200        * Substract \p r from \p l to a new option combination.
 201        *
 202        * @return The new option combination.
 203        */
 204       friend inline ViewOption
 205       operator - (const ViewOption &l, const ViewOption &r)
 206       {
 207         return ViewOption(l.opt & ~r.opt);
 208       }
 209
 210       /**
 211        * Assign specified option combination \p o to the current object.
 212        *
 213        * \param o   The option or option combination to make a copy of.
 214        * \return A reference to this option combination.
 215        */
 216       inline ViewOption &
 217       operator = (const ViewOption &o)
 218       {
 219         opt = o.opt; return *this;
 220       }
 221
 222       /**
 223        * Check if specified option \p o is set in the current object.
 224        * \param o    A view option constant.
 225        * \return True, if specified option \p o is
 226        *               set/enabled in the instance.
 227        */
 228       inline bool
 229       has(const ViewOption &o) const
 230       {
 231         return o.opt & opt;
 232       }
 233
 234     private:
 235       ViewOption(int o): opt(o) {}
 236       int opt;
 237     };
 238
 239
 240     // ---------------------------------------------------------------
 241     /**
 242      * ViewOptions is just an alias for ViewOption.
 243      */
 244     typedef ViewOption                           ViewOptions;
 245
 246
 247     // ---------------------------------------------------------------
 248     /**
 249      * Vector of URL scheme names.
 250      */
 251     typedef std::vector<std::string>             UrlSchemes;
 252
 253
 254     // ---------------------------------------------------------------
 255     /**
 256      * Forward declaration of internal UrlBase data.
 257      */
 258     class UrlBaseData;
 259
 260
 261     // ---------------------------------------------------------------
 262     /**
 263      * \brief Generic Url base class.
 264      *
 265      * The UrlBase class implements default behaviour for URL
 266      * manipulations and a base for implementation of scheme-
 267      * specialized URL's for the Url class.
 268      *
 269      */
 270     class UrlBase
 271     {
 272     public:
 273
 274       virtual
 275       ~UrlBase();
 276
 277       UrlBase();
 278
 279       /**
 280        * Create a new Url object as copy of the given one.
 281        * \param url The Url object to make a copy of.
 282        */
 283       UrlBase(const UrlBase &url);
 284
 285       /**
 286        * \brief Construct new object and initializes it with
 287        *        specified URL components.
 288        *
 289        * \param scheme    The scheme name.
 290        * \param authority The encoded authority component data.
 291        * \param pathdata  The encoded path component data.
 292        * \param querystr  The encoded query string component.
 293        * \param fragment  The encoded fragment string component.
 294        * \throws UrlNotAllowedException if one of the components
 295        *         is not allowed for the scheme.
 296        * \throws UrlBadComponentException if one of the components
 297        *         contains an invalid character.
 298        */
 299       UrlBase(const std::string &scheme,
 300               const std::string &authority,
 301               const std::string &pathdata,
 302               const std::string &querystr,
 303               const std::string &fragment);
 304
 305
 306       // -----------------
 307       /**
 308        * \brief Clears all data in the object.
 309        */
 310       virtual void
 311       clear();
 312
 313       /**
 314        * Returns pointer to a copy of the current object.
 315        *
 316        * Should be reimplemented by all derived object using
 317        * the copy constructor of the derived class, e.g.:
 318        * \code
 319        *   return new MyUrlDerivedFromUrlBase(*this);
 320        * \endcode
 321        *
 322        * \return A pointer to a copy of the current object.
 323        */
 324       virtual UrlBase *
 325       clone() const;
 326
 327       /**
 328        * \brief Initializes current object with new URL components.
 329        *
 330        * \param scheme    The scheme name.
 331        * \param authority The encoded authority component data.
 332        * \param pathdata  The encoded path component data.
 333        * \param querystr  The encoded query string component.
 334        * \param fragment  The encoded fragment string component.
 335        * \throws UrlNotAllowedException if one of the components
 336        *         is not allowed in the scheme.
 337        * \throws UrlBadComponentException if one of the components
 338        *         contains an invalid character.
 339        */
 340       virtual void
 341       init(const std::string &scheme,
 342            const std::string &authority,
 343            const std::string &pathdata,
 344            const std::string &querystr,
 345            const std::string &fragment);
 346
 347
 348       // -----------------
 349       /**
 350        * \brief Returns scheme names known by this object.
 351        *
 352        * This method is used in the isValidScheme() method and
 353        * is intended to be reimplemented by derived classes to
 354        * return the scheme names it implements (is restricted
 355        * or compatible to).
 356        *
 357        * For example, if your derived class implements special
 358        * features of LDAP URL's, this method may return "ldap"
 359        * and "ldaps" scheme names.
 360        *
 361        * The UrlBase class returns an empty vector, that signals
 362        * that it is useable with all URL's.
 363        *
 364        * \return A vector with scheme names known by this object.
 365        */
 366       virtual UrlSchemes
 367       getKnownSchemes() const;
 368
 369       /**
 370        * \brief Returns if scheme name is known to this object.
 371        * \return True, if scheme name is known to this object.
 372        */
 373       virtual bool
 374       isKnownScheme(const std::string &scheme) const;
 375
 376
 377       /**
 378        * \brief Verifies specified scheme name.
 379        *
 380        * Verifies the generic syntax of the specified \p scheme name
 381        * and if it is contained in the current object's list of known
 382        * schemes (see getKnownSchemes()) if the list is not empty (as
 383        * in the UrlBase class).
 384        *
 385        * \param  scheme The scheme name to verify.
 386        * \return True, if generic scheme name syntax is valid and
 387        *         the scheme name is known to the current object.
 388        */
 389       virtual bool
 390       isValidScheme(const std::string &scheme) const;
 391
 392       /**
 393        * \brief Verifies the Url.
 394        *
 395        * Verifies if the current object contains a non-empty scheme
 396        * name. Additional semantical URL checks may be performed by
 397        * derived UrlBase-objects.
 398        *
 399        * \return True, if the Url seems to be valid.
 400        */
 401       virtual bool
 402       isValid() const;
 403
 404
 405       // -----------------
 406       /**
 407        * Returns a default string representation of the Url object.
 408        *
 409        * By default, a password in the URL will be hidden.
 410        *
 411        * \return A default string representation of the Url object.
 412        */
 413       virtual std::string
 414       asString() const;
 415
 416       /**
 417        * Returns a string representation of the Url object.
 418        *
 419        * To include a password in the resulting Url string, use:
 420        * \code
 421        *    url.asString(url.getViewOptions() +
 422        *                 url::ViewOptions::WITH_PASSWORD);
 423        * \endcode
 424        *
 425        * \param opts  A combination of view options.
 426        * \return A string representation of the Url object.
 427        */
 428       virtual std::string
 429       asString(const zypp::url::ViewOptions &opts) const;
 430
 431
 432       // -----------------
 433       /**
 434        * Returns the scheme name of the URL.
 435        * \return Scheme name of the current Url object.
 436        */
 437       virtual std::string
 438       getScheme() const;
 439
 440
 441       // -----------------
 442       /**
 443        * Returns the encoded authority component of the URL.
 444        *
 445        * The returned authority string does not contain the leading
 446        * "//" separator characters, but just its "user:pass@host:port"
 447        * content only.
 448        *
 449        * \return The encoded authority component string.
 450        */
 451       virtual std::string
 452       getAuthority() const;
 453
 454       /**
 455        * Returns the username from the URL authority.
 456        * \param eflag Flag if the usename should be percent-decoded or not.
 457        * \return The username sub-component from the URL authority.
 458        * \throws UrlDecodingException if the decoded result string
 459        *         would contain a '\\0' character.
 460        */
 461       virtual std::string
 462       getUsername(EEncoding eflag) const;
 463
 464       /**
 465        * Returns the password from the URL authority.
 466        * \param eflag Flag if the password should be percent-decoded or not.
 467        * \return The password sub-component from the URL authority.
 468        * \throws UrlDecodingException if the decoded result string
 469        *         would contain a '\\0' character.
 470        */
 471       virtual std::string
 472       getPassword(EEncoding eflag) const;
 473
 474       /**
 475        * Returns the hostname or IP from the URL authority.
 476        *
 477        * In case the Url contains an IPv6 number, it is be surrounded
 478        * by "[" and "]" characters, for example "[::1]" for an IPv6
 479        * localhost address.
 480        *
 481        * \param eflag Flag if the host should be percent-decoded or not.
 482        * \return The host sub-component from the URL authority.
 483        * \throws UrlDecodingException if the decoded result string
 484        *         would contain a '\\0' character.
 485        */
 486       virtual std::string
 487       getHost(EEncoding eflag) const;
 488
 489       /**
 490        * Returns the port number from the URL authority.
 491        * \return The port sub-component from the URL authority.
 492        */
 493       virtual std::string
 494       getPort() const;
 495
 496
 497       // -----------------
 498       /**
 499        * Returns the encoded path component of the URL.
 500        *
 501        * The path data contains the path name, optionally
 502        * followed by path parameters separated with a ";"
 503        * character, for example "/foo/bar;version=1.1".
 504        *
 505        * \return The encoded path component of the URL.
 506        */
 507       virtual std::string
 508       getPathData() const;
 509
 510       /**
 511        * Returns the path name from the URL.
 512        * \param eflag Flag if the path should be decoded or not.
 513        * \return The path name sub-component without path parameters
 514        *         from path data component of the URL.
 515        * \throws UrlDecodingException if the decoded result string
 516        *         would contain a '\\0' character.
 517        */
 518       virtual std::string
 519       getPathName(EEncoding eflag) const;
 520
 521       /**
 522        * Returns the encoded path parameters from the URL.
 523        * \return The encoded path parameters from the URL.
 524        */
 525       virtual std::string
 526       getPathParams() const;
 527
 528       /**
 529        * Returns a vector with encoded path parameter substrings.
 530        *
 531        * The default path parameter separator is the \c ',' character.
 532        * A schema specific object may overide the default separators.
 533        *
 534        * For example, the path parameters string "foo=1,bar=2" is splited
 535        * by default into a vector containing the substrings "foo=1" and
 536        * "bar=2".
 537        *
 538        * \return The encoded path parameters vector.
 539        */
 540       virtual zypp::url::ParamVec
 541       getPathParamsVec() const;
 542
 543       /**
 544        * Returns a string map with path parameter keys and values.
 545        *
 546        * The default path parameter separator is the \c ',' character,
 547        * the default key/value separator for the path parameters is
 548        * the \c '=' character.
 549        * A schema specific object may overide the default separators.
 550        *
 551        * For example, the path parameters string "foo=1,bar=2" is splited
 552        * into a map containing "foo" = "1" and "bar" = "2" by default.
 553        *
 554        * \param eflag Flag if the path parameter keys and values should
 555        *               be decoded or not.
 556        * \return The path parameters key and values as a string map.
 557        * \throws UrlNotSupportedException if parameter parsing
 558        *         is not supported for a URL (scheme).
 559        * \throws UrlDecodingException if the decoded result string
 560        *         would contain a '\\0' character.
 561        */
 562       virtual zypp::url::ParamMap
 563       getPathParamsMap(EEncoding eflag) const;
 564
 565       /**
 566        * Return the value for the specified path parameter.
 567        *
 568        * For example, if the path parameters string is "foo=1,bar=2"
 569        * the method will return the substring "1" for the param key
 570        * "foo" and "2" for the param key "bar".
 571        *
 572        * \param param The path parameter key.
 573        * \param eflag Flag if the path parameter keys and values should
 574        *              be decoded or not.
 575        * \return The value for the path parameter key or empty string.
 576        * \throws UrlNotSupportedException if parameter parsing
 577        *         is not supported for a URL (scheme).
 578        * \throws UrlDecodingException if the decoded result string
 579        *         would contain a '\\0' character.
 580        */
 581       virtual std::string
 582       getPathParam(const std::string &param, EEncoding eflag) const;
 583
 584
 585       // -----------------
 586       /**
 587        * Returns the encoded query string component of the URL.
 588        *
 589        * The query string is returned without first "?" (separator)
 590        * character. Further "?" characters as in e.g. LDAP URL's
 591        * remains in the returned string.
 592        *
 593        * \return The encoded query string component of the URL.
 594        */
 595       virtual std::string
 596       getQueryString() const;
 597
 598       /**
 599        * Returns a vector with query string parameter substrings.
 600        *
 601        * The default query string parameter separator is the \c '&'
 602        * character.
 603        * A schema specific object may overide the default separators.
 604        *
 605        * For example, the query string "foo=1&bar=2" is splited by
 606        * default into a vector containing the substrings "foo=1" and
 607        * "bar=2".
 608        *
 609        * \return The query string splited into a vector of substrings.
 610        */
 611       virtual zypp::url::ParamVec
 612       getQueryStringVec() const;
 613
 614       /**
 615        * Returns a string map with query parameter and their values.
 616        *
 617        * The default query string parameter separator is the \c ','
 618        * character, the default key/value separator the \c '=' character.
 619        * A schema specific object may overide the default separators.
 620        *
 621        * For example, the query string "foo=1&bar=2" is splited by
 622        * default into a map containing "foo" = "1" and "bar" = "2".
 623        *
 624        * \param eflag Flag if the query string keys and values should
 625        *               be decoded or not.
 626        * \return The query string as a key/value string map.
 627        * \throws UrlNotSupportedException if parameter parsing
 628        *         is not supported for a URL (scheme).
 629        * \throws UrlDecodingException if the decoded result string
 630        *         would contain a '\\0' character.
 631        */
 632       virtual zypp::url::ParamMap
 633       getQueryStringMap(EEncoding eflag) const;
 634
 635       /**
 636        * Return the value for the specified query parameter.
 637        *
 638        * For example, if the query string is "foo=1,bar=2" the method
 639        * will return the substring "1" for the param key "foo" and
 640        * "2" for the param key "bar".
 641        *
 642        * \param param The query parameter key.
 643        * \param eflag Flag if the query parameter keys and values should
 644        *              be decoded or not.
 645        * \return The value for the query parameter key or empty string.
 646        * \throws UrlNotSupportedException if parameter parsing
 647        *         is not supported for a URL (scheme).
 648        * \throws UrlDecodingException if the decoded result string
 649        *         would contain a '\\0' character.
 650        */
 651       virtual std::string
 652       getQueryParam(const std::string &param, EEncoding eflag) const;
 653
 654
 655       // -----------------
 656       /**
 657        * Returns the encoded fragment component of the URL.
 658        * \param eflag Flag if the fragment should be percent-decoded or not.
 659        * \return The encoded fragment component of the URL.
 660        * \throws UrlDecodingException if the decoded result string
 661        *         would contain a '\\0' character.
 662        */
 663       virtual std::string
 664       getFragment(EEncoding eflag) const;
 665
 666
 667       // -----------------
 668       /**
 669        * \brief Set the scheme name in the URL.
 670        * \param scheme The new scheme name.
 671        * \throws UrlBadComponentException if the \p scheme
 672        *         contains an invalid character or is empty.
 673        */
 674       virtual void
 675       setScheme(const std::string &scheme);
 676
 677
 678       // -----------------
 679       /**
 680        * \brief Set the authority component in the URL.
 681        *
 682        * The \p authority string shoud not contain any leading
 683        * "//" separator characters (just "user:pass@host:port").
 684        *
 685        * \param authority The authority component string.
 686        * \throws UrlNotAllowedException if the \p authority
 687        *         has to be empty in for the current scheme.
 688        * \throws UrlBadComponentException if the \p authority
 689        *         contains an invalid character.
 690        * \throws UrlParsingException if \p authority parsing fails.
 691        */
 692       virtual void
 693       setAuthority(const std::string &authority);
 694
 695       /**
 696        * \brief Set the username in the URL authority.
 697        * \param user  The new username.
 698        * \param eflag If the \p username is encoded or not.
 699        * \throws UrlNotAllowedException if the \p user
 700        *         has to be empty in for the current scheme.
 701        * \throws UrlBadComponentException if the \p user
 702        *         contains an invalid character.
 703        */
 704       virtual void
 705       setUsername(const std::string &user,
 706                   EEncoding         eflag);
 707
 708       /**
 709        * \brief Set the password in the URL authority.
 710        * \param pass  The new password.
 711        * \param eflag If the \p password is encoded or not.
 712        * \throws UrlNotAllowedException if the \p pass
 713        *         has to be empty in for the current scheme.
 714        * \throws UrlBadComponentException if the \p pass
 715        *         contains an invalid character.
 716        */
 717       virtual void
 718       setPassword(const std::string &pass,
 719                   EEncoding         eflag);
 720
 721       /**
 722        * \brief Set the hostname or IP in the URL authority.
 723        *
 724        * The \p host parameter may contain a hostname, an IPv4 address
 725        * in dotted-decimal form or an IPv6 address literal encapsulated
 726        * within square brackets (RFC3513, Sect. 2.2).
 727        *
 728        * A hostname may contain national alphanumeric UTF8 characters
 729        * (letters other than ASCII a-zA-Z), that will be encoded.
 730        * This function allows to specify both, a encoded or decoded
 731        * hostname.
 732        *
 733        * Other IP literals in "[v ... ]" square bracket format are not
 734        * supported by the implementation in UrlBase class.
 735        *
 736        * \param host The new hostname or IP address.
 737        * \throws UrlNotAllowedException if the \p host
 738        *         has to be empty in for the current scheme.
 739        * \throws UrlBadComponentException if the \p host is invalid.
 740        */
 741       virtual void
 742       setHost(const std::string &host);
 743
 744       /**
 745        * \brief Set the port number in the URL authority.
 746        * \param port The new port number.
 747        * \throws UrlNotAllowedException if the \p port
 748        *         has to be empty in for the current scheme.
 749        * \throws UrlBadComponentException if the \p port is invalid.
 750        */
 751       virtual void
 752       setPort(const std::string &port);
 753
 754
 755       // -----------------
 756       /**
 757        * \brief Set the path data component in the URL.
 758        *
 759        * By default, the \p pathdata string may include path
 760        * parameters separated by the ";" separator character.
 761        *
 762        * \param pathdata The encoded path data component string.
 763        * \throws UrlBadComponentException if the \p pathdata
 764        *         contains an invalid character.
 765        */
 766       virtual void
 767       setPathData(const std::string &pathdata);
 768
 769       /**
 770        * \brief Set the path name.
 771        * \param path  The new path name.
 772        * \param eflag If the \p path name is encoded or not.
 773        * \throws UrlBadComponentException if the \p path name
 774        *         contains an invalid character.
 775        */
 776       virtual void
 777       setPathName(const std::string &path,
 778                   EEncoding         eflag);
 779
 780       /**
 781        * \brief Set the path parameters.
 782        * \param params The new encoded path parameter string.
 783        * \throws UrlBadComponentException if the path \p params
 784        *         contains an invalid character.
 785        */
 786       virtual void
 787       setPathParams(const std::string &params);
 788
 789       /**
 790        * \brief Set the path parameters.
 791        * \param pvec The vector with encoded path parameters.
 792        * \throws UrlBadComponentException if the \p pvec
 793        *         contains an invalid character.
 794        */
 795       virtual void
 796       setPathParamsVec(const zypp::url::ParamVec &pvec);
 797
 798       /**
 799        * \brief Set the path parameters.
 800        * \param pmap The map with decoded path parameters.
 801        * \throws UrlNotSupportedException if parameter parsing
 802        *         is not supported for a URL (scheme).
 803        */
 804       virtual void
 805       setPathParamsMap(const zypp::url::ParamMap &pmap);
 806
 807       /**
 808        * \brief Set or add value for the specified path parameter.
 809        * \param param The decoded path parameter name.
 810        * \param value The decoded path parameter value.
 811        * \throws UrlNotSupportedException if parameter parsing
 812        *         is not supported for a URL (scheme).
 813        * \throws UrlDecodingException if the decoded result string
 814        *         would contain a '\\0' character.
 815        */
 816       virtual void
 817       setPathParam(const std::string &param, const std::string &value);
 818
 819
 820       // -----------------
 821       /**
 822        * \brief Set the query string in the URL.
 823        *
 824        * The \p querystr string parameter is supposed
 825        * to not to contain the "?" URL query separator
 826        * character (use just a "foo=bar&x=22" instead
 827        * of "?foo=bar&x=22").
 828        *
 829        * \param querystr The new encoded query string.
 830        * \throws UrlBadComponentException if the \p querystr
 831        *         contains an invalid character.
 832        */
 833       virtual void
 834       setQueryString(const std::string &querystr);
 835
 836       /**
 837        * \brief Set the query parameters.
 838        * \param qvec The vector with encoded query parameters.
 839        * \throws UrlBadComponentException if the \p qvec
 840        *         contains an invalid character.
 841        */
 842       virtual void
 843       setQueryStringVec(const zypp::url::ParamVec &qvec);
 844
 845       /**
 846        * \brief Set the query parameters.
 847        * \param qmap The map with decoded query parameters.
 848        * \throws UrlNotSupportedException if parameter parsing
 849        *         is not supported for a URL (scheme).
 850        */
 851       virtual void
 852       setQueryStringMap(const zypp::url::ParamMap &qmap);
 853
 854       /**
 855        * \brief Set or add value for the specified query parameter.
 856        * \param param The decoded query parameter name.
 857        * \param value The decoded query parameter value.
 858        * \throws UrlNotSupportedException if parameter parsing
 859        *         is not supported for a URL (scheme).
 860        * \throws UrlDecodingException if the decoded result string
 861        *         would contain a '\\0' character.
 862        */
 863       virtual void
 864       setQueryParam(const std::string &param, const std::string &value);
 865
 866
 867       // -----------------
 868       /**
 869        * \brief Set the fragment string in the URL.
 870        * \param fragment The new fragment string.
 871        * \param eflag If the \p fragment is encoded or not.
 872        * \throws UrlBadComponentException if the \p querystr
 873        *         contains an invalid character.
 874        */
 875       virtual void
 876       setFragment(const std::string &fragment,
 877                   EEncoding         eflag);
 878
 879
 880       // -----------------
 881       /**
 882        * Configures behaviour of the instance.
 883        *
 884        * This method is called in UrlBase constructors before
 885        * any URL components are applied.
 886        * Derived classes may reimplement this method to change
 887        * the behaviour of the object.
 888        * Use the config() methods to query and change them.
 889        *
 890        * The UrlBase class uses following config variables:
 891        *
 892        * - Common path parameter separators:
 893        *   - \a \c sep_pathparams   \c ";"
 894        *     Separator used to split path parameters from path name.
 895        *     Setting it to empty string disables splitting of path
 896        *     name and path parameters. Set also rx_pathparams to an
 897        *     empty string.
 898        *   - \a \c psep_pathparam   \c ","
 899        *     Separator between path parameters.
 900        *   - \a \c vsep_pathparam   \c "="
 901        *     Separator between key and value of a path parameter.
 902        *   .
 903        * .
 904        *
 905        * - Common query string separators:
 906        *   - \a \c psep_querystr    \c "&"
 907        *     Separator between query string parameters.
 908        *   - \a \c vsep_querystr    \c "="
 909        *     Separator between key and value of a query parameter.
 910        *   .
 911        * .
 912        *
 913        * - Characters in URL components, that are safe without
 914        *   URL percent-encoding (see zypp::url::encode()).
 915        *   - \a safe_username
 916        *   - \a safe_password
 917        *   - \a safe_hostname
 918        *   - \a safe_pathname
 919        *   - \a safe_pathparams
 920        *   - \a safe_querystr
 921        *   - \a safe_fragment
 922        *   .
 923        * .
 924        *
 925        * - Regular expressions used to verify encoded URL
 926        *   components and their sub-components:
 927        *   - \a rx_username
 928        *   - \a rx_password
 929        *   - \a rx_pathname
 930        *   - \a rx_pathparams
 931        *   - \a rx_querystr
 932        *   - \a rx_fragment
 933        *   .
 934        * .
 935        */
 936       virtual void
 937       configure();
 938
 939
 940       /**
 941        * Get the value of a UrlBase configuration variable.
 942        *
 943        * See configure() method for names an purpose of the
 944        * configuration variables used in UrlBase class.
 945        *
 946        * \param opt The name of the configuration variable.
 947        * \return The value of the specified variable
 948        *         or empty string.
 949        */
 950       std::string
 951       config(const std::string &opt) const;
 952
 953       /**
 954        * Set the value of a UrlBase configuration variable.
 955        *
 956        * See configure() method for names an purpose of the
 957        * configuration variables used in UrlBase class.
 958        *
 959        * \param opt The name of the configuration variable.
 960        * \param val The new value for the configuration variable.
 961        */
 962       void
 963       config(const std::string &opt, const std::string &val);
 964
 965
 966       /**
 967        * Return the view options of the current object.
 968        *
 969        * This method is used to query the view options
 970        * used by the asString() method.
 971        *
 972        * \return The current view option combination.
 973        */
 974       ViewOptions
 975       getViewOptions() const;
 976
 977       /**
 978        * Change the view options of the current object.
 979        *
 980        * This method is used to change the view options
 981        * used by the asString() method.
 982        *
 983        * \param vopts New view options combination.
 984        */
 985       void
 986       setViewOptions(const ViewOptions &vopts);
 987
 988
 989     protected:
 990       /**
 991        * Utility method to cleanup an encoded path name.
 992        *
 993        * By default, this method makes sure, that the first slash
 994        * in the path is not encoded, and that the second slash
 995        * before the first path segment, is encoded (to "%2F").
 996        * It modifies the path in the url, for example:
 997        *   "ftp://host//aaa//bbb" to "ftp://host/%2Faaa//bbb"
 998        * or as encoded path only also "%2f/name" to "/%2fname".
 999        *
1000        * This operation is required to fulfill the path-absolute
1001        * rule of RFC3986, if there is no authority. It avoids the
1002        * missinterpretation of the path as an authority separator.
1003        *
1004        * It is not required if there is an authority ("//" behind
1005        * the "scheme:"), that is in the path-abempty rule, but it
1006        * is allowed and used e.g. in ftp url's defined by RFC1738.
1007        *
1008        * We apply this operation in both cases (for all paths).
1009        *
1010        * \param path   The encoded path name to cleanup.
1011        * \return A modified encoded path.
1012        */
1013       virtual std::string
1014       cleanupPathName(const std::string &path);
1015
1016       /**
1017        * \brief Verifies specified host or IP.
1018        *
1019        * It verifies, if the specified \p host parameter contains
1020        * a hostname, an IPv4 address in dotted-decimal form or an
1021        * IPv6 address literal encapsulated within square brackets
1022        * (RFC3513, Sect. 2.2).
1023        *
1024        * A hostname in the \p host parameter, may contain national
1025        * alphanumeric UTF8 characters (letters other than ASCII
1026        * a-zA-Z) and allows to specify both, a encoded or decoded
1027        * hostname.
1028        *
1029        * This function does not perform any hostname lookups and
1030        * supports only IPv6 addresses in "[ ... ]" notation. The
1031        * "[v ... ]" square bracket format is not supported by
1032        * this implementation.
1033        *
1034        * \param  host  The host name or IP to verify.
1035        * \return True, if host seems to be valid.
1036        */
1037       virtual bool
1038       isValidHost(const std::string &host);
1039
1040       /**
1041        * \brief Verifies specified port number.
1042        *
1043        * \param  port  The port number to verify.
1044        * \return True, if port number is valid.
1045        */
1046       virtual bool
1047       isValidPort(const std::string &port);
1048
1049     private:
1050       UrlBaseData *m_data;
1051     };
1052
1053
1054     // ---------------------------------------------------------------
1055     /**
1056      * \brief Copy-On-Write Url reference.
1057      */
1058     typedef RWCOW_pointer<UrlBase>          UrlRef;
1059
1060
1061     //////////////////////////////////////////////////////////////////
1062   } // namespace url
1063   ////////////////////////////////////////////////////////////////////
1064
1065   ////////////////////////////////////////////////////////////////////
1066 } // namespace zypp
1067 //////////////////////////////////////////////////////////////////////
1068
1069 #endif /* ZYPP_URL_URLBASE_H */
1070 /*
1071 ** vim: set ts=2 sts=2 sw=2 ai et:
1072 */