Files

671 lines
25 KiB
C++

/**
* @file include/ActivMiddleware/ActivFramework/RouterServiceApi.h
*
* @brief Header file for router api.
*/
#if (!defined ACTIV_FRAMEWORK_ROUTER_SERVICE_API_H)
#define ACTIV_FRAMEWORK_ROUTER_SERVICE_API_H
#include "ActivMiddleware/ActivFramework/External.h"
#include "ActivMiddleware/ActivBase/ISerializableMessage.h"
#include "ActivMiddleware/ActivBase/FieldTypes/Boolean.h"
#include "ActivMiddleware/ActivBase/FieldTypes/UInt.h"
//! Activ namespace.
namespace Activ
{
class Address;
class Component;
class HeapMessage;
class IHeap;
class IpAddress;
// ---------------------------------------------------------------------------------------------------------------------------------
/**
* @brief Api to the agent's router service.
*/
class RouterServiceApi
{
public:
/**
* @brief Get the complete set of RouterService endpoints available.
*
* @param component component to send message from.
* @param endPointIdSet
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_FAILURE
*/
ACTIV_FRAMEWORK_API static StatusCode GetEndPointIdSet(const Component &component, EndPointIdSet &endPointIdSet);
/**
* @brief Tcp related apis.
*/
class Tcp
{
public:
/**
* @brief List of available tunnelling types.
*/
#define ACTIV_ROUTER_SERVICE_API_TUNNEL_TYPE_LIST(d) \
d(TUNNEL_TYPE_NONE, "none") \
d(TUNNEL_TYPE_AUTO, "auto") \
d(TUNNEL_TYPE_PROXY_CONNECT, "CONNECT") \
d(TUNNEL_TYPE_HTTP_T2, "HTTPt2") \
d(TUNNEL_TYPE_WEBSOCKET, "WebSocket")
/**
* @brief Enumeration of available tunnelling types.
*/
enum TunnelType
{
ACTIV_ROUTER_SERVICE_API_TUNNEL_TYPE_LIST(ACTIV_DECLARE_ELEMENT_1_WITH_COMMA)
TUNNEL_TYPE_COUNT,
TUNNEL_TYPE_UNKNOWN = -1
};
/**
* @brief Socket stats.
*/
class SocketStats
{
public:
/**
* @brief Default constructor.
*
* Zeros all members.
*/
ACTIV_FRAMEWORK_API SocketStats();
static const MessageType MESSAGE_TYPE = ROUTER_MESSAGE_USER_NOTIFY_SOCKET_STATS;
size_t m_txQueueBytes; ///< Current size of to transmit queue in bytes.
size_t m_txQueueMessages; ///< Current size of to transmit queue in number of messages.
size_t m_txQueueHighBytes; ///< High size of to transmit queue in bytes.
size_t m_txQueueHighMessages; ///< High size of to transmit queue in number of messages.
size_t m_inTxQueueBytes; ///< Current size of currently transmitting queue in bytes.
size_t m_inTxQueueMessages; ///< Current size of currently transmitting queue in number of messages.
size_t m_inTxQueueHighBytes; ///< High size of currently transmitting queue in bytes.
size_t m_inTxQueueHighMessages; ///< High size of currently transmitting queue in number of messages.
uint64_t m_rxBytes; ///< Total rx bytes.
uint64_t m_txBytes; ///< Total tx bytes.
size_t m_mutexContentionCount; ///< Approx. contentions on the socket's mutex.
// OS-level stats; may not be defined.
UInt m_txRtt;
UInt m_txCongestionWindowSize;
UInt m_totalRetransmissions;
UInt m_reorders;
Boolean m_isNagleEnabled;
UInt m_txCompressionPercent; ///< If compressing, compression ratio as % (compressed-bytes / source-bytes).
uint64_t m_millisecondTimeStamp; ///< The time stamp when these stats were created, referenced to the system up time.
};
// CLIENT SIDE
/**
* @brief Create a circuit and initiate a synchronous connect.
*
* @param component component to initiate the connection from.
* @param url of the form protocol://host:port/location?unique.
* @param connectResponse reference to a HeapMessage object to receive connect response. Source address of this
* message for a successful connect will be the circuit address.
* @param pHeap the heap to use for received messages. Default is this component's heap.
* @param timeout How long to wait for the circuit to establish, in ms.
* @param pUserData optional userdata.
* @param pLocalIpAddress optional pointer to receive the local IP address of the connection.
*
* @retval STATUS_CODE_SUCCESS circuit is up.
* @retval STATUS_CODE_TIMEOUT circuit did not establish in the timeout period.
* @retval STATUS_CODE_HOST_DEVICE_NOT_FOUND unknown destination machine.
* @retval STATUS_CODE_INVALID_ENDPOINT_COMPONENT unknown endpoint-component on target system.
* @retval STATUS_CODE_FAILURE ...
*/
ACTIV_FRAMEWORK_API static StatusCode Connect(const Component &component, const String &url,
HeapMessage &connectResponse, IHeap * const pHeap, const TimeoutPeriod timeout,
const ISerializableMessage * const pUserData = ACTIV_NULLPTR, IpAddress *pLocalIpAddress = ACTIV_NULLPTR);
/**
* @brief Create a circuit and initiate an asynchronous connect.
*
* @param component component to initiate the connection from.
* @param url of the form protocol://host:port/location?unique.
* @param circuitAddress reference to an Address object to receive the address of the circuit.
* @param pHeap the heap to use for received messages. Default is this component's heap.
* @param pUserData optional userdata.
*
* @retval STATUS_CODE_SUCCESS OnConnect() will be invoked when the circuit is up.
* @retval STATUS_CODE_HOST_DEVICE_NOT_FOUND unknown destination machine.
* @retval STATUS_CODE_INVALID_ENDPOINT_COMPONENT unknown endpoint-component on target system.
* @retval STATUS_CODE_FAILURE ...
*/
ACTIV_FRAMEWORK_API static StatusCode Connect(const Component &component, const String &url, Address &circuitAddress,
IHeap * const pHeap = ACTIV_NULLPTR, const ISerializableMessage * const pUserData = ACTIV_NULLPTR);
// SERVER SIDE
/**
* @brief Allow an address to be accessible through a server.
*
* @param component component to allow access to.
* @param url of the form protocol://host:port?unique,accepts=n
* @param serverAddress reference to an Address object to receive the address of the server.
* @param accessUrlList to receive the urls that a client can use to access the server.
* @param pHeap the heap to use for received messages. Default is this component's heap.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_SHAREABLE unique not specified for an non-multiplexable protocol.
* @retval STATUS_CODE_INVALID_PROTOCOL server already exists on the given address and port with a different protocol.
* @retval STATUS_CODE_SHUTTING_DOWN can't add new user as server is shutting down.
* @retval STATUS_CODE_ALREADY_LISTENING user already added.
* @retval STATUS_CODE_FAILURE
* @retval STATUS_CODE_TIMEOUT
*/
ACTIV_FRAMEWORK_API static StatusCode Listen(const Component &component, const String &url, Address &serverAddress,
std::vector<String> &accessUrlList, IHeap * const pHeap = 0);
/**
* @brief Allow an address to be accessible through a server.
*
* @param component component to allow access to.
* @param url of the form protocol://host:port?unique,accepts=n
* @param serverAddress reference to an Address object to receive the address of the server.
* @param pHeap the heap to use for received messages. Default is this component's heap.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_NOT_SHAREABLE unique not specified for an non-multiplexable protocol.
* @retval STATUS_CODE_INVALID_PROTOCOL server already exists on the given address and port with a different protocol.
* @retval STATUS_CODE_SHUTTING_DOWN can't add new user as server is shutting down.
* @retval STATUS_CODE_ALREADY_LISTENING user already added.
* @retval STATUS_CODE_FAILURE
* @retval STATUS_CODE_TIMEOUT
*/
ACTIV_FRAMEWORK_API static StatusCode Listen(const Component &component, const String &url, Address &serverAddress,
IHeap * const pHeap = 0);
/**
* @brief Remove access to an address through a server.
*
* @param component component to stop listening.
* @param serverAddress address of the server to remove access from.
* @param shouldBreakAccepted whether to break existing accepted connections as well as stop listening.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_FAILURE
*/
ACTIV_FRAMEWORK_API static StatusCode Stop(const Component &component, const Address &serverAddress,
const bool shouldBreakAccepted = false);
/**
* @brief Break all accepted connections by a server.
*
* @param component component to send message from.
* @param serverAddress address of the server to close the accepted connections of.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_FAILURE
*/
ACTIV_FRAMEWORK_API static StatusCode BreakAll(const Component &component, const Address &serverAddress);
/**
* @brief Get the set of RouterService endpoints that will be handling a server.
*
* @param component component to send message from.
* @param serverAddress address of the server.
* @param endPointIdSet
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_FAILURE
*/
ACTIV_FRAMEWORK_API static StatusCode GetEndPointIdSet(const Component &component, const Address &serverAddress,
EndPointIdSet &endPointIdSet);
// CLIENT AND SERVER SIDE
/**
* @brief Break a connection.
*
* @param component component to initiate the break from.
* @param connectionAddress the address of a circuit to break. If the connection is shared,
* all circuits over that connection will break.
*
* @retval STATUS_CODE_SUCCESS the connection has been broken.
* @retval STATUS_CODE_FAILURE
*/
ACTIV_FRAMEWORK_API static StatusCode Break(const Component &component, const Address &connectionAddress);
/**
* @brief Disconnect a circuit.
*
* @param component component to initiate the disconnect from.
* @param circuitAddress the address of the circuit to initiate a disconnect on.
* @param timeout if 0, initiate an asynchronous disconnect. Otherwise, how long to wait for the circuit to
* close, in ms.
*
* @retval STATUS_CODE_SUCCESS for an asynchronous disconnect, OnDisconnect() will be invoked when the circuit is down.
* @retval STATUS_CODE_SUCCESS for a synchronous disconnect, circuit is down.
* Note data from this circuit may still be queued up on the destination endpoint, it is up to the
* application to discard this data if required.
* @retval STATUS_CODE_TIMEOUT for a synchronous disconnect - circuit did not close in the timeout period.
* @retval STATUS_CODE_FAILURE ...
*/
ACTIV_FRAMEWORK_API static StatusCode Disconnect(const Component &component, const Address &circuitAddress,
const TimeoutPeriod timeout = 0);
/**
* @brief Get the local ip address of a connection or server.
*
* Currently the local address is not passed in an accept (server-side) or connect (client-side) notification. This
* method can be used to retrieve it.
*
* @param component component to send the message from.
* @param address the address of the circuit or server to get the local ip address of.
* @param ipAddress to receive the ip address.
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode GetLocalIpAddress(const Component &component, const Address &address,
IpAddress &ipAddress);
/**
* @brief Set heap for a connection.
*
* @param component component to send the message from.
* @param address the address of a circuit.
* @param pHeap heap to use for received data on this connection.
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetHeap(const Component &component, const Address &address,
const IHeap * const pHeap);
/**
* @brief Get maximum transmit queue size for a connection.
*
* @param component component to send the message from.
* @param address the address of a circuit.
* @param numberOfBytes to receive the max bytes allowed on tx queue before breaking connection (0 is no limit).
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode GetMaxTxQueueSize(const Component &component, const Address &address,
size_t &numberOfBytes);
/**
* @brief Set maximum transmit queue size for a connection.
*
* @param component component to send the message from.
* @param address the address of a circuit.
* @param numberOfBytes max bytes to allow on tx queue before breaking connection (0 is no limit).
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetMaxTxQueueSize(const Component &component, const Address &address,
const size_t numberOfBytes);
/**
* @brief Enable receipt of socket stats for a circuit.
*
* The component will receive a message of type RouterServiceApi::Tcp::SocketStats::MESSAGE_TYPE on a lazy basis.
* Use DeserializeSocketStats() to retrieve the socket stats for the connection.
*
* @param component component to send request from.
* @param circuitAddress the address of the circuit to get the underlying socket stats for.
*
* @return STATUS_CODE_SUCCESS or an error status code.
*/
ACTIV_FRAMEWORK_API static StatusCode EnableSocketStats(const Component &component, const Address &circuitAddress);
/**
* @brief Deserialize a socket stats message.
*
* @param heapMessage received message of type RouterServiceApi::Tcp::SocketStats::MESSAGE_TYPE
* @param socketStats reference to a SocketStats to receive the stats.
*
* @return STATUS_CODE_SUCCESS or an error status code.
*/
ACTIV_FRAMEWORK_API static StatusCode DeserializeSocketStats(const HeapMessage &heapMessage, SocketStats &socketStats);
/**
* @brief Clear high counts for a socket.
*
* @param component component to send request from.
* @param circuitAddress the address of the circuit to get the underlying socket stats for.
*/
ACTIV_FRAMEWORK_API static StatusCode ClearSocketStatsHighCounts(const Component &component, const Address &circuitAddress);
/**
* @brief Get the tunnelling type used for a connection.
*
* @param component component to send request from.
* @param circuitAddress
* @param tunnelType to receive the tunnel type used on the connection specified by @a circuitAddress.
*
* @return STATUS_CODE_SUCCESS or an error status code.
*/
ACTIV_FRAMEWORK_API static StatusCode GetTunnelType(const Component &component, const Address &circuitAddress,
TunnelType &tunnelType);
/**
* @brief Convert tunnelling type to a string.
*
* @param tunnelType
*
* @return String representation of @a tunnelType.
*/
ACTIV_FRAMEWORK_API static const String TunnelTypeToString(const TunnelType tunnelType);
/**
* @brief Convert tunnelling type to a string.
*
* @param str string representation of an tunnelling type (e.g. from TunnelTypeToString()).
*
* @return TUNNEL_TYPE_UNKNOWN if unable to convert the string.
*/
ACTIV_FRAMEWORK_API static TunnelType StringToTunnelType(const String &str);
}; // Tcp
/**
* @brief Udp related apis.
*/
class Udp
{
public:
/**
* @brief Create a socket and bind it to a local address.
*
* @param component component to send the message from.
* @param localAddress local address to bind to.
* @param localPort local port to bind to.
* @param maxRxSize maximum size of a datagram that can be received.
* @param socketAddress reference to an Address object to receive the address of the socket.
* @param pHeap the heap to use for received messages. Default is this component's heap.
*
* @retval STATUS_CODE_SUCCESS
* @retval STATUS_CODE_TIMEOUT
* @retval STATUS_CODE_FAILURE ...
*/
ACTIV_FRAMEWORK_API static StatusCode Create(const Component &component, const String &localAddress,
const uint16_t localPort, const uint16_t maxRxSize, Address &socketAddress, IHeap * const pHeap = 0);
/**
* @brief Initiate a read on a udp socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to connect.
* @param shouldPurgeRxBuffer purge the socket's rx buffer before initiating the async read?
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode Read(const Component &component, const Address &socketAddress,
const bool shouldPurgeRxBuffer = false);
/**
* @brief Connect a udp socket to a remote address (filter all traffic from other addresses).
*
* @param component component to send the message from.
* @param socketAddress address of the socket to connect.
* @param remoteAddressString the remote address to connect to in string form.
* @param remotePort the remote port to connect to (local endian).
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode Connect(const Component &component, const Address &socketAddress,
const String &remoteAddressString, const uint16_t remotePort);
/**
* @brief Disconnect a udp socket from a remote address (allow all traffic).
*
* @param component component to send the message from.
* @param socketAddress address of the socket to disconnect.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode Disconnect(const Component &component, const Address &socketAddress);
/**
* @brief Get the local ip address of the udp socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to get the local ip address for.
* @param ipAddress to receive the ip address.
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode GetLocalIpAddress(const Component &component, const Address &socketAddress,
IpAddress &ipAddress);
/**
* @brief Close a udp socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to shutdown.
* @param gracefully true to only close the socket once any outstanding tx has completed,
* false to force the socket closed immediately.
*
* @retval STATUS_CODE_SUCCESS the socket is fully closed.
* @retval STATUS_CODE_PENDING the socket is closing and OnSocketClose() will be called.
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode Close(const Component &component, const Address &socketAddress,
const bool gracefully = false);
/**
* @brief Join a multicast group.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to join the multicast group on.
* @param multicastGroupString an ipv4 or ipv6 multicast address string.
* @param interfaceAddressString an ipv4 or ipv6 interface address string.
* @param sourceAddressString an ipv4 or ipv6 source address string. If non-empty, a source specific multicast join is
* attempted.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode JoinMulticastGroup(const Component &component, const Address &socketAddress,
const String &multicastGroupString, const String &interfaceAddressString,
const String &sourceAddressString = String(""));
/**
* @brief Leave a multicast group.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to leave the multicast group.
* @param multicastGroupString an ipv4 or ipv6 multicast address string.
* @param interfaceAddressString an ipv4 or ipv6 interface address string.
* @param sourceAddressString an ipv4 or ipv6 source address string. If non-empty, a source specific multicast leave is
* attempted.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode LeaveMulticastGroup(const Component &component, const Address &socketAddress,
const String &multicastGroupString, const String &interfaceAddressString,
const String &sourceAddressString = String(""));
/**
* @brief Set multicast interface for transmission.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to set multicast interface on.
* @param interfaceAddressString an ipv4 or ipv6 address string.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetMulticastTxInterface(const Component &component, const Address &socketAddress,
const String &interfaceAddressString);
/**
* @brief Set TTL to be used for multicasting.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to set the ttl on.
* @param ttl the TTL.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetMulticastTtl(const Component &component, const Address &socketAddress,
const uint32_t ttl);
/**
* @brief Set TTL to be used for unicasting.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to set unicast ttl on.
* @param ttl the TTL.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetUnicastTtl(const Component &component, const Address &socketAddress,
const uint32_t ttl);
/**
* @brief Get the internal rx buffer size of a socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to get buffer size of.
* @param size to receive the buffer size.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode GetRxBufferSize(const Component &component, const Address &socketAddress,
uint32_t &size);
/**
* @brief Set the internal rx buffer size of a socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to set buffer size on.
* @param size the buffer size.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetRxBufferSize(const Component &component, const Address &socketAddress,
const uint32_t size);
/**
* @brief Get the internal tx buffer size of a socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to get buffer size of.
* @param size to receive the buffer size.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode GetTxBufferSize(const Component &component, const Address &socketAddress,
uint32_t &size);
/**
* @brief Set the internal tx buffer size of a socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to set buffer size on.
* @param size the buffer size.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetTxBufferSize(const Component &component, const Address &socketAddress,
const uint32_t size);
/**
* @brief Set the receive multicast loopback option of a socket.
*
* @param component component to send the message from.
* @param socketAddress address of the socket to set transmit buffer size on.
* @param enable true to enable receipt of multicast loopback data, else false.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetMulticastLoopback(const Component &component, const Address &socketAddress,
const bool enable);
/**
* @brief Set the type of service of a socket (IP_TOS socket option).
*
* @param component component to send the message from.
* @param socketAddress address of the socket.
* @param typeOfService IP_TOS value.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode SetTypeOfService(const Component &component, const Address &socketAddress,
const byte_t typeOfService);
/**
* @brief Get the underying socket handle.
*
* Currently only supports udp sockets created by the router.
*
* @param component component to send the message from.
* @param socketAddress the socket to get the handle of.
* @param socket reference to a SOCKET variable to receive the handle.
*
* @retval STATUS_CODE_SUCCESS
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode GetSocketHandle(const Component &component, const Address &socketAddress,
SOCKET &socket);
/**
* @brief Do a blocking send of some data to a specified ip address.
*
* @param socket socket handle obtained with GetSocketHandle().
* @param pData pointer to data to send.
* @param dataLength length of data to send.
* @param toAddress destination ip address.
* @param timeoutPeriod how long to wait for the event, in ms.
*
* @return STATUS_CODE_SUCCESS
* @return STATUS_CODE_TIMEOUT
* @return ...
*/
ACTIV_FRAMEWORK_API static StatusCode SendTo(const SOCKET socket, const void *pData, size_t dataLength,
const IpAddress &toAddress, const TimeoutPeriod timeoutPeriod = ACTIV_WAIT_INFINITE);
/**
* @brief Do a blocking send of some data.
*
* @param socket socket handle obtained with GetSocketHandle().
* @param pData pointer to data to send.
* @param dataLength length of data to send.
* @param timeoutPeriod how long to wait for the event, in ms.
*
* @return STATUS_CODE_SUCCESS
* @return STATUS_CODE_TIMEOUT
* @return ...
*/
ACTIV_FRAMEWORK_API static StatusCode Send(const SOCKET socket, const void *pData, size_t dataLength,
const TimeoutPeriod timeoutPeriod = ACTIV_WAIT_INFINITE);
/**
* @brief Post some data. This call does not block, the transmission is handled by the router service.
*
* @param component component to send the message from.
* @param socketAddress the socket to send the data on.
* @param heapMessage the message to send.
*
* @retval ...
*/
ACTIV_FRAMEWORK_API static StatusCode PostData(const Component &component, const Address &socketAddress,
HeapMessage &heapMessage);
}; // Udp
};
} // namespace Activ
#endif // (!defined ACTIV_FRAMEWORK_ROUTER_SERVICE_API_H)