/** * @file include/ActivMiddleware/ActivBase/Url.h * * @brief Url parser & builder class. */ #if (!defined ACTIV_BASE_URL_H) #define ACTIV_BASE_URL_H #include "ActivMiddleware/ActivBase/External.h" #include "ActivMiddleware/ActivBase/Ip/IpAddress.h" #include "ActivMiddleware/ActivBase/MessageValidator.h" #include "ActivMiddleware/ActivBase/StatusCodeException.h" #include "ActivMiddleware/ActivBase/StringException.h" #include "ActivMiddleware/Misc/StringView.h" #include //! Activ namespace. namespace Activ { /** * @brief Url parser & builder class. * * A Url is of the form 'protocol://location/path?parameter?parameter' * 'parameter' is of the form 'key=value' * Other accepted parameter delimiters in addition to '?' are ',' '&' * Another accepted key/value delimiter is ':'. */ class Url { public: typedef std::pair Parameter; ///< Parameter type (key, value). typedef std::list ParameterList; ///< Parameter list type. //! Default constructor. Url(); /** * @brief Constructor. * * @param url * * @throw StatusCodeException */ Url(const String &url); /** * @brief Parse a url into the class members. * * @param url the url to parse. * * @retval STATUS_CODE_SUCCESS * @retval STATUS_CODE_INVALID_FORMAT */ ACTIV_BASE_API StatusCode Parse(const String &url); /** * @brief Build a url from the component parts. * * @return The url string. */ ACTIV_BASE_API const String Build() const; #if (!defined ACTIV_LITE_FRAMEWORK) /** * @brief Get an ip address from the location. * * @return IpAddress * * @throw Exception * @throw std::exception */ ACTIV_BASE_API const IpAddress GetIpAddress() const; #endif // (!defined ACTIV_LITE_FRAMEWORK) /** * @brief Get host and port from the location. * * @param host reference to a string to receive the host portion of the location. * @param portNumber reference to a variable to receive the optional port number portion location. * * @return false if the location could not be parsed. * * @throw Exception if this object has not been initialized with a url string. */ ACTIV_BASE_API bool GetHostAndPort(String &host, Boost::optional &portNumber) const; /** * @brief Parse just the parameter part of a url into a ParameterList. * * @param parameterString * @param parameterList to receive the parsed parameters. Not initially cleared down. */ ACTIV_BASE_API static void ParseParameterString(const String ¶meterString, ParameterList ¶meterList); /** * @brief Build the parameter part of a url from a ParameterList. * * @param parameterList * * @return The parameter part of a url. */ ACTIV_BASE_API static String BuildParameterString(const ParameterList ¶meterList); /** * @brief Build a url from the component parts. * * @param protocol the protocol to build the url with. * @param location the location to build the url with. * @param path the path to build the url with. * @param parameterList the parameterList to build the url with. * * @return The url string. */ ACTIV_BASE_API static const String Build(const String &protocol, const String &location, const String &path, const ParameterList ¶meterList); //! Get the character used to delimit values in a parameter's value list. ACTIV_BASE_API static char GetValueListDelimiter(); /** * @brief Decode a (potentially) URL encoded string. * * @tparam ALWAYS_COPY whether to copy @a string to @a decodedString even if it is not encoded. * @tparam S a string-like type. * * @param string the source string. * @param decodedString a String to receive the decoded string (if decoding is required or ALWAYS_COPY is true). * * @return A CxxYZ::string_view to the decoded string (which will refer to @a string if ALWAYS_COPY is false and no decoding * was required, otherwise @a decodedString). * * @throw std::exception if decoding fails. */ template static CxxYZ::string_view Decode(const S &string, String &decodedString); String m_protocol; ///< Protocol portion of the url. String m_location; ///< Location portion of the url. String m_path; ///< Path portion of the url. ParameterList m_parameterList; ///< Parameter list portion of the url. private: /** * @brief Parse an optional parameter. * * @param parameterString a string containing the parameter. * @param parameterList the list to append a Parameter object to containing the parsed key and value. */ static void ParseParameter(const String ¶meterString, ParameterList ¶meterList); String m_fixedString; String m_parameterString; }; // --------------------------------------------------------------------------------------------------------------------------------- inline Url::Url() { } // --------------------------------------------------------------------------------------------------------------------------------- inline Url::Url(const String &url) { ACTIV_THROW_RESULT_IF(STATUS_CODE_SUCCESS, != ,Parse(url)); } // --------------------------------------------------------------------------------------------------------------------------------- template CxxYZ::string_view Url::Decode(const S &string, String &decodedString) { size_t stringOffset = 0, lastDecodedOffset = 0; for (const char *pChar = string.data(); (stringOffset < string.length()); ++pChar, ++stringOffset) { if ('%' == *pChar) { if (0 == lastDecodedOffset) decodedString.assign(string.data(), (stringOffset - lastDecodedOffset)); else decodedString.append(string.data() + lastDecodedOffset, (stringOffset - lastDecodedOffset)); const size_t hexStringLength = 2; if (ACTIV_UNLIKELY((string.length() - stringOffset) <= hexStringLength)) { ACTIV_BOOST_THROW_EXCEPTION(StringException( String("Url::Decode(\"") + ToStringType(string) + "\") failed; invalid length at offset " + TypeToString(stringOffset))); } byte_t decodedChar; StatusCode statusCode = MessageValidator(pChar + 1, hexStringLength).ValidateAsciiHexadecimalIntegral< MessageValidator::ENDIAN_LITTLE>(hexStringLength, decodedChar); if (ACTIV_UNLIKELY(STATUS_CODE_SUCCESS != statusCode)) { ACTIV_BOOST_THROW_EXCEPTION(StringException( String("Url::Decode(\"") + ToStringType(string) + "\") failed; " + StatusCodeToString(statusCode) + " at offset " + TypeToString(stringOffset))); } decodedString.append(1, static_cast(decodedChar)); pChar += hexStringLength; stringOffset += hexStringLength; lastDecodedOffset = stringOffset + 1; } } if (0 != lastDecodedOffset) { decodedString.append(string.data() + lastDecodedOffset, (stringOffset - lastDecodedOffset)); return CxxYZ::string_view(decodedString.data(), decodedString.length()); } else if (ALWAYS_COPY) { decodedString.assign(string.data(), string.length()); return CxxYZ::string_view(decodedString.data(), decodedString.length()); } else { return CxxYZ::string_view(string.data(), string.length()); } } } // namespace Activ #endif // (!defined ACTIV_BASE_URL_H)