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::toString() 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 std::invalid_argument exception if one of the
 295        *         parameters contains an invalid character.
 296        */
 297       UrlBase(const std::string &scheme,
 298               const std::string &authority,
 299               const std::string &pathdata,
 300               const std::string &querystr,
 301               const std::string &fragment);
 302
 303
 304       // -----------------
 305       /**
 306        * \brief Clears all data in the object.
 307        */
 308       virtual void
 309       clear();
 310
 311       /**
 312        * Returns pointer to a copy of the current object.
 313        *
 314        * Should be reimplemented by all derived object using
 315        * the copy constructor of the derived class, e.g.:
 316        * \code
 317        *   return new MyUrlDerivedFromUrlBase(*this);
 318        * \endcode
 319        *
 320        * \return A pointer to a copy of the current object.
 321        */
 322       virtual UrlBase *
 323       clone() const;
 324
 325       /**
 326        * \brief Initializes current object with new URL components.
 327        *
 328        * \param scheme    The scheme name.
 329        * \param authority The encoded authority component data.
 330        * \param pathdata  The encoded path component data.
 331        * \param querystr  The encoded query string component.
 332        * \param fragment  The encoded fragment string component.
 333        * \throws std::invalid_argument exception if one of the
 334        *         parameters contains an invalid character.
 335        */
 336       virtual void
 337       init(const std::string &scheme,
 338            const std::string &authority,
 339            const std::string &pathdata,
 340            const std::string &querystr,
 341            const std::string &fragment);
 342
 343
 344       // -----------------
 345       /**
 346        * \brief Returns scheme names known by this object.
 347        *
 348        * This method is used in the isValidScheme() method and
 349        * is intended to be reimplemented by derived classes to
 350        * return the scheme names it implements (is restricted
 351        * or compatible to).
 352        *
 353        * For example, if your derived class implements special
 354        * features of LDAP URL's, this method may return "ldap"
 355        * and "ldaps" scheme names.
 356        *
 357        * The UrlBase class returns an empty vector, that signals
 358        * that it is useable with all URL's.
 359        *
 360        * \return A vector with scheme names known by this object.
 361        */
 362       virtual UrlSchemes
 363       getKnownSchemes() const;
 364
 365       /**
 366        * \brief Returns if scheme name is known to this object.
 367        * \return True, if scheme name is known to this object.
 368        */
 369       virtual bool
 370       isKnownScheme(const std::string &scheme) const;
 371
 372
 373       /**
 374        * \brief Verifies specified scheme name.
 375        *
 376        * Verifies the generic syntax of the specified \p scheme name
 377        * and if it is contained in the current object's list of known
 378        * schemes (see getKnownSchemes()) if the list is not empty (as
 379        * in the UrlBase class).
 380        *
 381        * \param  scheme The scheme name to verify.
 382        * \return True, if generic scheme name syntax is valid and
 383        *         the scheme name is known to the current object.
 384        */
 385       virtual bool
 386       isValidScheme(const std::string &scheme) const;
 387
 388       /**
 389        * \brief Verifies the Url.
 390        *
 391        * Verifies if the current object contains a non-empty scheme
 392        * name. Additional semantical URL checks may be performed by
 393        * derived UrlBase-objects.
 394        *
 395        * \return True, if the Url seems to be valid.
 396        */
 397       virtual bool
 398       isValid() const;
 399
 400
 401       // -----------------
 402       /**
 403        * Returns a default string representation of the Url object.
 404        *
 405        * By default, a password in the URL will be hidden.
 406        *
 407        * \return A default string representation of the Url object.
 408        */
 409       virtual std::string
 410       toString() const;
 411
 412       /**
 413        * Returns a string representation of the Url object.
 414        *
 415        * To include a password in the resulting Url string, use:
 416        * \code
 417        *    url.toString(url::ViewOptions() +
 418        *                 url::ViewOptions::WITH_PASSWORD);
 419        * \endcode
 420        *
 421        * or its equivalent:
 422        *
 423        * \code
 424        *    url.toString(url::ViewOptions::DEFAULTS +
 425        *                 url::ViewOptions::WITH_PASSWORD);
 426        * \endcode
 427        *
 428        * \param opts  A combination of view options.
 429        * \return A string representation of the Url object.
 430        */
 431       virtual std::string
 432       toString(const zypp::url::ViewOptions &opts) const;
 433
 434
 435       // -----------------
 436       /**
 437        * Returns the scheme name of the URL.
 438        * \return Scheme name of the current Url object.
 439        */
 440       virtual std::string
 441       getScheme() const;
 442
 443
 444       // -----------------
 445       /**
 446        * Returns the encoded authority component of the URL.
 447        *
 448        * The returned authority string does not contain the leading
 449        * "//" separator characters, but just its "user:pass@host:port"
 450        * content only.
 451        *
 452        * \return The encoded authority component string.
 453        */
 454       virtual std::string
 455       getAuthority() const;
 456
 457       /**
 458        * Returns the username from the URL authority.
 459        * \param eflag Flag if the usename should be percent-decoded or not.
 460        * \return The username sub-component from the URL authority.
 461        * \throws std::invalid_argument exception if the decoded
 462        *         result string would contain a '\\0' character.
 463        */
 464       virtual std::string
 465       getUsername(EEncoding eflag) const;
 466
 467       /**
 468        * Returns the password from the URL authority.
 469        * \param eflag Flag if the password should be percent-decoded or not.
 470        * \return The password sub-component from the URL authority.
 471        * \throws std::invalid_argument exception if the decoded
 472        *         result string would contain a '\\0' character.
 473        */
 474       virtual std::string
 475       getPassword(EEncoding eflag) const;
 476
 477       /**
 478        * Returns the hostname or IP from the URL authority.
 479        *
 480        * In case the Url contains an IPv6 number, it is be surrounded
 481        * by "[" and "]" characters, for example "[::1]" for an IPv6
 482        * localhost address.
 483        *
 484        * \param eflag Flag if the host should be percent-decoded or not.
 485        * \return The host sub-component from the URL authority.
 486        * \throws std::invalid_argument exception if the decoded
 487        *         result string would contain a '\\0' character.
 488        */
 489       virtual std::string
 490       getHost(EEncoding eflag) const;
 491
 492       /**
 493        * Returns the port number from the URL authority.
 494        * \return The port sub-component from the URL authority.
 495        */
 496       virtual std::string
 497       getPort() const;
 498
 499
 500       // -----------------
 501       /**
 502        * Returns the encoded path component of the URL.
 503        *
 504        * The path data contains the path name, optionally
 505        * followed by path parameters separated with a ";"
 506        * character, for example "/foo/bar;version=1.1".
 507        *
 508        * \return The encoded path component of the URL.
 509        */
 510       virtual std::string
 511       getPathData() const;
 512
 513       /**
 514        * Returns the path name from the URL.
 515        * \param eflag Flag if the path should be decoded or not.
 516        * \return The path name sub-component without path parameters
 517        *         from path data component of the URL.
 518        * \throws std::invalid_argument exception if the decoded
 519        *         result string would contain a '\\0' character.
 520        */
 521       virtual std::string
 522       getPathName(EEncoding eflag) const;
 523
 524       /**
 525        * Returns the encoded path parameters from the URL.
 526        * \return The encoded path parameters from the URL.
 527        */
 528       virtual std::string
 529       getPathParams() const;
 530
 531       /**
 532        * Returns a vector with encoded path parameter substrings.
 533        *
 534        * The default path parameter separator is the \c ',' character.
 535        * A schema specific object may overide the default separators.
 536        *
 537        * For example, the path parameters string "foo=1,bar=2" is splited
 538        * by default into a vector containing the substrings "foo=1" and
 539        * "bar=2".
 540        *
 541        * \return The encoded path parameters vector.
 542        */
 543       virtual zypp::url::ParamVec
 544       getPathParamsVec() const;
 545
 546       /**
 547        * Returns a string map with path parameter keys and values.
 548        *
 549        * The default path parameter separator is the \c ',' character,
 550        * the default key/value separator for the path parameters is
 551        * the \c '=' character.
 552        * A schema specific object may overide the default separators.
 553        *
 554        * For example, the path parameters string "foo=1,bar=2" is splited
 555        * into a map containing "foo" = "1" and "bar" = "2" by default.
 556        *
 557        * \param eflag Flag if the path parameter keys and values should
 558        *               be decoded or not.
 559        * \return The path parameters key and values as a string map.
 560        * \throws std::logic_error exception if parameter parsing
 561        *         is not supported for a URL (scheme).
 562        * \throws std::invalid_argument exception if a decoded
 563        *         string would contain a '\\0' character.
 564        */
 565       virtual zypp::url::ParamMap
 566       getPathParamsMap(EEncoding eflag) const;
 567
 568       /**
 569        * Return the value for the specified path parameter.
 570        *
 571        * For example, if the path parameters string is "foo=1,bar=2"
 572        * the method will return the substring "1" for the param key
 573        * "foo" and "2" for the param key "bar".
 574        *
 575        * \param param The path parameter key.
 576        * \param eflag Flag if the path parameter keys and values should
 577        *              be decoded or not.
 578        * \return The value for the path parameter key or empty string.
 579        * \throws std::logic_error exception if parameter parsing
 580        *         is not supported for a URL (scheme).
 581        * \throws std::invalid_argument exception if a decoded
 582        *         string would contain a '\\0' character.
 583        */
 584       virtual std::string
 585       getPathParam(const std::string &param, EEncoding eflag) const;
 586
 587
 588       // -----------------
 589       /**
 590        * Returns the encoded query string component of the URL.
 591        *
 592        * The query string is returned without first "?" (separator)
 593        * character. Further "?" characters as in e.g. LDAP URL's
 594        * remains in the returned string.
 595        *
 596        * \return The encoded query string component of the URL.
 597        */
 598       virtual std::string
 599       getQueryString() const;
 600
 601       /**
 602        * Returns a vector with query string parameter substrings.
 603        *
 604        * The default query string parameter separator is the \c '&'
 605        * character.
 606        * A schema specific object may overide the default separators.
 607        *
 608        * For example, the query string "foo=1&bar=2" is splited by
 609        * default into a vector containing the substrings "foo=1" and
 610        * "bar=2".
 611        *
 612        * \return The query string splited into a vector of substrings.
 613        */
 614       virtual zypp::url::ParamVec
 615       getQueryStringVec() const;
 616
 617       /**
 618        * Returns a string map with query parameter and their values.
 619        *
 620        * The default query string parameter separator is the \c ','
 621        * character, the default key/value separator the \c '=' character.
 622        * A schema specific object may overide the default separators.
 623        *
 624        * For example, the query string "foo=1&bar=2" is splited by
 625        * default into a map containing "foo" = "1" and "bar" = "2".
 626        *
 627        * \param eflag Flag if the query string keys and values should
 628        *               be decoded or not.
 629        * \return The query string as a key/value string map.
 630        * \throws std::logic_error exception if parameter parsing
 631        *         is not supported for a URL (scheme).
 632        * \throws std::invalid_argument exception if a decoded
 633        *         string would contain a '\\0' character.
 634        */
 635       virtual zypp::url::ParamMap
 636       getQueryStringMap(EEncoding eflag) const;
 637
 638       /**
 639        * Return the value for the specified query parameter.
 640        *
 641        * For example, if the query string is "foo=1,bar=2" the method
 642        * will return the substring "1" for the param key "foo" and
 643        * "2" for the param key "bar".
 644        *
 645        * \param param The query parameter key.
 646        * \param eflag Flag if the query parameter keys and values should
 647        *              be decoded or not.
 648        * \return The value for the query parameter key or empty string.
 649        * \throws std::logic_error exception if parameter parsing
 650        *         is not supported for a URL (scheme).
 651        * \throws std::invalid_argument exception if a decoded
 652        *         string would contain a '\\0' character.
 653        */
 654       virtual std::string
 655       getQueryParam(const std::string &param, EEncoding eflag) const;
 656
 657
 658       // -----------------
 659       /**
 660        * Returns the encoded fragment component of the URL.
 661        * \param eflag Flag if the fragment should be percent-decoded or not.
 662        * \return The encoded fragment component of the URL.
 663        * \throws std::invalid_argument exception if the decoded
 664        *         result string would contain a '\\0' character.
 665        */
 666       virtual std::string
 667       getFragment(EEncoding eflag) const;
 668
 669
 670       // -----------------
 671       /**
 672        * \brief Set the scheme name in the URL.
 673        * \param scheme The new scheme name.
 674        * \throws std::invalid_argument exception if the \p scheme
 675        *         parameter contains an invalid character.
 676        */
 677       virtual void
 678       setScheme(const std::string &scheme);
 679
 680
 681       // -----------------
 682       /**
 683        * \brief Set the authority component in the URL.
 684        *
 685        * The \p authority string shoud not contain any leading
 686        * "//" separator characters (just "user:pass@host:port").
 687        *
 688        * \param authority The authority component string.
 689        * \throws std::invalid_argument exception if the \p authority
 690        *         parameter contains an invalid character.
 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 std::invalid_argument exception if the encoded
 700        *         \p user parameter contains an invalid character.
 701        */
 702       virtual void
 703       setUsername(const std::string &user,
 704                   EEncoding         eflag);
 705
 706       /**
 707        * \brief Set the password in the URL authority.
 708        * \param pass  The new password.
 709        * \param eflag If the \p password is encoded or not.
 710        * \throws std::invalid_argument exception if the encoded
 711        *         \p pass parameter contains an invalid character.
 712        */
 713       virtual void
 714       setPassword(const std::string &pass,
 715                   EEncoding         eflag);
 716
 717       /**
 718        * \brief Set the hostname or IP in the URL authority.
 719        *
 720        * The \p host parameter may contain a hostname, an IPv4 address
 721        * in dotted-decimal form or an IPv6 address literal encapsulated
 722        * within square brackets (RFC3513, Sect. 2.2).
 723        *
 724        * A hostname may contain national alphanumeric UTF8 characters
 725        * (letters other than ASCII a-zA-Z), that will be encoded.
 726        * This function allows to specify both, a encoded or decoded
 727        * hostname.
 728        *
 729        * Other IP literals in "[v ... ]" square bracket format are not
 730        * supported by the implementation in UrlBase class.
 731        *
 732        * \param host The new hostname or IP address.
 733        * \throws std::invalid_argument exception if the host is invalid.
 734        */
 735       virtual void
 736       setHost(const std::string &host);
 737
 738       /**
 739        * \brief Set the port number in the URL authority.
 740        * \param port The new port number.
 741        * \throws std::invalid_argument exception if the port is invalid.
 742        */
 743       virtual void
 744       setPort(const std::string &port);
 745
 746
 747       // -----------------
 748       /**
 749        * \brief Set the path data component in the URL.
 750        *
 751        * By default, the \p pathdata string may include path
 752        * parameters separated by the ";" separator character.
 753        *
 754        * \param pathdata The encoded path data component string.
 755        * \throws std::invalid_argument exception if the
 756        *         \p pathdata parameter contains an invalid character.
 757        */
 758       virtual void
 759       setPathData(const std::string &pathdata);
 760
 761       /**
 762        * \brief Set the path name.
 763        * \param path  The new path name.
 764        * \param eflag If the \p path name is encoded or not.
 765        * \throws std::invalid_argument exception if the encoded
 766        *         \p path parameter contains an invalid character.
 767        */
 768       virtual void
 769       setPathName(const std::string &path,
 770                   EEncoding         eflag);
 771
 772       /**
 773        * \brief Set the path parameters.
 774        * \param params The new encoded path parameter string.
 775        * \throws std::invalid_argument exception if the
 776        *         \p params parameter contains an invalid character.
 777        */
 778       virtual void
 779       setPathParams(const std::string &params);
 780
 781       /**
 782        * \brief Set the path parameters.
 783        * \param pvec The vector with encoded path parameters.
 784        * \throws std::invalid_argument exception if the
 785        *         \pvec parameter contains an invalid character.
 786        */
 787       virtual void
 788       setPathParamsVec(const zypp::url::ParamVec &pvec);
 789
 790       /**
 791        * \brief Set the path parameters.
 792        * \param pmap The map with decoded path parameters.
 793        * \throws std::logic_error exception if parameter parsing
 794        *         is not supported for a URL (scheme).
 795        */
 796       virtual void
 797       setPathParamsMap(const zypp::url::ParamMap &pmap);
 798
 799       /**
 800        * \brief Set or add value for the specified path parameter.
 801        * \param param The decoded path parameter name.
 802        * \param value The decoded path parameter value.
 803        * \throws std::logic_error exception if parameter parsing
 804        *         is not supported for a URL (scheme).
 805        * \throws std::invalid_argument exception if a decoded
 806        *         string would contain a '\\0' character.
 807        */
 808       virtual void
 809       setPathParam(const std::string &param, const std::string &value);
 810
 811
 812       // -----------------
 813       /**
 814        * \brief Set the query string in the URL.
 815        *
 816        * The \p querystr string parameter is supposed
 817        * to not to contain the "?" URL query separator
 818        * character (use just a "foo=bar&x=22" instead
 819        * of "?foo=bar&x=22").
 820        *
 821        * \param querystr The new encoded query string.
 822        * \throws std::invalid_argument exception if the
 823        *         \p querystr parameter contains an invalid character.
 824        */
 825       virtual void
 826       setQueryString(const std::string &querystr);
 827
 828       /**
 829        * \brief Set the query parameters.
 830        * \param qvec The vector with encoded query parameters.
 831        * \throws std::invalid_argument exception if the
 832        *         \p qvec parameter contains an invalid character.
 833        */
 834       virtual void
 835       setQueryStringVec(const zypp::url::ParamVec &qvec);
 836
 837       /**
 838        * \brief Set the query parameters.
 839        * \param qmap The map with decoded query parameters.
 840        * \throws std::logic_error exception if parameter parsing
 841        *         is not supported for a URL (scheme).
 842        */
 843       virtual void
 844       setQueryStringMap(const zypp::url::ParamMap &qmap);
 845
 846       /**
 847        * \brief Set or add value for the specified query parameter.
 848        * \param param The decoded query parameter name.
 849        * \param value The decoded query parameter value.
 850        * \throws std::logic_error exception if parameter parsing
 851        *         is not supported for a URL (scheme).
 852        * \throws std::invalid_argument exception if a decoded
 853        *         string would contain a '\\0' character.
 854        */
 855       virtual void
 856       setQueryParam(const std::string &param, const std::string &value);
 857
 858
 859       // -----------------
 860       /**
 861        * \brief Set the fragment string in the URL.
 862        * \param fragment The new fragment string.
 863        * \param eflag If the \p fragment is encoded or not.
 864        * \throws std::invalid_argument exception if the encoded
 865        *         \p fragment parameter contains an invalid character.
 866        */
 867       virtual void
 868       setFragment(const std::string &fragment,
 869                   EEncoding         eflag);
 870
 871
 872       // -----------------
 873       /**
 874        * Configures behaviour of the instance.
 875        *
 876        * This method is called in UrlBase constructors before
 877        * any URL components are applied.
 878        * Derived classes may reimplement this method to change
 879        * the behaviour of the object.
 880        * Use the config() methods to query and change them.
 881        *
 882        * The UrlBase class uses following config variables:
 883        *
 884        * - Common path parameter separators:
 885        *   - \a \c sep_pathparams   \c ";"
 886        *     Separator used to split path parameters from path name.
 887        *     Setting it to empty string disables splitting of path
 888        *     name and path parameters. Set also rx_pathparams to an
 889        *     empty string.
 890        *   - \a \c psep_pathparam   \c ","
 891        *     Separator between path parameters.
 892        *   - \a \c vsep_pathparam   \c "="
 893        *     Separator between key and value of a path parameter.
 894        *   .
 895        * .
 896        *
 897        * - Common query string separators:
 898        *   - \a \c psep_querystr    \c "&"
 899        *     Separator between query string parameters.
 900        *   - \a \c vsep_querystr    \c "="
 901        *     Separator between key and value of a query parameter.
 902        *   .
 903        * .
 904        *
 905        * - Characters in URL components, that are safe without
 906        *   URL percent-encoding (see zypp::url::encode()).
 907        *   - \a safe_username
 908        *   - \a safe_password
 909        *   - \a safe_hostname
 910        *   - \a safe_pathname
 911        *   - \a safe_pathparams
 912        *   - \a safe_querystr
 913        *   - \a safe_fragment
 914        *   .
 915        * .
 916        *
 917        * - Regular expressions used to verify encoded URL
 918        *   components and their sub-components:
 919        *   - \a rx_username
 920        *   - \a rx_password
 921        *   - \a rx_pathname
 922        *   - \a rx_pathparams
 923        *   - \a rx_querystr
 924        *   - \a rx_fragment
 925        *   .
 926        * .
 927        */
 928       virtual void
 929       configure();
 930
 931
 932       /**
 933        * Get the value of a UrlBase configuration variable.
 934        *
 935        * See configure() method for names an purpose of the
 936        * configuration variables used in UrlBase class.
 937        *
 938        * \param opt The name of the configuration variable.
 939        * \return The value of the specified variable
 940        *         or empty string.
 941        */
 942       std::string
 943       config(const std::string &opt) const;
 944
 945       /**
 946        * Set the value of a UrlBase configuration variable.
 947        *
 948        * See configure() method for names an purpose of the
 949        * configuration variables used in UrlBase class.
 950        *
 951        * \param opt The name of the configuration variable.
 952        * \param val The new value for the configuration variable.
 953        */
 954       void
 955       config(const std::string &opt, const std::string &val);
 956
 957
 958       /**
 959        * Return the view options of the current object.
 960        *
 961        * This method is used to query the view options
 962        * used by the toString() method.
 963        *
 964        * \return The current view option combination.
 965        */
 966       ViewOptions
 967       getViewOptions() const;
 968
 969       /**
 970        * Change the view options of the current object.
 971        *
 972        * This method is used to change the view options
 973        * used by the toString() method.
 974        *
 975        * \param vopts New view options combination.
 976        */
 977       void
 978       setViewOptions(const ViewOptions &vopts);
 979
 980
 981     protected:
 982       /**
 983        * Utility method to cleanup a path name.
 984        *
 985        * By default, this method replaces multiple occurences
 986        * of the "/" characeter from the begining of the path,
 987        * so the cleaned path begins with at most one "/".
 988        *
 989        * This operation is required in some cases to not to
 990        * missinterpret multiple "/" occurences as an empty
 991        * URL authority.
 992        *
 993        * \param path   A path name to cleanup.
 994        * \return A path begining with at most one "/" character.
 995        */
 996       virtual std::string
 997       cleanupPathName(const std::string &path);
 998
 999       /**
1000        * \brief Verifies specified host or IP.
1001        *
1002        * It verifies, if the specified \p host parameter contains
1003        * a hostname, an IPv4 address in dotted-decimal form or an
1004        * IPv6 address literal encapsulated within square brackets
1005        * (RFC3513, Sect. 2.2).
1006        *
1007        * A hostname in the \p host parameter, may contain national
1008        * alphanumeric UTF8 characters (letters other than ASCII
1009        * a-zA-Z) and allows to specify both, a encoded or decoded
1010        * hostname.
1011        *
1012        * This function does not perform any hostname lookups and
1013        * supports only IPv6 addresses in "[ ... ]" notation. The
1014        * "[v ... ]" square bracket format is not supported by
1015        * this implementation.
1016        *
1017        * \param  host  The host name or IP to verify.
1018        * \return True, if host seems to be valid.
1019        */
1020       virtual bool
1021       isValidHost(const std::string &host);
1022
1023       /**
1024        * \brief Verifies specified port number.
1025        *
1026        * \param  port  The port number to verify.
1027        * \return True, if port number is valid.
1028        */
1029       virtual bool
1030       isValidPort(const std::string &port);
1031
1032     private:
1033       UrlBaseData *m_data;
1034     };
1035
1036
1037     // ---------------------------------------------------------------
1038     /**
1039      * \brief Copy-On-Write Url reference.
1040      */
1041     typedef RWCOW_pointer<UrlBase>          UrlRef;
1042
1043
1044     //////////////////////////////////////////////////////////////////
1045   } // namespace url
1046   ////////////////////////////////////////////////////////////////////
1047
1048   ////////////////////////////////////////////////////////////////////
1049 } // namespace zypp
1050 //////////////////////////////////////////////////////////////////////
1051
1052 #endif /* ZYPP_URL_URLBASE_H */
1053 /*
1054 ** vim: set ts=2 sts=2 sw=2 ai et:
1055 */