/** * @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 &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)