From 36eb5e1cf36f851c177827ec22ab9190abc9acd1 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Tue, 8 May 2012 15:36:28 +0200 Subject: [PATCH] More documentation updates. --- base/tcpclient.cpp | 79 ++++++++++++++++++++++++++++++++++++++ base/tcpserver.cpp | 45 ++++++++++++++++++++++ base/tlsclient.cpp | 94 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 218 insertions(+) diff --git a/base/tcpclient.cpp b/base/tcpclient.cpp index f5f35df9c..9234772f0 100644 --- a/base/tcpclient.cpp +++ b/base/tcpclient.cpp @@ -2,6 +2,13 @@ using namespace icinga; +/** + * TCPClient + * + * Constructor for the TCPClient class. + * + * @param role The role of the TCP client socket. + */ TCPClient::TCPClient(TCPClientRole role) { m_Role = role; @@ -10,11 +17,23 @@ TCPClient::TCPClient(TCPClientRole role) m_RecvQueue = make_shared(); } +/** + * GetRole + * + * Retrieves the role of the socket. + * + * @returns The role. + */ TCPClientRole TCPClient::GetRole(void) const { return m_Role; } +/** + * Start + * + * Registers the socket and starts processing events for it. + */ void TCPClient::Start(void) { TCPSocket::Start(); @@ -23,6 +42,14 @@ void TCPClient::Start(void) OnWritable += bind_weak(&TCPClient::WritableEventHandler, shared_from_this()); } +/** + * Connect + * + * Creates a socket and connects to the specified node and service. + * + * @param node The node. + * @param service The service. + */ void TCPClient::Connect(const string& node, const string& service) { m_Role = RoleOutbound; @@ -71,16 +98,38 @@ void TCPClient::Connect(const string& node, const string& service) freeaddrinfo(result); } +/** + * GetSendQueue + * + * Retrieves the send queue for the socket. + * + * @returns The send queue. + */ FIFO::Ptr TCPClient::GetSendQueue(void) { return m_SendQueue; } +/** + * GetRecvQueue + * + * Retrieves the recv queue for the socket. + * + * @returns The recv queue. + */ FIFO::Ptr TCPClient::GetRecvQueue(void) { return m_RecvQueue; } +/** + * ReadableEventHandler + * + * Processes data that is available for this socket. + * + * @param ea Event arguments. + * @returns 0 + */ int TCPClient::ReadableEventHandler(const EventArgs& ea) { int rc; @@ -110,6 +159,14 @@ int TCPClient::ReadableEventHandler(const EventArgs& ea) return 0; } +/** + * WritableEventHandler + * + * Processes data that can be written for this socket. + * + * @param ea Event arguments. + * @returns 0 + */ int TCPClient::WritableEventHandler(const EventArgs& ea) { int rc; @@ -126,16 +183,38 @@ int TCPClient::WritableEventHandler(const EventArgs& ea) return 0; } +/** + * WantsToRead + * + * Checks whether data should be read for this socket. + * + * @returns true + */ bool TCPClient::WantsToRead(void) const { return true; } +/** + * WantsToWrite + * + * Checks whether data should be written for this socket. + * + * @returns true if data should be written, false otherwise. + */ bool TCPClient::WantsToWrite(void) const { return (m_SendQueue->GetSize() > 0); } +/** + * TCPClientFactory + * + * Default factory function for TCP clients. + * + * @param role The role of the new client. + * @returns The new client. + */ TCPClient::Ptr icinga::TCPClientFactory(TCPClientRole role) { return make_shared(role); diff --git a/base/tcpserver.cpp b/base/tcpserver.cpp index 332374eb9..86899c8bb 100644 --- a/base/tcpserver.cpp +++ b/base/tcpserver.cpp @@ -2,21 +2,45 @@ using namespace icinga; +/** + * TCPServer + * + * Constructor for the TCPServer class. + */ TCPServer::TCPServer(void) { m_ClientFactory = bind(&TCPClientFactory, RoleInbound); } +/** + * SetClientFactory + * + * Sets the client factory. + * + * @param clientFactory The client factory function. + */ void TCPServer::SetClientFactory(function clientFactory) { m_ClientFactory = clientFactory; } +/** + * GetFactoryFunction + * + * Retrieves the client factory. + * + * @returns The client factory function. + */ function TCPServer::GetFactoryFunction(void) const { return m_ClientFactory; } +/** + * Start + * + * Registers the TCP server and starts processing events for it. + */ void TCPServer::Start(void) { TCPSocket::Start(); @@ -24,6 +48,11 @@ void TCPServer::Start(void) OnReadable += bind_weak(&TCPServer::ReadableEventHandler, shared_from_this()); } +/** + * Listen + * + * Starts listening for incoming client connections. + */ void TCPServer::Listen(void) { int rc = listen(GetFD(), SOMAXCONN); @@ -34,6 +63,15 @@ void TCPServer::Listen(void) } } +/** + * ReadableEventHandler + * + * Accepts a new client and creates a new client object for it + * using the client factory function. + * + * @param ea Event arguments. + * @returns 0 + */ int TCPServer::ReadableEventHandler(const EventArgs& ea) { int fd; @@ -57,6 +95,13 @@ int TCPServer::ReadableEventHandler(const EventArgs& ea) return 0; } +/** + * WantsToRead + * + * Checks whether the TCP server wants to read (i.e. accept new clients). + * + * @returns true + */ bool TCPServer::WantsToRead(void) const { return true; diff --git a/base/tlsclient.cpp b/base/tlsclient.cpp index 726922e18..4f3fdd01a 100644 --- a/base/tlsclient.cpp +++ b/base/tlsclient.cpp @@ -5,6 +5,14 @@ using namespace icinga; int I2_EXPORT TLSClient::m_SSLIndex; bool I2_EXPORT TLSClient::m_SSLIndexInitialized = false; +/** + * TLSClient + * + * Constructor for the TLSClient class. + * + * @param role The role of the client. + * @param sslContext The SSL context for the client. + */ TLSClient::TLSClient(TCPClientRole role, shared_ptr sslContext) : TCPClient(role) { m_SSLContext = sslContext; @@ -12,21 +20,47 @@ TLSClient::TLSClient(TCPClientRole role, shared_ptr sslContext) : TCPCl m_BlockWrite = false; } +/** + * NullCertificateDeleter + * + * Takes a certificate as an argument. Does nothing. + * + * @param certificate An X509 certificate. + */ void TLSClient::NullCertificateDeleter(X509 *certificate) { /* Nothing to do here. */ } +/** + * GetClientCertificate + * + * Retrieves the X509 certficate for this client. + * + * @returns The X509 certificate. + */ shared_ptr TLSClient::GetClientCertificate(void) const { return shared_ptr(SSL_get_certificate(m_SSL.get()), &TLSClient::NullCertificateDeleter); } +/** + * GetPeerCertificate + * + * Retrieves the X509 certficate for the peer. + * + * @returns The X509 certificate. + */ shared_ptr TLSClient::GetPeerCertificate(void) const { return shared_ptr(SSL_get_peer_certificate(m_SSL.get()), X509_free); } +/** + * Start + * + * Registers the TLS socket and starts processing events for it. + */ void TLSClient::Start(void) { TCPClient::Start(); @@ -60,6 +94,14 @@ void TLSClient::Start(void) SSL_do_handshake(m_SSL.get()); } +/** + * ReadableEventHandler + * + * Processes data that is available for this socket. + * + * @param ea Event arguments. + * @returns 0 + */ int TLSClient::ReadableEventHandler(const EventArgs& ea) { int rc; @@ -98,6 +140,14 @@ int TLSClient::ReadableEventHandler(const EventArgs& ea) return 0; } +/** + * WritableEventHandler + * + * Processes data that can be written for this socket. + * + * @param ea Event arguments. + * @returns 0 + */ int TLSClient::WritableEventHandler(const EventArgs& ea) { int rc; @@ -130,6 +180,13 @@ int TLSClient::WritableEventHandler(const EventArgs& ea) return 0; } +/** + * WantsToRead + * + * Checks whether data should be read for this socket. + * + * @returns true if data should be read, false otherwise. + */ bool TLSClient::WantsToRead(void) const { if (SSL_want_read(m_SSL.get())) @@ -141,6 +198,13 @@ bool TLSClient::WantsToRead(void) const return TCPClient::WantsToRead(); } +/** + * WantsToWrite + * + * Checks whether data should be written for this socket. + * + * @returns true if data should be written, false otherwise. + */ bool TLSClient::WantsToWrite(void) const { if (SSL_want_write(m_SSL.get())) @@ -152,6 +216,13 @@ bool TLSClient::WantsToWrite(void) const return TCPClient::WantsToWrite(); } +/** + * CloseInternal + * + * Closes the socket. + * + * @param from_dtor Whether this method was invoked from the destructor. + */ void TLSClient::CloseInternal(bool from_dtor) { SSL_shutdown(m_SSL.get()); @@ -159,6 +230,11 @@ void TLSClient::CloseInternal(bool from_dtor) TCPClient::CloseInternal(from_dtor); } +/** + * HandleSSLError + * + * Handles an OpenSSL error. + */ void TLSClient::HandleSSLError(void) { int code = ERR_get_error(); @@ -174,11 +250,29 @@ void TLSClient::HandleSSLError(void) return; } +/** + * TLSClientFactory + * + * Factory function for the TLSClient class. + * + * @param role The role of the TLS socket. + * @param sslContext The SSL context for the socket. + * @returns A new TLS socket. + */ TCPClient::Ptr icinga::TLSClientFactory(TCPClientRole role, shared_ptr sslContext) { return make_shared(role, sslContext); } +/** + * SSLVerifyCertificate + * + * Callback function that verifies SSL certificates. + * + * @param ok Whether pre-checks for the SSL certificates were successful. + * @param x509Context X509 context for the certificate. + * @returns 1 if the verification was successful, 0 otherwise. + */ int TLSClient::SSLVerifyCertificate(int ok, X509_STORE_CTX *x509Context) { SSL *ssl = (SSL *)X509_STORE_CTX_get_ex_data(x509Context, SSL_get_ex_data_X509_STORE_CTX_idx()); -- 2.40.0