From 04152f05a917eb1056d8beebafae5ff757bd3c88 Mon Sep 17 00:00:00 2001 From: peri4 Date: Thu, 14 Aug 2025 14:07:52 +0300 Subject: [PATCH] some autogen docs --- .../client_server/piclientserver_client.h | 8 ++ .../piclientserver_client_base.h | 39 ++++++++++ .../client_server/piclientserver_server.h | 29 +++++++ libs/main/http_client/pihttpclient.h | 28 +++++++ libs/main/http_common/pihttptypes.h | 75 +++++++++++++++++++ libs/main/http_server/microhttpd_server.h | 59 +++++++++++++-- libs/main/http_server/pihttpserver.h | 30 +++++++- 7 files changed, 261 insertions(+), 7 deletions(-) diff --git a/libs/main/client_server/piclientserver_client.h b/libs/main/client_server/piclientserver_client.h index 20ebe99f..24e45eb0 100644 --- a/libs/main/client_server/piclientserver_client.h +++ b/libs/main/client_server/piclientserver_client.h @@ -33,6 +33,8 @@ namespace PIClientServer { // ServerClient +//! ~english Server-side client implementation +//! ~russian Серверная реализация клиента class PIP_CLIENT_SERVER_EXPORT ServerClient: public ClientBase { friend class Server; NO_COPY_CLASS(ServerClient); @@ -41,6 +43,8 @@ public: ServerClient() {} protected: + //! ~english Called before client destruction + //! ~russian Вызывается перед уничтожением клиента virtual void aboutDelete() {} private: @@ -50,6 +54,8 @@ private: // Client +//! ~english Client implementation for connecting to servers +//! ~russian Клиентская реализация для подключения к серверам class PIP_CLIENT_SERVER_EXPORT Client: public ClientBase { NO_COPY_CLASS(Client); @@ -57,6 +63,8 @@ public: Client(); ~Client(); + //! ~english Connects to specified server address + //! ~russian Подключается к указанному адресу сервера void connect(PINetworkAddress addr); protected: diff --git a/libs/main/client_server/piclientserver_client_base.h b/libs/main/client_server/piclientserver_client_base.h index 2f0d7560..844da0d1 100644 --- a/libs/main/client_server/piclientserver_client_base.h +++ b/libs/main/client_server/piclientserver_client_base.h @@ -37,6 +37,8 @@ class Server; class ClientInterface {}; +//! ~english Base class for client-server communication with diagnostics support +//! ~russian Базовый класс для клиент-серверного взаимодействия с поддержкой диагностики // template class PIP_CLIENT_SERVER_EXPORT ClientBase { friend class Server; @@ -46,16 +48,39 @@ public: ClientBase(); virtual ~ClientBase(); + //! ~english Gets underlying TCP connection + //! ~russian Возвращает TCP-соединение const PIEthernet * getTCP() const { return tcp; } + //! ~english Closes the connection + //! ~russian Закрывает соединение void close(); + + //! ~english Gracefully stops and waits for completion + //! ~russian Плавно останавливает и ожидает завершения void stopAndWait(); + + //! ~english Writes byte array to the connection + //! ~russian Записывает массив байтов в соединение int write(const void * d, const size_t s); + + //! ~english Writes byte array to the connection + //! ~russian Записывает массив байтов в соединение int write(const PIByteArray & ba) { return write(ba.data(), ba.size()); } + + //! ~english Enables diagnostics collection + //! ~russian Включает сбор диагностики void enableDiagnostics(); + + //! ~english Gets current diagnostics state + //! ~russian Возвращает текущее состояние диагностики PIDiagnostics::State diagnostics() const; + + + //! ~english Gets current received packet bytes already received (all bytes count passed in \a receivePacketStart()) + //! ~russian Возвращает сколько байт принимаемого пакета получено (общее количество передается в \a receivePacketStart()) int receivePacketProgress() const; const PIStreamPackerConfig & configuration() const { return stream.configuration(); } @@ -63,10 +88,24 @@ public: void setConfiguration(const PIStreamPackerConfig & config) { stream.setConfiguration(config); } protected: + //! ~english Called when data is received + //! ~russian Вызывается при получении данных virtual void readed(PIByteArray data) {} + + //! ~english Called when connection is established + //! ~russian Вызывается при установке соединения virtual void connected() {} + + //! ~english Called when connection is closed + //! ~russian Вызывается при закрытии соединения virtual void disconnected() {} + + //! ~english Called when packet receiving starts + //! ~russian Вызывается при начале получения пакета virtual void receivePacketStart(int size) {} + + //! ~english Called when packet receiving ends + //! ~russian Вызывается при завершении получения пакета virtual void receivePacketEnd() {} void init(); diff --git a/libs/main/client_server/piclientserver_server.h b/libs/main/client_server/piclientserver_server.h index 5e30f033..f66eca5f 100644 --- a/libs/main/client_server/piclientserver_server.h +++ b/libs/main/client_server/piclientserver_server.h @@ -38,6 +38,8 @@ namespace PIClientServer { class ServerClient; +//! ~english TCP server for client-server communication +//! ~russian TCP сервер для клиент-серверного взаимодействия class PIP_CLIENT_SERVER_EXPORT Server: public PIStreamPackerConfig { friend class ServerClient; NO_COPY_CLASS(Server); @@ -46,17 +48,44 @@ public: Server(); virtual ~Server(); + //! ~english Starts listening on specified address + //! ~russian Начинает прослушивание на указанном адресе void listen(PINetworkAddress addr); + + //! ~english Starts listening on all interfaces + //! ~russian Начинает прослушивание на всех интерфейсах void listenAll(ushort port) { listen({0, port}); } + + //! ~english Stops the server + //! ~russian Останавливает сервер void stopServer(); + + //! ~english Closes all client connections + //! ~russian Закрывает все клиентские соединения void closeAll(); + + //! ~english Gets maximum allowed clients + //! ~russian Возвращает максимальное число клиентов int getMaxClients() const { return max_clients; } + + //! ~english Sets maximum allowed clients + //! ~russian Устанавливает максимальное число клиентов void setMaxClients(int new_max_clients); + + //! ~english Gets current clients count + //! ~russian Возвращает текущее количество клиентов int clientsCount() const; + + + //! ~english Executes function for each connected client + //! ~russian Выполняет функцию для каждого подключённого клиента void forEachClient(std::function func); + + //! ~english Sets factory for creating new client instances + //! ~russian Устанавливает фабрику для создания клиентских экземпляров void setClientFactory(std::function f) { client_factory = f; } private: diff --git a/libs/main/http_client/pihttpclient.h b/libs/main/http_client/pihttpclient.h index ed270d51..01bff413 100644 --- a/libs/main/http_client/pihttpclient.h +++ b/libs/main/http_client/pihttpclient.h @@ -13,23 +13,51 @@ public: }; +//! ~english Main HTTP client class for performing requests with event callbacks. +//! ~russian Основной класс HTTP-клиента для выполнения запросов с callback-ми событий. class PIP_HTTP_CLIENT_EXPORT PIHTTPClient: private PIHTTPClientBase { friend class PIHTTPClientBase; friend class CurlThreadPool; public: + //! ~english Creates a new HTTP request instance with the specified URL, method and message. + //! ~russian Создает новый экземпляр HTTP-запроса с указанным URL, методом и сообщением. static PIHTTPClient * create(const PIString & url, PIHTTP::Method method = PIHTTP::Method::Get, const PIHTTP::MessageConst & req = {}); + //! ~english Sets a callback for successful request completion (no parameters). + //! ~russian Устанавливает callback для успешного завершения запроса (без параметров). PIHTTPClient * onFinish(std::function f); + + //! ~english Sets a callback for successful request completion (with response). + //! ~russian Устанавливает callback для успешного завершения запроса (с ответом). PIHTTPClient * onFinish(std::function f); + + //! ~english Sets a callback for request errors (no parameters). + //! ~russian Устанавливает callback для ошибок запроса (без параметров). PIHTTPClient * onError(std::function f); + + //! ~english Sets a callback for request errors (with error response). + //! ~russian Устанавливает callback для ошибок запроса (с ответом об ошибке). PIHTTPClient * onError(std::function f); + + //! ~english Sets a callback for request abortion (no parameters). + //! ~russian Устанавливает callback для прерывания запроса (без параметров). PIHTTPClient * onAbort(std::function f); + + //! ~english Sets a callback for request abortion (with abort response). + //! ~russian Устанавливает callback для прерывания запроса (с ответом о прерывании). PIHTTPClient * onAbort(std::function f); + //! ~english Starts the HTTP request execution. + //! ~russian Начинает выполнение HTTP-запроса. void start(); + + //! ~english Aborts the current HTTP request. + //! ~russian Прерывает текущий HTTP-запрос. void abort(); + //! ~english Returns the last error message. + //! ~russian Возвращает последнее сообщение об ошибке. PIString lastError() const { return last_error; } private: diff --git a/libs/main/http_common/pihttptypes.h b/libs/main/http_common/pihttptypes.h index b9b3ccad..96fc30a2 100644 --- a/libs/main/http_common/pihttptypes.h +++ b/libs/main/http_common/pihttptypes.h @@ -9,20 +9,60 @@ namespace PIHTTP { +//! ~english Immutable HTTP message container with accessors for message components +//! ~russian Контейнер для неизменяемого HTTP-сообщения с методами доступа к компонентам class PIP_EXPORT MessageConst { public: + //! ~english Gets the HTTP method used in the message + //! ~russian Возвращает HTTP-метод, использованный в сообщении PIHTTP::Method method() const { return m_method; } + + //! ~english Gets the HTTP status code + //! ~russian Возвращает HTTP-статус код PIHTTP::Code code() const { return m_code; } + + //! ~english Checks if status code is informational (1xx) + //! ~russian Проверяет, является ли статус код информационным (1xx) bool isCodeInformational() const; + + //! ~english Checks if status code indicates success (2xx) + //! ~russian Проверяет, указывает ли статус код на успех (2xx) bool isCodeSuccess() const; + + //! ~english Checks if status code indicates redirection (3xx) + //! ~russian Проверяет, указывает ли статус код на перенаправление (3xx) bool isCodeRedirection() const; + + //! ~english Checks if status code indicates client error (4xx) + //! ~russian Проверяет, указывает ли статус код на ошибку клиента (4xx) bool isCodeClientError() const; + + //! ~english Checks if status code indicates server error (5xx) + //! ~russian Проверяет, указывает ли статус код на ошибку сервера (5xx) bool isCodeServerError() const; + + //! ~english Checks if status code indicates any error (4xx or 5xx) + //! ~russian Проверяет, указывает ли статус код на любую ошибку (4xx или 5xx) bool isCodeError() const { return isCodeClientError() || isCodeServerError(); } + + //! ~english Gets the request/response path + //! ~russian Возвращает путь запроса/ответа const PIString & path() const { return m_path; } + + //! ~english Gets path components as list + //! ~russian Возвращает компоненты пути в виде списка PIStringList pathList() const { return m_path.split('/').removeAll({}); } + + //! ~english Gets the message body + //! ~russian Возвращает тело сообщения const PIByteArray & body() const { return m_body; } + + //! ~english Gets all message headers + //! ~russian Возвращает все заголовки сообщения const PIMap & headers() const { return m_headers; } + + //! ~english Gets all message arguments + //! ~russian Возвращает все аргументы сообщения const PIMap & arguments() const { return m_arguments; } protected: @@ -35,25 +75,60 @@ protected: }; +//! ~english Mutable HTTP message container with modifiers for message components +//! ~russian Контейнер для изменяемого HTTP-сообщения с методами модификации class PIP_EXPORT MessageMutable: public MessageConst { public: + //! ~english Sets the HTTP method + //! ~russian Устанавливает HTTP-метод MessageMutable & setMethod(PIHTTP::Method m); + + //! ~english Sets the HTTP status code + //! ~russian Устанавливает HTTP-статус код MessageMutable & setCode(PIHTTP::Code c); + + //! ~english Sets the request/response path + //! ~russian Устанавливает путь запроса/ответа MessageMutable & setPath(PIString p); + + //! ~english Sets the message body + //! ~russian Устанавливает тело сообщения MessageMutable & setBody(PIByteArray b); + const PIMap & headers() const { return m_headers; } const PIMap & arguments() const { return m_arguments; } PIMap & headers() { return m_headers; } + + //! ~english Adds a header to the message + //! ~russian Добавляет заголовок к сообщению MessageMutable & addHeader(const PIString & header, const PIString & value); + + //! ~english Removes a header from the message + //! ~russian Удаляет заголовок из сообщения MessageMutable & removeHeader(const PIString & header); + PIMap & arguments() { return m_arguments; } + + //! ~english Adds an argument to the message + //! ~russian Добавляет аргумент к сообщению MessageMutable & addArgument(const PIString & arg, const PIString & value); + + //! ~english Removes an argument from the message + //! ~russian Удаляет аргумент из сообщения MessageMutable & removeArgument(const PIString & arg); + + //! ~english Creates message from HTTP status code + //! ~russian Создает сообщение из HTTP-статус кода static MessageMutable fromCode(PIHTTP::Code c); + + //! ~english Creates message from HTTP method + //! ~russian Создает сообщение из HTTP-метода static MessageMutable fromMethod(PIHTTP::Method m); }; +//! ~english Gets string representation of HTTP method +//! ~russian Возвращает строковое представление HTTP-метода PIP_EXPORT const char * methodName(Method m); diff --git a/libs/main/http_server/microhttpd_server.h b/libs/main/http_server/microhttpd_server.h index 6c944e8c..812a8b0e 100644 --- a/libs/main/http_server/microhttpd_server.h +++ b/libs/main/http_server/microhttpd_server.h @@ -7,6 +7,8 @@ struct MicrohttpdServerConnection; +//! ~english Base HTTP server class implementing core functionality +//! ~runnan Базовый класс HTTP сервера, реализующий основную функциональность class PIP_HTTP_SERVER_EXPORT MicrohttpdServer: public PIObject { PIOBJECT(MicrohttpdServer) friend struct MicrohttpdServerConnection; @@ -15,30 +17,75 @@ public: MicrohttpdServer(); virtual ~MicrohttpdServer(); + //! ~english Server configuration options + //! ~russian Опции конфигурации сервера enum class Option { - ConnectionLimit, // uint - ConnectionTimeout, // uint, sec - HTTPSEnabled, // bool - HTTPSMemKey, // const char * to key.pem data - HTTPSMemCert, // const char * to cert.pem data - HTTPSKeyPassword // const char * to passwd for key.pem + ConnectionLimit, //!< ~english Maximum concurrent connections + //!< ~russian Максимальное количество соединений + ConnectionTimeout, //!< ~english Connection timeout in seconds + //!< ~russian Таймаут соединения в секундах + HTTPSEnabled, //!< ~english Enable HTTPS support + //!< ~russian Включить поддержку HTTPS + HTTPSMemKey, //!< ~english SSL key in memory (PIByteArray) + //!< ~russian SSL ключ в памяти (PIByteArray) + HTTPSMemCert, //!< ~english SSL certificate in memory (PIByteArray) + //!< ~russian SSL сертификат в памяти (PIByteArray) + HTTPSKeyPassword //!< ~english SSL key password (PIByteArray) + //!< ~russian Пароль SSL ключа (PIByteArray) }; + //! ~english Sets server option + //! ~russian Устанавливает опцию сервера void setOption(Option o, PIVariant v); + + //! ~english Sets server favicon + //! ~russian Устанавливает фавикон сервера void setFavicon(const PIByteArray & im); + + //! ~english Starts server on specified address + //! ~russian Запускает сервер на указанном адресе bool listen(PINetworkAddress addr); + + //! ~english Starts server on all interfaces + //! ~russian Запускает сервер на всех интерфейсах bool listenAll(ushort port) { return listen({0, port}); } + + //! ~english Checks if server is running + //! ~russian Проверяет, работает ли сервер bool isListen() const; + + //! ~english Stops the server + //! ~russian Останавливает сервер void stop(); + + //! ~english Enables basic authentication + //! ~russian Включает базовую аутентификацию void enableBasicAuth() { setBasicAuthEnabled(true); } + + //! ~english Disables basic authentication + //! ~russian Выключает базовую аутентификацию void disableBasicAuth() { setBasicAuthEnabled(false); } + + //! ~english Set basic authentication enabled to "yes" + //! ~russian Устанавливает базовую аутентификацию в "yes" void setBasicAuthEnabled(bool yes) { use_basic_auth = yes; } + + //! ~english Return if basic authentication enabled + //! ~russian Возвращает включена ли базовая аутентификация bool isBasicAuthEnabled() const { return use_basic_auth; } + + //! ~english Sets basic authentication realm + //! ~russian Устанавливает область аутентификации void setBasicAuthRealm(const PIString & r) { realm = r; } + //! ~english Sets request processing callback + //! ~russian Устанавливает callback для обработки запросов void setRequestCallback(std::function c) { callback = c; } + + //! ~english Sets basic authentication callback + //! ~russian Устанавливает callback для базовой аутентификации void setBasicAuthCallback(std::function c) { callback_auth = c; } private: diff --git a/libs/main/http_server/pihttpserver.h b/libs/main/http_server/pihttpserver.h index 0c3f82b4..166507ae 100644 --- a/libs/main/http_server/pihttpserver.h +++ b/libs/main/http_server/pihttpserver.h @@ -3,6 +3,8 @@ #include "microhttpd_server.h" +//! ~english HTTP server +//! ~russian HTTP сервер class PIP_HTTP_SERVER_EXPORT PIHTTPServer: public MicrohttpdServer { PIOBJECT_SUBCLASS(PIHTTPServer, MicrohttpdServer) @@ -12,24 +14,50 @@ public: using RequestFunction = std::function; + + //! ~english Registers handler for specific path and HTTP method + //! ~russian Регистрирует обработчик для указанного пути и HTTP метода void registerPath(const PIString & path, PIHTTP::Method method, RequestFunction functor); + + //! ~english Registers handler for specific path and HTTP method + //! ~russian Регистрирует обработчик для указанного пути и HTTP метода template void registerPath(const PIString & path, PIHTTP::Method method, T * o, PIHTTP::MessageMutable (T::*function)(const PIHTTP::MessageConst &)) { registerPath(path, method, [o, function](const PIHTTP::MessageConst & m) { return (o->*function)(m); }); } + + + //! ~english Registers handler for unhandled requests + //! ~russian Регистрирует обработчик для необработанных запросов void registerUnhandled(RequestFunction functor); + + //! ~english Registers handler for unhandled requests + //! ~russian Регистрирует обработчик для необработанных запросов template void registerUnhandled(T * o, PIHTTP::MessageMutable (T::*function)(const PIHTTP::MessageConst &)) { registerUnhandled([o, function](const PIHTTP::MessageConst & m) { return (o->*function)(m); }); } + + //! ~english Unregisters handler for specific path and method + //! ~russian Удаляет обработчик для указанного пути и метода void unregisterPath(const PIString & path, PIHTTP::Method method); + + //! ~english Unregisters all handlers for specific path + //! ~russian Удаляет все обработчики для указанного пути void unregisterPath(const PIString & path); - // void registerBasicAuth() {} + //! ~english Adds header to all server responses + //! ~russian Добавляет заголовок ко всем ответам сервера void addReplyHeader(const PIString & name, const PIString & value) { reply_headers[name] = value; } + + //! ~english Removes header from server responses + //! ~russian Удаляет заголовок из ответов сервера void removeReplyHeader(const PIString & name) { reply_headers.remove(name); } + + //! ~english Clears all custom response headers + //! ~russian Очищает все пользовательские заголовки ответов void clearReplyHeaders() { reply_headers.clear(); } private: