//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
/**
* @class Uri
- * @brief This class provides useful methods for URI.
+ * @brief This class provides methods for managing URI.
*
* @since 2.0
*
- * The %Uri class represents a Uniform Resource Identifier (URI) as defined by RFC2396 and provides accessors
- * which access the URI component.
- * It also provides methods for creating, accessing, normalizing, resolving, and relativizing %Uri instances.
+ * The %Uri class represents a Uniform Resource Identifier (URI) as defined by RFC2396 and provides methods
+ * for managing URI.
+ * The %Uri class provides methods for creating, accessing, normalizing, resolving, and relativizing %Uri instances.
*
* For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/uri.htm">URI</a>.
*
* void
* MyClass::UriSample(void)
* {
- * String base(L"http://www.samsung.com");
- * String against(L"/osp/framework/index.html");
- * String resolveString(L"http://www.samsung.com/osp/framework/index.html");
+ * String base(L"https://developer.tizen.org");
+ * String against(L"/downloads/tizen-sdk");
+ * String resolveString(L"https://developer.tizen.org/downloads/tizen-sdk");
*
* Uri baseUri;
* baseUri.SetUri(base);
* {
* // ...
* }
- *
* }
* @endcode
*/
virtual ~Uri(void);
/**
- * Sets the current %Uri instance to the value of the specified instance of %Uri.
+ * Sets the current %Uri instance with the value of the specified %Uri instance.
*
* @since 2.0
*
- * @param[in] uri An instance of %Uri
+ * @param[in] uri An instance of %Uri to set
*/
void SetUri(const Uri& uri);
/**
- * Sets the current %Uri instance by parsing a given string.
+ * Sets the current %Uri instance by parsing the specified string.
*
* @since 2.0
*
* @return An error code
- * @param[in] str A string to parse into a URI
+ * @param[in] str The string to parse for URI value
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c str is an empty string.
* @exception E_INVALID_FORMAT The specified @c str violates the URI syntax (RFC 2396).
result SetUri(const Tizen::Base::String& str);
/**
- * Sets an absolute %Uri instance with given components.
+ * Sets an absolute %Uri instance with specified components.
*
* @since 2.0
*
* @return An error code
- * @param[in] scheme The scheme
- * @param[in] ssp The scheme-specific-part
- * @param[in] fragment The fragment
+ * @param[in] scheme The scheme
+ * @param[in] ssp The scheme-specific-part
+ * @param[in] fragment The fragment
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_FORMAT A component violates the URI syntax(RFC 2396).
+ * @exception E_INVALID_FORMAT A specified component violates the URI syntax(RFC 2396).
*/
result SetUri(const Tizen::Base::String& scheme, const Tizen::Base::String& ssp, const Tizen::Base::String& fragment);
* @since 2.0
*
* @return An error code
- * @param[in] scheme The scheme
- * @param[in] userInfo The user name and authorization
- * @param[in] host The host name
- * @param[in] port The port number
- * @param[in] path The path
- * @param[in] query The query
- * @param[in] fragment The fragment
+ * @param[in] scheme The scheme
+ * @param[in] userInfo The user name and authorization
+ * @param[in] host The host name
+ * @param[in] port The port number
+ * @param[in] path The path
+ * @param[in] query The query
+ * @param[in] fragment The fragment
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_FORMAT A component violates the URI syntax(RFC 2396).
+ * @exception E_INVALID_FORMAT A specified component violates the URI syntax(RFC 2396).
*/
result SetUri(const Tizen::Base::String& scheme, const Tizen::Base::String& userInfo, const Tizen::Base::String& host, int port, const Tizen::Base::String& path, const Tizen::Base::String& query, const Tizen::Base::String& fragment);
* @since 2.0
*
* @return An error code
- * @param[in] scheme The scheme
- * @param[in] host The host name
- * @param[in] path The path
- * @param[in] fragment The fragment
+ * @param[in] scheme The scheme
+ * @param[in] host The host name
+ * @param[in] path The path
+ * @param[in] fragment The fragment
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_FORMAT A component violates the URI syntax(RFC 2396).
+ * @exception E_INVALID_FORMAT A specified component violates the URI syntax(RFC 2396).
* @remarks The authority and query component are left empty, and the port is set to @c -1.
*/
result SetUri(const Tizen::Base::String& scheme, const Tizen::Base::String& host, const Tizen::Base::String& path, const Tizen::Base::String& fragment);
* @since 2.0
*
* @return An error code
- * @param[in] scheme The scheme
- * @param[in] authority The authority
- * @param[in] path The path
- * @param[in] query The query
- * @param[in] fragment The fragment
+ * @param[in] scheme The scheme
+ * @param[in] authority The authority
+ * @param[in] path The path
+ * @param[in] query The query
+ * @param[in] fragment The fragment
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_FORMAT A component violates the URI syntax(RFC 2396).
+ * @exception E_INVALID_FORMAT A specified component violates the URI syntax(RFC 2396).
*/
result SetUri(const Tizen::Base::String& scheme, const Tizen::Base::String& authority, const Tizen::Base::String& path, const Tizen::Base::String& query, const Tizen::Base::String& fragment);
* @return The value of the authority component, @n
* else an empty string if the authority component is undefined
* @remarks The string returned by this method is equal to the string returned by GetEncodedAuthority(),
- * except that all sequences of the escaped octets are decoded.
+ * except that all the sequences of the escaped octets are decoded.
*/
Tizen::Base::String GetAuthority(void) const;
* @return The value of the fragment component, @n
* else an empty string if the fragment component is undefined
* @remarks The string returned by this method is equal to the string returned by GetEncodedFragment(),
- * except that all sequences of the escaped octets are decoded.
+ * except that all the sequences of the escaped octets are decoded.
*/
Tizen::Base::String GetFragment(void) const;
* @return The value of the path component, @n
* else an empty string if the path component is undefined
* @remarks The string returned by this method is equal to the string returned by GetEncodedPath(),
- * except that all sequences of the escaped octets are decoded.
+ * except that all the sequences of the escaped octets are decoded.
*/
Tizen::Base::String GetPath(void) const;
* @return The value of the query component, @n
* else an empty string if the query component is undefined
* @remarks The string returned by this method is equal to the string returned by GetEncodedQuery(),
- * except that all sequences of the escaped octets are decoded.
+ * except that all the sequences of the escaped octets are decoded.
*/
Tizen::Base::String GetQuery(void) const;
* @return The value of the scheme-specific-part component, @n
* else an empty string if the scheme-specific-part component is undefined
* @remarks The string returned by this method is equal to the string returned by GetEncodedSchemeSpecificPart(),
- * except that all sequences of the escaped octets are decoded.
+ * except that all the sequences of the escaped octets are decoded.
*/
Tizen::Base::String GetSchemeSpecificPart(void) const;
* @return The value of the user-info component, @n
* else an empty string if the user-info component is undefined
* @remarks The string returned by this method is equal to the string returned by GetEncodedUserInfo(),
- * except that all sequences of the escaped octets are decoded.
+ * except that all the sequences of the escaped octets are decoded.
*/
Tizen::Base::String GetUserInfo(void) const;
/**
- * Checks whether the calling %Uri instance is an opaque URI.
+ * Checks whether the current %Uri instance is an opaque URI.
*
* @since 2.0
*
* The following example demonstrates how to use the %GetEncodedString() method.
*
* @code
- * String str(L"http://www.sec.com/osp?currency==\u20ac");
+ * String str(L"https://www.tizen.org/?currency==\u20ac");
*
* Uri uri;
* uri.SetUri(str);
*
- * String encode = uri.GetEncodedString(); // encode == L"http://www.sec.com/osp?currency==%E2%82%AC"
+ * String encode = uri.GetEncodedString(); // encode == L"https://www.tizen.org/?currency==%E2%82%AC"
*
* @endcode
*/
Tizen::Base::String GetEncodedString(void) const;
/**
- * Compares the calling URI instance to the specified %Uri instance. @n
+ * Compares the current URI instance with the specified %Uri instance. @n
* When comparing corresponding components of two URIs, if one component in the current instance is undefined
* but the other is defined, then the current instance is considered to be less than the given object.
*
* = 0 if the current instance is equal to the given object
* > 0 if the current instance is greater than the given object
* @endcode
- * @param[in] uri An instance of %Uri
+ * @param[in] uri An instance of %Uri to compare
* @remarks
*
* Ordering of URIs
* to the ordering of fragments, without regard to case.
* 5. Authority
* If two hierarchical URIs have identical schemes, they are ordered according to the authority,
- * without regard to the case.
+ * without regard to the case. @n
* 5-1. Server-based authority
* If two URIs are server-based, they are ordered according to their user-information,
* without regard to case.
*
* @return @c true if the two instances are equal, @n
* else @c false
- * @param[in] obj The object to compare with the current instance
- * @remarks Two equal instances must return the same hash value. The default
- * implementation of this method returns @c true if two instances
- * have the same address. @n
- * The method can be overridden to support value equality. Furthermore, the Equals()
+ * @param[in] obj The object to compare with the current instance
+ * @remarks
+ * - Two equal instances must return the same hash value. @n The default
+ * implementation of this method returns @c true if the two instances
+ * have the same address.
+ * - The method can be overridden to support value equality. Furthermore, the Equals()
* method must return the same results as the equality operator.
*/
virtual bool Equals(const Tizen::Base::Object& obj) const;
* @since 2.0
*
* @return The hash value of the current instance
- * @remarks Two equal instances must return the same hash value. For better performance,
- * the used hash function must generate a random distribution for all inputs.
+ * @remarks Two equal instances must return the same hash value. @n
+ * For better performance, the used hash function must generate a random distribution for all inputs.
*/
virtual int GetHashCode(void) const;
* @return The normalized URI, @n
* else the current URI in case any error occurs
* @remarks Normalization is the process of removing unnecessary "." and ".." segments from the path component of the
- * hierarchical URI. All "." segments are removed and If a ".." segment is preceded by a non-".." segment,
- * both of these segments are removed. If a URI is opaque, the normalization has no effect.
+ * hierarchical URI. All "." segments are removed.
+ * If a ".." segment is preceded by a non-".." segment,
+ * both the segments are removed. If a URI is opaque, the normalization has no effect.
*
* The following example demonstrates how to use the %Normalize() method.
*
* @param[out] uri The parsed URI
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The authority component is defined but cannot be parsed as a server-based authority.
- * @remarks This method is provided because the generic URI syntax cannot always distinguish a malformed server-based authority from a legitimate registry-based authority.
+ * @remarks This method is provided because the generic URI syntax cannot always distinguish a malformed server-based authority from a legitimate registry-based authority. @n
* For example, the authority component in the URI string "//foo:bar/" is not a legal
* server-based authority but it is legal as a registry-based authority.
*/
/**
- * Relativizes the specified %Uri instance against the calling %Uri instance.
+ * Relativizes the specified %Uri instance against the current %Uri instance.
*
* @since 2.0
*
* @return An error code
- * @param[in] uri The %Uri to relativize against the calling %Uri
+ * @param[in] uri The %Uri to relativize against the current %Uri instance
* @param[out] resultUri The relativized URI
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @remarks Relativization is the opposite of Resolution. It is used
- * to divide a URI into the base URI and the relative URI.
+ * @remarks
+ * - Relativization is the opposite of Resolution.
+ * - It is used to divide a URI into the base URI and the relative URI.
*/
result Relativize(const Uri& uri, Uri& resultUri);
/**
- * Resolves the specified %Uri instance against the calling %Uri instance.
+ * Resolves the specified %Uri instance against the current %Uri instance.
*
* @since 2.0
*
* @param[out] resultUri The resolved URI
* @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
- * @remarks Resolution is the process of resolving a URI against another, base URI. For hierarchical URI,
- * the path of the original is resolved against the path of the base URI and then normalized. @n
- *
- * For example, to resolve the URI "/osp/framework/index.html" against the base URI "http://www.samsung.com" ,
- * the resultant URI is "http://www.samsung.com/osp/framework/index.html".
- *
+ * @remarks
+ * - Resolution is the process of resolving a URI against another, base URI.
+ * - For a hierarchical URI, the path of the original URI is resolved against the path of the base URI and then normalized. @n
+ * For example, when you resolve the URI "/downloads/tizen-sdk" against the base URI "https://developer.tizen.org",
+ * the resultant URI is "https://developer.tizen.org/downloads/tizen-sdk".
*/
result Resolve(const Uri& uri, Uri& resultUri);
* @since 2.0
*
* @return An error code
- * @param[in] authority The authority
+ * @param[in] authority The authority to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
/**
- * Sets the fragment component to the specified String instance.
+ * Sets the fragment component to the specified String instance
*
* @since 2.0
*
* @return An error code
- * @param[in] fragment The new fragment
+ * @param[in] fragment The fragment to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
* @since 2.0
*
* @return An error code
- * @param[in] host The new host
+ * @param[in] host The host to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
* @since 2.0
*
* @return An error code
- * @param[in] path The new path component
+ * @param[in] path The path to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
* @since 2.0
*
* @return An error code
- * @param[in] port The new port component
+ * @param[in] port The port to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified @c port is negative.
*/
* @since 2.0
*
* @return An error code
- * @param[in] query The new query string
+ * @param[in] query The query to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
* @since 2.0
*
* @return An error code
- * @param[in] scheme The new scheme
+ * @param[in] scheme The scheme to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
* @since 2.0
*
* @return An error code
- * @param[in] ssp The new scheme-specific-part component
+ * @param[in] ssp The scheme-specific-part to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
* @since 2.0
*
* @return An error code
- * @param[in] userInfo The new user-info string
+ * @param[in] userInfo The user-info to set
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_FORMAT The specified string is invalid.
*/
/**
- * Gets the content of the calling %Uri instance as a string containing escaped octets.
+ * Gets the content of the current %Uri instance as a string containing escaped octets.
*
* @since 2.0
*
- * @return The content of this URI as a string containing escaped octets
+ * @return The content of the current %Uri instance as a string containing escaped octets
*/
Tizen::Base::String ToString(void) const;