

//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
//_/_/
//_/_/  This file is part of CMSDK version 2.1.1.260726 (26 July 2026)
//_/_/  
//_/_/  developed by
//_/_/  
//_/_/  Communicative Machines Ltd. 
//_/_/    http://cmlabs.com/
//_/_/  Copyright (c) 2026
//_/_/  
//_/_/  in collaboration with 
//_/_/  
//_/_/  Icelandic Institute for Intelligent Machines ses
//_/_/    Menntavegur 1
//_/_/    101 Reykjavik
//_/_/    ICELAND
//_/_/    http://www.iiim.is/
//_/_/
//_/_/  and is released under the following
//_/_/  
//_/_/  EXTENDED BSD License
//_/_/
//_/_/  Redistribution and use in source and binary forms, with or without
//_/_/  modification, is permitted provided that the following conditions 
//_/_/  are met:
//_/_/
//_/_/  - Redistributions of source code must retain the above copyright 
//_/_/    and collaboration notice, this list of conditions and the following 
//_/_/    disclaimer.
//_/_/
//_/_/  - Redistributions in binary form must reproduce the above copyright 
//_/_/    notice, this list of conditions and the following disclaimer in the 
//_/_/    documentation and/or other materials provided with the distribution.
//_/_/
//_/_/  - Neither the name of its copyright holders nor the names of its 
//_/_/    contributors may be used to endorse or promote products derived from 
//_/_/    this software without specific prior written permission.
//_/_/
//_/_/  - CADIA Clause: The license granted in and to the software under this 
//_/_/    agreement is a limited-use license. The software may not be used in 
//_/_/    furtherance of: (i) intentionally causing bodily injury or severe 
//_/_/    emotional harm to any person; (ii) invading the personal privacy or 
//_/_/    violating the human rights of any person; or (iii) committing or 
//_/_/    preparing for any act of war. 
//_/_/
//_/_/  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
//_/_/  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
//_/_/  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 
//_/_/  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 
//_/_/  OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
//_/_/  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
//_/_/  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
//_/_/  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
//_/_/  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
//_/_/  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
//_/_/  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//_/_/
//_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
/*! @file HTML.h
	@brief HTML/URL helper utilities: entity encoding/decoding, MIME type lookup and URL component parsing.

	Small, dependency-light helpers used throughout the networking stack
	(NetworkProtocols, NetworkManager's built-in HTTP server, RequestGateway
	web serving). Two families of functions live here:

	- @b HTML @b text handling: entity encode/decode (e.g. "&amp;amp;" &harr; "&amp;")
	  and MIME type resolution from file extensions, used when serving files
	  over HTTP.
	- @b URL @b parsing: extraction of protocol, host, port, URI path and
	  embedded basic-auth credentials from URL strings such as
	  "https://user:pass@host:8080/path?x=1".

	All functions are stateless and thread-safe (no shared mutable state);
	std::string arguments are taken by value and results returned by value.

	@ingroup Networking
*/
#if !defined(_HTML_H_)
#define _HTML_H_

#include "Utils.h"

namespace cmlabs {
namespace html {

/*! Decode HTML entities in a string (e.g. "&amp;lt;" to "<", "&amp;#65;" to "A").
	@param str Input string possibly containing HTML entities.
	@return The decoded plain-text string. */
std::string DecodeHTML(std::string str);
/*! Encode a plain string for safe embedding in HTML (e.g. "<" to "&amp;lt;").
	@param str Input plain-text string.
	@return The entity-encoded string. */
std::string EncodeHTML(std::string str);

/*! Convert a single HTML entity (e.g. "&amp;amp;" or "&amp;#38;") to its character.
	@param str Pointer to the entity text (starting at or after '&').
	@return The decoded character, or 0 if the entity is not recognised. */
unsigned char HTML2Char(const char* str);

/*! Look up the MIME type for a filename based on its extension.
	@param dest Caller-provided buffer receiving the MIME type string (e.g. "text/html").
	@param filename File name or path whose extension determines the type.
	@param maxsize Capacity of @p dest in bytes (output is truncated to fit).
	@return true if a type was written (falls back to a default for unknown extensions), false on invalid arguments. */
bool GetMimeType(char* dest, const char* filename, uint32 maxsize);
/*! Look up the MIME type for a filename and report whether it is binary.
	@param dest Caller-provided buffer receiving the MIME type string.
	@param filename File name or path whose extension determines the type.
	@param maxsize Capacity of @p dest in bytes.
	@param isBinary Set to true when the content should be treated as binary
	(no text transformations, Content-Length required), false for text types.
	@return true if a type was written, false on invalid arguments. */
bool GetMimeType(char* dest, const char* filename, uint32 maxsize, bool &isBinary);
/*! Determine whether a MIME type denotes binary content.
	@param type MIME type string, e.g. "image/png".
	@return true for binary types, false for textual types (text&#47;&lowast;, JSON, XML, etc.). */
bool IsMimeBinary(const char* type);

/*! Extract the username from a URL of the form scheme://user:pass\@host/...
	@param url Full URL string.
	@return The username, or an empty string if none is present. */
std::string GetUsernameFromURL(std::string url);
/*! Extract the password from a URL of the form scheme://user:pass\@host/...
	@param url Full URL string.
	@return The password, or an empty string if none is present. */
std::string GetPasswordFromURL(std::string url);
/*! Extract the full "user:pass" authentication section from a URL.
	@param url Full URL string.
	@return The "user:pass" text before the '\@', or an empty string if absent. */
std::string GetAuthenticationFromURL(std::string url);
/*! Extract the host name (or IP literal) from a URL.
	@param url Full URL string.
	@return The host portion without protocol, credentials, port or path. */
std::string GetHostFromURL(std::string url);
/*! Extract the port number from a URL.
	@param url Full URL string.
	@return The explicit port if given; otherwise the scheme default
	(80 for http, 443 for https), or 0 if it cannot be determined. */
uint16 GetPortFromURL(std::string url);
/*! Extract the protocol/scheme from a URL.
	@param url Full URL string.
	@return The scheme (e.g. "http", "https", "ws"), or an empty string if absent. */
std::string GetProtocolFromURL(std::string url);
/*! Extract the URI (path plus query) from a URL.
	@param url Full URL string.
	@return The path starting at '/', including any query string; "/" if the URL has no explicit path. */
std::string GetURIFromURL(std::string url);

/*! Self-contained unit test of the HTML/URL helpers.
	@return true when all checks pass. */
bool HTML_UnitTest();

} // namespace html
} // namespace cmlabs

#endif //_UTILS_H_

