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