361 lines
13 KiB
C++
361 lines
13 KiB
C++
|
|
// Network.h
|
|
|
|
// Declares the classes used for the Network API
|
|
|
|
|
|
|
|
|
|
|
|
#pragma once
|
|
|
|
|
|
|
|
|
|
|
|
// fwd:
|
|
class cTCPLink;
|
|
typedef std::shared_ptr<cTCPLink> cTCPLinkPtr;
|
|
typedef std::vector<cTCPLinkPtr> cTCPLinkPtrs;
|
|
class cServerHandle;
|
|
typedef std::shared_ptr<cServerHandle> cServerHandlePtr;
|
|
typedef std::vector<cServerHandlePtr> cServerHandlePtrs;
|
|
class cCryptoKey;
|
|
typedef std::shared_ptr<cCryptoKey> cCryptoKeyPtr;
|
|
class cX509Cert;
|
|
typedef std::shared_ptr<cX509Cert> cX509CertPtr;
|
|
|
|
|
|
|
|
|
|
|
|
/** Interface that provides the methods available on a single TCP connection. */
|
|
class cTCPLink
|
|
{
|
|
friend class cNetwork;
|
|
|
|
public:
|
|
class cCallbacks
|
|
{
|
|
public:
|
|
// Force a virtual destructor for all descendants:
|
|
virtual ~cCallbacks() {}
|
|
|
|
/** Called when the cTCPLink for the connection is created.
|
|
The callback may store the cTCPLink instance for later use, but it should remove it in OnError(), OnRemoteClosed() or right after Close(). */
|
|
virtual void OnLinkCreated(cTCPLinkPtr a_Link) = 0;
|
|
|
|
/** Called when there's data incoming from the remote peer. */
|
|
virtual void OnReceivedData(const char * a_Data, size_t a_Length) = 0;
|
|
|
|
/** Called when the remote end closes the connection.
|
|
The link is still available for connection information query (IP / port).
|
|
Sending data on the link is not an error, but the data won't be delivered. */
|
|
virtual void OnRemoteClosed(void) = 0;
|
|
|
|
/** Called when the TLS handshake has been completed and communication can continue regularly.
|
|
Has an empty default implementation, so that link callback descendants don't need to specify TLS handlers when they don't use TLS at all. */
|
|
virtual void OnTlsHandshakeCompleted(void) {}
|
|
|
|
/** Called when an error is detected on the connection. */
|
|
virtual void OnError(int a_ErrorCode, const AString & a_ErrorMsg) = 0;
|
|
};
|
|
typedef std::shared_ptr<cCallbacks> cCallbacksPtr;
|
|
|
|
|
|
// Force a virtual destructor for all descendants:
|
|
virtual ~cTCPLink() {}
|
|
|
|
/** Queues the specified data for sending to the remote peer.
|
|
Returns true on success, false on failure. Note that this success or failure only reports the queue status, not the actual data delivery. */
|
|
virtual bool Send(const void * a_Data, size_t a_Length) = 0;
|
|
|
|
/** Queues the specified data for sending to the remote peer.
|
|
Returns true on success, false on failure. Note that this success or failure only reports the queue status, not the actual data delivery. */
|
|
bool Send(const AString & a_Data)
|
|
{
|
|
return Send(a_Data.data(), a_Data.size());
|
|
}
|
|
|
|
/** Returns the IP address of the local endpoint of the connection. */
|
|
virtual AString GetLocalIP(void) const = 0;
|
|
|
|
/** Returns the port used by the local endpoint of the connection. */
|
|
virtual UInt16 GetLocalPort(void) const = 0;
|
|
|
|
/** Returns the IP address of the remote endpoint of the connection. */
|
|
virtual AString GetRemoteIP(void) const = 0;
|
|
|
|
/** Returns the port used by the remote endpoint of the connection. */
|
|
virtual UInt16 GetRemotePort(void) const = 0;
|
|
|
|
/** Closes the link gracefully.
|
|
The link will send any queued outgoing data, then it will send the FIN packet.
|
|
The link will still receive incoming data from remote until the remote closes the connection. */
|
|
virtual void Shutdown(void) = 0;
|
|
|
|
/** Drops the connection without any more processing.
|
|
Sends the RST packet, queued outgoing and incoming data is lost. */
|
|
virtual void Close(void) = 0;
|
|
|
|
/** Starts a TLS handshake as a client connection.
|
|
If a client certificate should be used for the connection, set the certificate into a_OwnCertData and
|
|
its corresponding private key to a_OwnPrivKeyData. If both are empty, no client cert is presented.
|
|
a_OwnPrivKeyPassword is the password to be used for decoding PrivKey, empty if not passworded.
|
|
Returns empty string on success, non-empty error description on failure. */
|
|
virtual AString StartTLSClient(
|
|
cX509CertPtr a_OwnCert,
|
|
cCryptoKeyPtr a_OwnPrivKey
|
|
) = 0;
|
|
|
|
/** Starts a TLS handshake as a server connection.
|
|
Set the server certificate into a_CertData and its corresponding private key to a_OwnPrivKeyData.
|
|
a_OwnPrivKeyPassword is the password to be used for decoding PrivKey, empty if not passworded.
|
|
a_StartTLSData is any data that should be pushed into the TLS before reading more data from the remote.
|
|
This is used mainly for protocols starting TLS in the middle of communication, when the TLS start command
|
|
can be received together with the TLS Client Hello message in one OnReceivedData() call, to re-queue the
|
|
Client Hello message into the TLS handshake buffer.
|
|
Returns empty string on success, non-empty error description on failure. */
|
|
virtual AString StartTLSServer(
|
|
cX509CertPtr a_OwnCert,
|
|
cCryptoKeyPtr a_OwnPrivKey,
|
|
const AString & a_StartTLSData
|
|
) = 0;
|
|
|
|
/** Returns the callbacks that are used. */
|
|
cCallbacksPtr GetCallbacks(void) const { return m_Callbacks; }
|
|
|
|
protected:
|
|
/** Callbacks to be used for the various situations. */
|
|
cCallbacksPtr m_Callbacks;
|
|
|
|
|
|
/** Creates a new link, with the specified callbacks. */
|
|
cTCPLink(cCallbacksPtr a_Callbacks):
|
|
m_Callbacks(a_Callbacks)
|
|
{
|
|
}
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/** Interface that provides the methods available on a listening server socket. */
|
|
class cServerHandle
|
|
{
|
|
friend class cNetwork;
|
|
public:
|
|
|
|
// Force a virtual destructor for all descendants:
|
|
virtual ~cServerHandle() {}
|
|
|
|
/** Stops the server, no more incoming connections will be accepted.
|
|
All current connections will be shut down (cTCPLink::Shutdown()). */
|
|
virtual void Close(void) = 0;
|
|
|
|
/** Returns true if the server has been started correctly and is currently listening for incoming connections. */
|
|
virtual bool IsListening(void) const = 0;
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
/** Interface that provides methods available on UDP communication endpoints. */
|
|
class cUDPEndpoint
|
|
{
|
|
public:
|
|
/** Interface for the callbacks for events that can happen on the endpoint. */
|
|
class cCallbacks
|
|
{
|
|
public:
|
|
// Force a virtual destructor in all descendants:
|
|
virtual ~cCallbacks() {}
|
|
|
|
/** Called when an error occurs on the endpoint. */
|
|
virtual void OnError(int a_ErrorCode, const AString & a_ErrorMsg) = 0;
|
|
|
|
/** Called when there is an incoming datagram from a remote host. */
|
|
virtual void OnReceivedData(const char * a_Data, size_t a_Size, const AString & a_RemoteHost, UInt16 a_RemotePort) = 0;
|
|
};
|
|
|
|
|
|
// Force a virtual destructor for all descendants:
|
|
virtual ~cUDPEndpoint() {}
|
|
|
|
/** Closes the underlying socket.
|
|
Note that there still might be callbacks in-flight after this method returns. */
|
|
virtual void Close(void) = 0;
|
|
|
|
/** Returns true if the endpoint is open. */
|
|
virtual bool IsOpen(void) const = 0;
|
|
|
|
/** Returns the local port to which the underlying socket is bound. */
|
|
virtual UInt16 GetPort(void) const = 0;
|
|
|
|
/** Sends the specified payload in a single UDP datagram to the specified host + port combination.
|
|
Note that in order to send to a broadcast address, you need to call EnableBroadcasts() first. */
|
|
virtual bool Send(const AString & a_Payload, const AString & a_Host, UInt16 a_Port) = 0;
|
|
|
|
/** Marks the socket as capable of sending broadcast, using whatever OS API is needed.
|
|
Without this call, sending to a broadcast address using Send() may fail. */
|
|
virtual void EnableBroadcasts(void) = 0;
|
|
|
|
protected:
|
|
/** The callbacks used for various events on the endpoint. */
|
|
cCallbacks & m_Callbacks;
|
|
|
|
|
|
/** Creates a new instance of an endpoint, with the specified callbacks. */
|
|
cUDPEndpoint(cCallbacks & a_Callbacks):
|
|
m_Callbacks(a_Callbacks)
|
|
{
|
|
}
|
|
};
|
|
|
|
typedef std::shared_ptr<cUDPEndpoint> cUDPEndpointPtr;
|
|
|
|
|
|
|
|
|
|
|
|
class cNetwork
|
|
{
|
|
public:
|
|
/** Callbacks used for connecting to other servers as a client. */
|
|
class cConnectCallbacks
|
|
{
|
|
public:
|
|
// Force a virtual destructor for all descendants:
|
|
virtual ~cConnectCallbacks() {}
|
|
|
|
/** Called when the Connect call succeeds.
|
|
Provides the newly created link that can be used for communication. */
|
|
virtual void OnConnected(cTCPLink & a_Link) = 0;
|
|
|
|
/** Called when the Connect call fails. */
|
|
virtual void OnError(int a_ErrorCode, const AString & a_ErrorMsg) = 0;
|
|
};
|
|
typedef std::shared_ptr<cConnectCallbacks> cConnectCallbacksPtr;
|
|
|
|
|
|
/** Callbacks used when listening for incoming connections as a server. */
|
|
class cListenCallbacks
|
|
{
|
|
public:
|
|
// Force a virtual destructor for all descendants:
|
|
virtual ~cListenCallbacks() {}
|
|
|
|
/** Called when the TCP server created with Listen() receives a new incoming connection.
|
|
Returns the link callbacks that the server should use for the newly created link.
|
|
If a nullptr is returned, the connection is dropped immediately;
|
|
otherwise a new cTCPLink instance is created and OnAccepted() is called. */
|
|
virtual cTCPLink::cCallbacksPtr OnIncomingConnection(const AString & a_RemoteIPAddress, UInt16 a_RemotePort) = 0;
|
|
|
|
/** Called when the TCP server created with Listen() creates a new link for an incoming connection.
|
|
Provides the newly created Link that can be used for communication.
|
|
Called right after a successful OnIncomingConnection(). */
|
|
virtual void OnAccepted(cTCPLink & a_Link) = 0;
|
|
|
|
/** Called when the socket fails to listen on the specified port. */
|
|
virtual void OnError(int a_ErrorCode, const AString & a_ErrorMsg) = 0;
|
|
};
|
|
typedef std::shared_ptr<cListenCallbacks> cListenCallbacksPtr;
|
|
|
|
|
|
/** Callbacks used when resolving names to IPs. */
|
|
class cResolveNameCallbacks
|
|
{
|
|
public:
|
|
// Force a virtual destructor for all descendants:
|
|
virtual ~cResolveNameCallbacks() {}
|
|
|
|
/** Called when the hostname is successfully resolved into an IP address.
|
|
May be called multiple times if a name resolves to multiple addresses.
|
|
a_IP may be either an IPv4 or an IPv6 address with their proper formatting.
|
|
Each call to OnNameResolved() is preceded by a call to either OnNameResolvedV4() or OnNameResolvedV6(). */
|
|
virtual void OnNameResolved(const AString & a_Name, const AString & a_IP) = 0;
|
|
|
|
/** Called when the hostname is successfully resolved into an IPv4 address.
|
|
May be called multiple times if a name resolves to multiple addresses.
|
|
Each call to OnNameResolvedV4 is followed by OnNameResolved with the IP address serialized to a string.
|
|
If this callback returns false, the OnNameResolved() call is skipped for this address. */
|
|
virtual bool OnNameResolvedV4(const AString & a_Name, const sockaddr_in * a_IP) { return true; }
|
|
|
|
/** Called when the hostname is successfully resolved into an IPv6 address.
|
|
May be called multiple times if a name resolves to multiple addresses.
|
|
Each call to OnNameResolvedV4 is followed by OnNameResolved with the IP address serialized to a string.
|
|
If this callback returns false, the OnNameResolved() call is skipped for this address. */
|
|
virtual bool OnNameResolvedV6(const AString & a_Name, const sockaddr_in6 * a_IP) { return true; }
|
|
|
|
/** Called when an error is encountered while resolving.
|
|
If an error is reported, the OnFinished() callback is not called. */
|
|
virtual void OnError(int a_ErrorCode, const AString & a_ErrorMsg) = 0;
|
|
|
|
/** Called when all the addresses resolved have been reported via the OnNameResolved() callback.
|
|
Only called if there was no error reported. */
|
|
virtual void OnFinished(void) = 0;
|
|
};
|
|
typedef std::shared_ptr<cResolveNameCallbacks> cResolveNameCallbacksPtr;
|
|
|
|
|
|
/** Queues a TCP connection to be made to the specified host.
|
|
Calls one the connection callbacks (success, error) when the connection is successfully established, or upon failure.
|
|
The a_LinkCallbacks is passed to the newly created cTCPLink.
|
|
Returns true if queueing was successful, false on failure to queue.
|
|
Note that the return value doesn't report the success of the actual connection; the connection is established asynchronously in the background.
|
|
Implemented in TCPLinkImpl.cpp. */
|
|
static bool Connect(
|
|
const AString & a_Host,
|
|
UInt16 a_Port,
|
|
cConnectCallbacksPtr a_ConnectCallbacks,
|
|
cTCPLink::cCallbacksPtr a_LinkCallbacks
|
|
);
|
|
|
|
|
|
/** Opens up the specified port for incoming connections.
|
|
Calls an OnAccepted callback for each incoming connection.
|
|
A cTCPLink with the specified link callbacks is created for each connection.
|
|
Returns a cServerHandle that can be used to query the operation status and close the server.
|
|
Implemented in ServerHandleImpl.cpp. */
|
|
static cServerHandlePtr Listen(
|
|
UInt16 a_Port,
|
|
cListenCallbacksPtr a_ListenCallbacks
|
|
);
|
|
|
|
|
|
/** Queues a DNS query to resolve the specified hostname to IP address.
|
|
Calls one of the callbacks when the resolving succeeds, or when it fails.
|
|
Returns true if queueing was successful, false if not.
|
|
Note that the return value doesn't report the success of the actual lookup; the lookup happens asynchronously on the background.
|
|
Implemented in HostnameLookup.cpp. */
|
|
static bool HostnameToIP(
|
|
const AString & a_Hostname,
|
|
cResolveNameCallbacksPtr a_Callbacks
|
|
);
|
|
|
|
|
|
/** Queues a DNS query to resolve the specified IP address to a hostname.
|
|
Calls one of the callbacks when the resolving succeeds, or when it fails.
|
|
Returns true if queueing was successful, false if not.
|
|
Note that the return value doesn't report the success of the actual lookup; the lookup happens asynchronously on the background.
|
|
Implemented in IPLookup.cpp. */
|
|
static bool IPToHostName(
|
|
const AString & a_IP,
|
|
cResolveNameCallbacksPtr a_Callbacks
|
|
);
|
|
|
|
/** Opens up an UDP endpoint for sending and receiving UDP datagrams on the specified port.
|
|
If a_Port is 0, the OS is free to assign any port number it likes to the endpoint.
|
|
Returns the endpoint object that can be interacted with. */
|
|
static cUDPEndpointPtr CreateUDPEndpoint(UInt16 a_Port, cUDPEndpoint::cCallbacks & a_Callbacks);
|
|
|
|
/** Returns all local IP addresses for network interfaces currently available. */
|
|
static AStringVector EnumLocalIPAddresses(void);
|
|
};
|
|
|
|
|
|
|
|
|