initial commit

2025-09-01 20:47:58 +08:00
commit 12c51b5ddb
843 changed files with 475321 additions and 0 deletions
@@ -0,0 +1,272 @@
+//
+// HTTPCookie.h
+//
+// Library: Net
+// Package: HTTP
+// Module:  HTTPCookie
+//
+// Definition of the HTTPCookie class.
+//
+// Copyright (c) 2005-2006, Applied Informatics Software Engineering GmbH.
+// and Contributors.
+//
+// SPDX-License-Identifier:	BSL-1.0
+//
+
+
+#ifndef Net_HTTPCookie_INCLUDED
+#define Net_HTTPCookie_INCLUDED
+
+
+#include "Poco/Net/Net.h"
+
+
+namespace Poco {
+namespace Net {
+
+
+class NameValueCollection;
+
+
+class Net_API HTTPCookie
+	/// This class represents a HTTP Cookie.
+	///
+	/// A cookie is a small amount of information sent by a Web 
+	/// server to a Web browser, saved by the browser, and later sent back 
+	/// to the server. A cookie's value can uniquely identify a client, so 
+	/// cookies are commonly used for session management.
+	///
+	/// A cookie has a name, a single value, and optional attributes such 
+	/// as a comment, path and domain qualifiers, a maximum age, and a 
+	/// version number.
+	///
+	/// This class supports both the Version 0 (by Netscape) and Version 1 
+	/// (by RFC 2109) cookie specifications. By default, cookies are created 
+	/// using Version 0 to ensure the best interoperability.
+{
+public:
+	HTTPCookie();
+		/// Creates an empty HTTPCookie.
+		
+	explicit HTTPCookie(const std::string& name);
+		/// Creates a cookie with the given name.	
+		/// The cookie never expires.
+		
+	explicit HTTPCookie(const NameValueCollection& nvc);
+		/// Creates a cookie from the given NameValueCollection.
+		
+	HTTPCookie(const std::string& name, const std::string& value);
+		/// Creates a cookie with the given name and value.
+		/// The cookie never expires.
+		///
+		/// Note: If value contains whitespace or non-alphanumeric
+		/// characters, the value should be escaped by calling escape()
+		/// before passing it to the constructor.
+		
+	HTTPCookie(const HTTPCookie& cookie);
+		/// Creates the HTTPCookie by copying another one.
+
+	~HTTPCookie();
+		/// Destroys the HTTPCookie.
+		
+	HTTPCookie& operator = (const HTTPCookie& cookie);
+		/// Assigns a cookie.
+		
+	void setVersion(int version);
+		/// Sets the version of the cookie.
+		///
+		/// Version must be either 0 (denoting a Netscape cookie)
+		/// or 1 (denoting a RFC 2109 cookie).
+		
+	int getVersion() const;
+		/// Returns the version of the cookie, which is
+		/// either 0 or 1.	
+		
+	void setName(const std::string& name);
+		/// Sets the name of the cookie.
+		
+	const std::string& getName() const;
+		/// Returns the name of the cookie.
+		
+	void setValue(const std::string& value);
+		/// Sets the value of the cookie.
+		///
+		/// According to the cookie specification, the
+		/// size of the value should not exceed 4 Kbytes.
+		///
+		/// Note: If value contains whitespace or non-alphanumeric
+		/// characters, the value should be escaped by calling escape()
+		/// prior to passing it to setName().
+		
+	const std::string& getValue() const;
+		/// Returns the value of the cookie.
+		
+	void setComment(const std::string& comment);
+		/// Sets the comment for the cookie.
+		///
+		/// Comments are only supported for version 1 cookies.
+
+	const std::string& getComment() const;
+		/// Returns the comment for the cookie.
+
+	void setDomain(const std::string& domain);
+		/// Sets the domain for the cookie.
+		
+	const std::string& getDomain() const;
+		/// Returns the domain for the cookie.
+
+	void setPath(const std::string& path);
+		/// Sets the path for the cookie.
+
+	void setPriority(const std::string& priority);
+		/// Sets the priority for the cookie.
+		
+	const std::string& getPath() const;
+		/// Returns the path for the cookie.
+
+	const std::string& getPriority() const;
+		/// Returns the priority for the cookie.
+
+	void setSecure(bool secure);
+		/// Sets the value of the secure flag for
+		/// the cookie.
+		
+	bool getSecure() const;
+		/// Returns the value of the secure flag
+		/// for the cookie.
+
+	void setMaxAge(int maxAge);
+		/// Sets the maximum age in seconds for
+		/// the cookie.
+		///
+		/// A value of -1 (default) causes the cookie 
+		/// to become a session cookie, which will
+		/// be deleted when the browser window
+		/// is closed.
+		///
+		/// A value of 0 deletes the cookie on
+		/// the client.
+
+	int getMaxAge() const;
+		/// Returns the maximum age in seconds for
+		/// the cookie.
+		
+	void setHttpOnly(bool flag = true);
+		/// Sets the HttpOnly flag for the cookie.
+		
+	bool getHttpOnly() const;
+		/// Returns true iff the cookie's HttpOnly flag is set.
+		
+	std::string toString() const;
+		/// Returns a string representation of the cookie,
+		/// suitable for use in a Set-Cookie header.
+		
+	static std::string escape(const std::string& str);
+		/// Escapes the given string by replacing all 
+		/// non-alphanumeric characters with escape
+		/// sequences in the form %xx, where xx is the
+		/// hexadecimal character code.
+		///
+		/// The following characters will be replaced
+		/// with escape sequences:
+		///   - percent sign %
+		///   - less-than and greater-than < and >
+		///   - curly brackets { and }
+		///   - square brackets [ and ]
+		///   - parenthesis ( and )
+		///   - solidus /
+		///   - vertical line |
+		///   - reverse solidus (backslash /)
+		///   - quotation mark "
+		///   - apostrophe '
+		///   - circumflex accent ^
+		///   - grave accent `
+		///   - comma and semicolon , and ;
+		///   - whitespace and control characters
+		
+	static std::string unescape(const std::string& str);
+		/// Unescapes the given string by replacing all
+		/// escape sequences in the form %xx with the
+		/// respective characters.
+
+private:
+	int         _version;
+	std::string _name;
+	std::string _value;
+	std::string _comment;
+	std::string _domain;
+	std::string _path;
+	std::string _priority;
+	bool        _secure;
+	int         _maxAge;
+	bool        _httpOnly;
+};
+
+
+//
+// inlines
+//
+inline int HTTPCookie::getVersion() const
+{
+	return _version;
+}
+
+
+inline const std::string& HTTPCookie::getName() const
+{
+	return _name;
+}
+
+
+inline const std::string& HTTPCookie::getValue() const
+{
+	return _value;
+}
+
+
+inline const std::string& HTTPCookie::getComment() const
+{
+	return _comment;
+}
+
+
+inline const std::string& HTTPCookie::getDomain() const
+{
+	return _domain;
+}
+
+
+inline const std::string& HTTPCookie::getPath() const
+{
+	return _path;
+}
+
+
+inline const std::string& HTTPCookie::getPriority() const
+{
+	return _priority;
+}
+
+
+inline bool HTTPCookie::getSecure() const
+{
+	return _secure;
+}
+
+
+inline int HTTPCookie::getMaxAge() const
+{
+	return _maxAge;
+}
+
+
+inline bool HTTPCookie::getHttpOnly() const
+{
+	return _httpOnly;
+}
+
+
+} } // namespace Poco::Net
+
+
+#endif // Net_HTTPCookie_INCLUDED