1 /*---------------------------------------------------------------------\
3 | |__ / \ / / . \ . \ |
8 \---------------------------------------------------------------------*/
15 #include <zypp/url/UrlBase.h>
16 #include <zypp/url/UrlUtils.h>
19 //////////////////////////////////////////////////////////////////////
21 { ////////////////////////////////////////////////////////////////////
24 namespace hotfix1050625 {
25 std::string asString( const Url & url_r );
27 namespace filesystem {
30 using filesystem::Pathname;
34 * \brief Url manipulation class.
36 * The generic URL (URI) syntax and its main components are defined in
37 * RFC3986 (http://rfc.net/rfc3986.html) Section 3, "Syntax Components".
38 * The scheme specific URL syntax and semantics is defined in the
39 * specification of the particular scheme. See also RFC1738
40 * (http://rfc.net/rfc1738.html), that defines specific syntax for
41 * several URL schemes.
43 * This class provides methods to access and manipulate generic and
44 * common scheme-specific URL components (or using the more general
45 * term, URI components).
46 * To consider the scheme-specifics of a URL, the Url class contains
47 * a reference object pointing to a UrlBase or derived object, that
48 * implements the scheme specifics.
50 * Using the Url::registerScheme() method, it is possible to register
51 * a preconfigured or derived UrlBase object for a specific scheme
52 * name. The registered object will be cloned to handle all URLs
53 * containing the specified scheme name.
55 * \par RFC3986, Syntax Components:
57 * The generic URI syntax consists of a hierarchical sequence of
58 * components referred to as the scheme, authority, path, query,
62 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
64 * hier-part = "//" authority path-abempty
70 * The scheme and path components are required, though the path may be
71 * empty (no characters).
72 * When authority is present, the path must either be empty or begin
73 * with a slash ("/") character.
74 * When authority is not present, the path cannot begin with two slash
76 * These restrictions result in five different ABNF rules for a path
77 * (Section 3.3), only one of which will match any given URI reference.
79 * The following are two example URIs and their component parts:
81 * foo://example.com:8042/over/there?name=ferret#nose
82 * \_/ \______________/\_________/ \_________/ \__/
84 * scheme authority path query fragment
85 * | _____________________|__
87 * urn:example:animal:ferret:nose
97 typedef zypp::url::EEncoding EEncoding;
102 typedef zypp::url::ViewOptions ViewOptions;
109 * Create a new Url object as shared copy of the given one.
111 * Upon return, both objects will point to the same underlying
112 * object. This state will remain until one of the object is
115 * \param url The Url object to make a copy of.
116 * \throws url::UrlException if copy fails (should not happen).
122 * Create a new Url object as shared copy of the given reference.
124 * Upon return, both objects will point to the same underlying
125 * object. This state will remain until one of the object is
128 * \param url The URL implementation reference to make a copy of.
129 * \throws url::UrlException if reference is empty.
131 Url(const zypp::url::UrlRef &url);
135 * \brief Construct a Url object from percent-encoded URL string.
137 * Parses the \p encodedUrl string using the parseUrl() method
138 * and assigns the result to the newly created object.
140 * \param encodedUrl A percent-encoded URL string.
141 * \throws url::UrlParsingException if parsing of the url fails.
142 * \throws url::UrlNotAllowedException if one of the components
143 * is not allowed for the scheme.
144 * \throws url::UrlBadComponentException if one of the components
145 * contains an invalid character.
147 Url(const std::string &encodedUrl);
152 * \brief Parse a percent-encoded URL string.
154 * Tries to parse the given string into generic URL components
155 * and creates a clone of a scheme-specialized object or a new
158 * \param encodedUrl A percent-encoded URL string.
159 * \return A reference to a (derived) UrlBase object or
160 * empty reference if the \p encodedUrl string
161 * does not match the generic URL syntax.
162 * \throws url::UrlNotAllowedException if one of the components
163 * is not allowed for the scheme.
164 * \throws url::UrlBadComponentException if one of the components
165 * contains an invalid character.
168 parseUrl(const std::string &encodedUrl);
173 * \brief Assigns parsed percent-encoded URL string to the object.
175 * Parses \p encodedUrl string using the parseUrl() method
176 * and assigns the result to the current object.
178 * \param encodedUrl A percent-encoded URL string.
179 * \return A reference to this Url object.
180 * \throws url::UrlParsingException if parsing of the url fails.
181 * \throws url::UrlNotAllowedException if one of the components
182 * is not allowed for the scheme.
183 * \throws url::UrlBadComponentException if one of the components
184 * contains an invalid character.
187 operator = (const std::string &encodedUrl);
191 * \brief Assign a shared copy of \p url to the current object.
193 * Upon return, both objects will point to the same underlying
194 * object. This state will remain until one of the objects is
197 * \param url The Url object to make a copy of.
198 * \return A reference to this Url object.
201 operator = (const Url &url);
206 * \brief Register a scheme-specific implementation.
208 * \param scheme A name of a scheme.
209 * \param urlImpl A UrlBase object specialized for this scheme.
210 * \return True, if the object claims to implement the scheme.
213 registerScheme(const std::string &scheme,
214 url::UrlRef urlImpl);
217 * \brief Returns all registered scheme names.
218 * \return A vector with registered URL scheme names.
220 static zypp::url::UrlSchemes
221 getRegisteredSchemes();
224 * \brief Returns if scheme name is registered.
225 * \return True, if scheme name is registered.
228 isRegisteredScheme(const std::string &scheme);
233 * \brief Returns scheme names known to this object.
234 * \return A vector with scheme names known by this object.
236 zypp::url::UrlSchemes
237 getKnownSchemes() const;
241 * \brief Verifies the specified scheme name.
243 * Verifies the generic syntax of the specified \p scheme name
244 * and if it is contained in the current object's list of known
245 * schemes (see getKnownSchemes()) if the list is not empty.
247 * The default implementation in the UrlBase class returns an
248 * emtpy list of known schemes, causing a check of the generic
251 * \return True, if generic scheme name syntax is valid and
252 * the scheme name is known to the current object.
255 isValidScheme(const std::string &scheme) const;
258 /** hd cd dvd dir file iso */
259 static bool schemeIsLocal( const std::string & scheme_r );
260 /** \overload nonstatic version */
261 bool schemeIsLocal() const { return schemeIsLocal( getScheme() ); }
263 /** nfs nfs4 smb cifs http https ftp sftp tftp */
264 static bool schemeIsRemote( const std::string & scheme_r );
265 /** \overload nonstatic version */
266 bool schemeIsRemote() const { return schemeIsRemote( getScheme() ); }
269 static bool schemeIsVolatile( const std::string & scheme_r );
270 /** \overload nonstatic version */
271 bool schemeIsVolatile() const { return schemeIsVolatile( getScheme() ); }
273 /** http https ftp sftp tftp */
274 static bool schemeIsDownloading( const std::string & scheme_r );
275 /** \overload nonstatic version */
276 bool schemeIsDownloading() const { return schemeIsDownloading( getScheme() ); }
279 * \brief Verifies the Url.
281 * Verifies if the current object contains a non-empty scheme
282 * name. Additional semantical URL checks may be performed by
283 * derived UrlBase objects.
285 * \return True, if the Url seems to be valid.
293 * Returns a default string representation of the Url object.
295 * By default, a password in the URL will be hidden.
297 * \return A default string representation of the Url object.
303 * Returns a string representation of the Url object.
305 * To include a password in the resulting Url string, use:
307 * url.asString(url.getViewOptions() +
308 * url::ViewOptions::WITH_PASSWORD);
311 * \param opts A combination of view options.
312 * \return A string representation of the Url object.
315 asString(const ViewOptions &opts) const;
318 * Returns a complete string representation of the Url object.
320 * This function ignores the configuration of the view options
321 * in the current object (see setViewOption()) and forces to
322 * return a string with all URL components included.
324 * \return A complete string representation of the Url object.
327 asCompleteString() const;
332 * Returns the scheme name of the URL.
333 * \return Scheme name of the current Url object.
341 * Returns the encoded authority component of the URL.
343 * The returned authority string does not contain the leading
344 * "//" separator characters, but just its "user:pass@host:port"
347 * \return The encoded authority component string.
350 getAuthority() const;
353 * Returns the username from the URL authority.
354 * \param eflag Flag if the usename should be percent-decoded or not.
355 * \return The username sub-component from the URL authority.
356 * \throws url::UrlDecodingException if the decoded result string
357 * would contain a '\\0' character.
360 getUsername(EEncoding eflag = zypp::url::E_DECODED) const;
363 * Returns the password from the URL authority.
364 * \param eflag Flag if the password should be percent-decoded or not.
365 * \return The password sub-component from the URL authority.
366 * \throws url::UrlDecodingException if the decoded result string
367 * would contain a '\\0' character.
370 getPassword(EEncoding eflag = zypp::url::E_DECODED) const;
373 * Returns \c true if username \b and password are encoded in the authority component.
375 bool hasCredentialsInAuthority() const
376 { return ! ( getUsername().empty() || getPassword().empty() ); }
379 * Returns the hostname or IP from the URL authority.
381 * In case the Url contains an IP number, it may be surrounded
382 * by "[" and "]" characters, for example "[::1]" for an IPv6
385 * \param eflag Flag if the host should be percent-decoded or not.
386 * \return The host sub-component from the URL authority.
387 * \throws url::UrlDecodingException if the decoded result string
388 * would contain a '\\0' character.
391 getHost(EEncoding eflag = zypp::url::E_DECODED) const;
394 * Returns the port from the URL authority.
395 * \return The port sub-component from the URL authority.
403 * Returns the encoded path component of the URL.
405 * The path data contains the path name, optionally
406 * followed by path parameters separated with a ";"
407 * character, for example "/foo/bar;version=1.1".
409 * \return The encoded path component of the URL.
415 * Returns the path name from the URL.
416 * \param eflag Flag if the path should be decoded or not.
417 * \return The path name sub-component without path parameters
418 * from Path-Data component of the URL.
419 * \throws url::UrlDecodingException if the decoded result string
420 * would contain a '\\0' character.
423 getPathName(EEncoding eflag = zypp::url::E_DECODED) const;
426 * Returns the path parameters from the URL.
427 * \return The encoded path parameters from the URL.
430 getPathParams() const;
433 * Returns a vector with path parameter substrings.
435 * The default path parameter separator is the \c ',' character.
436 * A schema specific object may overide the default separators.
438 * For example, the path parameters string "foo=1,bar=2" is splited
439 * by default into a vector containing the substrings "foo=1" and
442 * \return The path parameters splited into a vector of substrings.
445 getPathParamsVec() const;
448 * Returns a string map with path parameter keys and values.
450 * The default path parameter separator is the \c ',' character,
451 * the default key/value separator for the path parameters is
452 * the \c '=' character.
453 * A schema specific object may overide the default separators.
455 * For example, the path parameters string "foo=1,bar=2" is splited
456 * into a map containing "foo" = "1" and "bar" = "2" by default.
458 * \param eflag Flag if the path parameter keys and values should
460 * \return The path parameters key and values as a string map.
461 * \throws url::UrlNotSupportedException if parameter parsing
462 * is not supported for a URL (scheme).
463 * \throws url::UrlDecodingException if the decoded result string
464 * would contain a '\\0' character.
467 getPathParamsMap(EEncoding eflag = zypp::url::E_DECODED) const;
470 * Return the value for the specified path parameter.
472 * For example, if the path parameters string is "foo=1,bar=2"
473 * the method will return the substring "1" for the param key
474 * "foo" and "2" for the param key "bar".
476 * \param param The path parameter key.
477 * \param eflag Flag if the path parameter keys and values should
479 * \return The value for the path parameter key or empty string.
480 * \throws url::UrlNotSupportedException if parameter parsing
481 * is not supported for a URL (scheme).
482 * \throws url::UrlDecodingException if the decoded result string
483 * would contain a '\\0' character.
486 getPathParam(const std::string ¶m,
487 EEncoding eflag = zypp::url::E_DECODED) const;
492 * Returns the encoded query string component of the URL.
494 * The query string is returned without first "?" (separator)
495 * character. Further "?" characters as in e.g. LDAP URLs
496 * remain in the returned string.
498 * \return The encoded query string component of the URL.
501 getQueryString() const;
504 * Returns a vector with query string parameter substrings.
506 * The default query string parameter separator is the \c '&'
508 * A schema specific object may overide the default separators.
510 * For example, the query string "foo=1&bar=2" is splited by
511 * default into a vector containing the substrings "foo=1" and
514 * \return The query string splited into a vector of substrings.
517 getQueryStringVec() const;
520 * Returns a string map with query parameter and their values.
522 * The default query string parameter separator is the \c ','
523 * character, the default key/value separator the \c '=' character.
524 * A schema specific object may overide the default separators.
526 * For example, the query string "foo=1&bar=2" is splited by
527 * default into a map containing "foo" = "1" and "bar" = "2".
529 * \param eflag Flag if the query string keys and values should
531 * \return The query string as a key/value string map.
532 * \throws url::UrlNotSupportedException if parameter parsing
533 * is not supported for a URL (scheme).
534 * \throws url::UrlDecodingException if the decoded result string
535 * would contain a '\\0' character.
538 getQueryStringMap(EEncoding eflag = zypp::url::E_DECODED) const;
541 * Return the value for the specified query parameter.
543 * For example, if the query string is "foo=1,bar=2" the method
544 * will return the substring "1" for the param key "foo" and
545 * "2" for the param key "bar".
547 * \param param The query parameter key.
548 * \param eflag Flag if the query parameter keys and values should
550 * \return The value for the query parameter key or empty string.
551 * \throws url::UrlNotSupportedException if parameter parsing
552 * is not supported for a URL (scheme).
553 * \throws url::UrlDecodingException if the decoded result string
554 * would contain a '\\0' character.
557 getQueryParam(const std::string ¶m,
558 EEncoding eflag = zypp::url::E_DECODED) const;
563 * Returns the encoded fragment component of the URL.
564 * \param eflag Flag if the fragment should be percent-decoded or not.
565 * \return The encoded fragment component of the URL.
566 * \throws url::UrlDecodingException if the decoded result string
567 * would contain a '\\0' character.
570 getFragment(EEncoding eflag = zypp::url::E_DECODED) const;
575 * \brief Set the scheme name in the URL.
576 * \param scheme The new scheme name.
577 * \throws url::UrlBadComponentException if the \p scheme
578 * contains an invalid character or is empty.
581 setScheme(const std::string &scheme);
586 * \brief Set the authority component in the URL.
588 * The \p authority string shoud contain the "user:pass@host:port"
589 * sub-components without any leading "//" separator characters.
591 * \param authority The encoded authority component string.
592 * \throws url::UrlNotAllowedException if the \p authority
593 * has to be empty in for the current scheme.
594 * \throws url::UrlBadComponentException if the \p authority
595 * contains an invalid character.
596 * \throws url::UrlParsingException if \p authority parsing fails.
599 setAuthority(const std::string &authority);
602 * \brief Set the username in the URL authority.
603 * \param user The new username.
604 * \param eflag If the \p username is encoded or not.
605 * \throws url::UrlNotAllowedException if the \p user
606 * has to be empty in for the current scheme
607 * \throws url::UrlBadComponentException if the \p user
608 * contains an invalid character.
611 setUsername(const std::string &user,
612 EEncoding eflag = zypp::url::E_DECODED);
615 * \brief Set the password in the URL authority.
616 * \param pass The new password.
617 * \param eflag If the \p password is encoded or not.
618 * \throws url::UrlNotAllowedException if the \p pass
619 * has to be empty in for the current scheme.
620 * \throws url::UrlBadComponentException if the \p pass
621 * contains an invalid character.
624 setPassword(const std::string &pass,
625 EEncoding eflag = zypp::url::E_DECODED);
628 * \brief Set the hostname or IP in the URL authority.
630 * The \p host parameter may contain a hostname, an IPv4 address
631 * in dotted-decimal form or an IPv6 address literal encapsulated
632 * within square brackets (RFC3513, Sect. 2.2).
634 * A hostname may contain national alphanumeric UTF8 characters
635 * (letters other than ASCII a-z0-9), that will be encoded.
636 * This function allows to specify both, a encoded or decoded
639 * Other IP literals in "[v ... ]" square bracket format are not
640 * supported by the implementation in UrlBase class.
642 * \param host The new hostname or IP address.
643 * \throws url::UrlNotAllowedException if the \p host (authority)
644 * has to be empty in for the current scheme.
645 * \throws url::UrlBadComponentException if the \p host is invalid.
648 setHost(const std::string &host);
651 * \brief Set the port number in the URL authority.
652 * \param port The new port number.
653 * \throws url::UrlNotAllowedException if the \p port (authority)
654 * has to be empty in for the current scheme.
655 * \throws url::UrlBadComponentException if the \p port is invalid.
658 setPort(const std::string &port);
663 * \brief Set the path data component in the URL.
665 * By default, the \p pathdata string may include path
666 * parameters separated by the ";" separator character.
668 * \param pathdata The encoded path data component string.
669 * \throws url::UrlBadComponentException if the \p pathdata
670 * contains an invalid character.
673 setPathData(const std::string &pathdata);
676 * \brief Set the path name.
677 * \param path The new path name.
678 * \param eflag If the \p path name is encoded or not.
679 * \throws url::UrlBadComponentException if the \p path name
680 * contains an invalid character.
683 setPathName(const std::string &path,
684 EEncoding eflag = zypp::url::E_DECODED);
687 setPathName(const Pathname &path,
688 EEncoding eflag = zypp::url::E_DECODED);
691 setPathName(const char *path,
692 EEncoding eflag = zypp::url::E_DECODED);
695 * \brief Extend the path name.
697 void appendPathName( const Pathname & path_r, EEncoding eflag_r = zypp::url::E_DECODED );
700 * \brief Set the path parameters.
701 * \param params The new encoded path parameter string.
702 * \throws url::UrlBadComponentException if the path \p params
703 * contains an invalid character.
706 setPathParams(const std::string ¶ms);
709 * \brief Set the path parameters.
710 * \param pvec The vector with encoded path parameters.
711 * \throws url::UrlBadComponentException if the \p pvec
712 * contains an invalid character.
715 setPathParamsVec(const zypp::url::ParamVec &pvec);
718 * \brief Set the path parameters.
719 * \param pmap The map with decoded path parameters.
720 * \throws url::UrlNotSupportedException if parameter parsing
721 * is not supported for a URL (scheme).
724 setPathParamsMap(const zypp::url::ParamMap &pmap);
727 * \brief Set or add value for the specified path parameter.
728 * \param param The decoded path parameter name.
729 * \param value The decoded path parameter value.
730 * \throws url::UrlNotSupportedException if parameter parsing
731 * is not supported for a URL (scheme).
732 * \throws url::UrlDecodingException if the decoded result string
733 * would contain a '\\0' character.
736 setPathParam(const std::string ¶m, const std::string &value);
741 * \brief Set the query string in the URL.
742 * \param querystr The new encoded query string.
743 * \throws url::UrlBadComponentException if the \p querystr
744 * contains an invalid character.
747 setQueryString(const std::string &querystr);
750 * \brief Set the query parameters.
751 * \param qvec The vector with encoded query parameters.
752 * \throws url::UrlBadComponentException if the \p qvec
753 * contains an invalid character.
756 setQueryStringVec(const zypp::url::ParamVec &qvec);
759 * \brief Set the query parameters.
760 * \param qmap The map with decoded query parameters.
761 * \throws url::UrlNotSupportedException if parameter parsing
762 * is not supported for a URL (scheme).
765 setQueryStringMap(const zypp::url::ParamMap &qmap);
768 * \brief Set or add value for the specified query parameter.
769 * \param param The decoded query parameter name.
770 * \param value The decoded query parameter value.
771 * \throws url::UrlNotSupportedException if parameter parsing
772 * is not supported for a URL (scheme).
773 * \throws url::UrlDecodingException if the decoded result string
774 * would contain a '\\0' character.
777 setQueryParam(const std::string ¶m, const std::string &value);
780 * \brief remove the specified query parameter.
781 * \param param The decoded query parameter name.
782 * \throws url::UrlNotSupportedException if parameter parsing
783 * is not supported for a URL (scheme).
784 * \throws url::UrlDecodingException if the decoded result string
785 * would contain a '\\0' character.
788 delQueryParam(const std::string ¶m);
793 * \brief Set the fragment string in the URL.
794 * \param fragment The new fragment string.
795 * \param eflag If the \p fragment is encoded or not.
796 * \throws url::UrlBadComponentException if the \p fragment
797 * contains an invalid character.
800 setFragment(const std::string &fragment,
801 EEncoding eflag = zypp::url::E_DECODED);
806 * Return the view options of the current object.
808 * This method is used to query the view options
809 * used by the asString() method.
811 * \return The current view option combination.
814 getViewOptions() const;
817 * Change the view options of the current object.
819 * This method is used to change the view options
820 * used by the asString() method.
822 * \param vopts New view options combination.
825 setViewOptions(const ViewOptions &vopts);
828 friend std::string hotfix1050625::asString( const Url & url_r );
832 std::ostream & operator<<( std::ostream & str, const Url & url );
835 * needed for std::set
837 bool operator<( const Url &lhs, const Url &rhs );
842 bool operator==( const Url &lhs, const Url &rhs );
845 bool operator!=( const Url &lhs, const Url &rhs );
847 ////////////////////////////////////////////////////////////////////
849 //////////////////////////////////////////////////////////////////////
851 #endif /* ZYPP_URL_H */
853 ** vim: set ts=2 sts=2 sw=2 ai et: