783 lines
32 KiB
C++
783 lines
32 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"
|
|
#include "ActivMiddleware/ActivBase/Ip/IpAddress.h"
|
|
#include "ActivMiddleware/ActivFramework/Address.h"
|
|
|
|
//! Activ namespace.
|
|
namespace Activ
|
|
{
|
|
|
|
class Address;
|
|
class Component;
|
|
class HeapMessage;
|
|
class IHeap;
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
//! Api to the agent's router service.
|
|
namespace RouterServiceApi
|
|
{
|
|
|
|
/**
|
|
* @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 StatusCode GetEndPointIdSet(const Component &component, EndPointIdSet &endPointIdSet);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
//! Tcp related apis.
|
|
namespace Tcp
|
|
{
|
|
|
|
//! 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")
|
|
|
|
//! 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
|
|
};
|
|
|
|
//! Protocol type.
|
|
typedef uint8_t Protocol;
|
|
|
|
//! List of available tcp protocol types.
|
|
#define ACTIV_ROUTER_SERVICE_API_PROTOCOL_LIST(d) \
|
|
d(PROTOCOL_AMS, 0, "ams") \
|
|
d(PROTOCOL_BMS, 1, "bms") \
|
|
d(PROTOCOL_BASIC, 2, "basic") \
|
|
d(PROTOCOL_UNKNOWN, -1, "unknown")
|
|
|
|
#define ACTIV_DECLARE_CONSTANT(a, b, c) ACTIV_BOOST_CONSTEXPR_OR_CONST Protocol a = b;
|
|
ACTIV_ROUTER_SERVICE_API_PROTOCOL_LIST(ACTIV_DECLARE_CONSTANT)
|
|
#undef ACTIV_DECLARE_CONSTANT
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
//! Socket stats.
|
|
class SocketStats
|
|
{
|
|
public:
|
|
//! Default constructor.
|
|
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.
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
//! Connection info. Optionally provided during OnAccept and OnConnect callbacks.
|
|
struct ConnectionInfo
|
|
{
|
|
Protocol m_protocol;
|
|
IpAddress m_localIpAddress;
|
|
IpAddress m_remoteIpAddress;
|
|
TunnelType m_tunnelType;
|
|
size_t m_maxTxQueueSize;
|
|
Address m_remoteDestinationAddress;
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
// 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 pConnectionInfo optional pointer to receive the connection info.
|
|
*
|
|
* @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 StatusCode Connect(const Component &component, const String &url, HeapMessage &connectResponse,
|
|
IHeap * const pHeap, const TimeoutPeriod timeout, const ISerializableMessage * const pUserData = ACTIV_NULLPTR,
|
|
ConnectionInfo *pConnectionInfo = 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 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 StatusCode Listen(const Component &component, const String &url, Address &serverAddress,
|
|
std::vector<String> &accessUrlList, IHeap * const pHeap = ACTIV_NULLPTR);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @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 StatusCode Listen(const Component &component, const String &url, Address &serverAddress,
|
|
IHeap * const pHeap = ACTIV_NULLPTR);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @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 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 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 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 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 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 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 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 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 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 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 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 StatusCode ClearSocketStatsHighCounts(const Component &component, const Address &circuitAddress);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Convert tunnelling type to a string.
|
|
*
|
|
* @param tunnelType
|
|
*
|
|
* @return String representation of @a tunnelType.
|
|
*/
|
|
ACTIV_FRAMEWORK_API String TunnelTypeToString(const TunnelType tunnelType);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Convert string to tunnelling type.
|
|
*
|
|
* @param str string representation of a tunnelling type (e.g. from TunnelTypeToString()).
|
|
*
|
|
* @return TUNNEL_TYPE_UNKNOWN if unable to convert the string.
|
|
*/
|
|
ACTIV_FRAMEWORK_API TunnelType StringToTunnelType(const String &str);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Convert protocol to a string.
|
|
*
|
|
* @param protocol
|
|
*
|
|
* @return String representation of @a protocol.
|
|
*/
|
|
ACTIV_FRAMEWORK_API const char *ProtocolToString(const Protocol protocol);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Convert string to protocol.
|
|
*
|
|
* @param str string representation of a protocol (e.g. from ProtocolToString()).
|
|
*
|
|
* @return TUNNEL_TYPE_UNKNOWN if unable to convert the string.
|
|
*/
|
|
ACTIV_FRAMEWORK_API Protocol StringToProtocol(const String &str);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @brief Enable buffer tokens on a connection.
|
|
*
|
|
* The connection component will receive periodic messages about buffering on the connection:
|
|
* - ROUTER_MESSAGE_CONNECTION_TX_BYTES
|
|
* - ROUTER_MESSAGE_BUFFER_TOKEN
|
|
*
|
|
* See ActivFramework/RouterService/RouterCircuitMessages.h for further details.
|
|
*
|
|
* This option should only be enabled:
|
|
* - When the remote application also supports buffer tokens.
|
|
* - When the connection is not sharable, either by protocol used or by specifying 'unique' on the client url.
|
|
*
|
|
* @param component component to send request from.
|
|
* @param circuitAddress the address of the circuit to enable buffer tokens on.
|
|
*
|
|
* @return STATUS_CODE_SUCCESS or an error status code.
|
|
*/
|
|
ACTIV_FRAMEWORK_API StatusCode EnableBufferTokens(const Component &component, const Address &circuitAddress);
|
|
|
|
} // namespace Tcp
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
//! Udp related apis.
|
|
namespace Udp
|
|
{
|
|
|
|
/**
|
|
* @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 StatusCode Create(const Component &component, const String &localAddress, const uint16_t localPort,
|
|
const uint16_t maxRxSize, Address &socketAddress, IHeap * const pHeap = ACTIV_NULLPTR);
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* @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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 StatusCode PostData(const Component &component, const Address &socketAddress, HeapMessage &heapMessage);
|
|
|
|
} // namespace Udp
|
|
|
|
} // namespace RouterServiceApi
|
|
|
|
} // namespace Activ
|
|
|
|
#endif // (!defined ACTIV_FRAMEWORK_ROUTER_SERVICE_API_H)
|