/* * Copyright (c) 2009-2024 Real-Time Innovations, Inc. All rights reserved. * No duplications, whole or partial, manual or electronic, may be made * without express written permission. Any such copies, or revisions thereof, * must display this notice unaltered. * This code contains trade secrets of Real-Time Innovations, Inc. */ #ifndef rtitls_endpoint_h #define rtitls_endpoint_h #ifndef transport_interface_h #include "transport/transport_interface.h" #endif #if defined(RTI_LYNX) && !defined(RTI_LYNXOS_SE) && !defined(RTI_LYNX500) #include #endif #if defined(RTI_VXWORKS) #if (VXWORKS_MAJOR_VERSION==5) && (VXWORKS_MINOR_VERSION==4) #define socklen_t int #endif #endif #ifdef __cplusplus extern "C" { #endif /* ================================================================= */ /* Component: Transport ConnectionEndpoint plugin API */ /* ================================================================= */ /*i \file \ingroup NDDS_TransportEndpoint \brief Transport ConnectionEndpoint plugin interface, for use by TCP transport. */ /* {{{ Connection Endpoint Factory Property Base Class * ================================================================= */ /*i \ingroup NDDS_TransportEndpoint * \brief An enumeration value to use in the factory property base class * that tell the kind of property. * * It can be used eventually in other structures that required * extending a base class. */ enum NDDS_Transport_ConnectionEndpointKind { NDDS_TRANSPORT_CONNECTION_ENDPOINT_KIND_TCPv4, NDDS_TRANSPORT_CONNECTION_ENDPOINT_KIND_TLSv4, NDDS_TRANSPORT_CONNECTION_ENDPOINT_KIND_TCPv6, NDDS_TRANSPORT_CONNECTION_ENDPOINT_KIND_TLSv6 }; /*i \ingroup NDDS_TransportEndpoint @brief ConnectionEndpointFactory properties base class */ struct NDDS_Transport_ConnectionEndpointFactoryProperty { /* Here we need to put all common properties for all the specific * implementation of the factory property */ enum NDDS_Transport_ConnectionEndpointKind kind; }; /* }}} */ /* {{{ Connection Endpoint Class * ================================================================= */ /*i \defgroup NDDS_TransportConnectionEndpointClass NDDS_Transport_ConnectionEndpoint \ingroup NDDS_TransportEndpoint \brief Interface for connection endpoint abstraction. */ /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Interface representation for connection endpoint abstraction. */ struct NDDS_Transport_ConnectionEndpoint; struct NDDS_Transport_ConnectionEndpointFactory; /*i \ingroup NDDS_TransportConnectionEndpointClass \brief The status of a connection endpoint, as value reported by the getStatus or getConnectionStatus function of the connection endpoint */ typedef enum NDDS_Transport_ConnectionEndpointStatus { NDDS_TRANSPORT_ENDPOINT_OK, /* Connected, no errors */ NDDS_TRANSPORT_PRECONDITION_ERROR, /* Precondition check failed */ NDDS_TRANSPORT_ENDPOINT_WOULDBLOCK, /* Operation would block on a non-blocking socket */ NDDS_TRANSPORT_ENDPOINT_CONNRESET, /* Remote peer has closed or reset the connection */ NDDS_TRANSPORT_ENDPOINT_CONNINPROGRESS, /* Connection in progress */ NDDS_TRANSPORT_ENDPOINT_CONNREFUSED, /* Connection refused */ NDDS_TRANSPORT_ENDPOINT_HANDSHAKEINPROGRESS, /* Protocol handshake in progress */ NDDS_TRANSPORT_ENDPOINT_HANDSHAKEFAILED, /* Protocol handshake in progress */ NDDS_TRANSPORT_ENDPOINT_BAD /* Any other error */ } NDDS_Transport_ConnectionEndpointStatus; /*i * \ingroup NDDS_TransportConnectionEndpointClass * \brief Returns a string representation of the connection endpoint status */ extern const char * NDDS_Transport_ConnectionEndpointStatus_toString( enum NDDS_Transport_ConnectionEndpointStatus status); /*i \ingroup NDDS_TransportConnectionEndpointClass Default send option. */ #define NDDS_TRANSPORT_SEND_OPTION_DEFAULT (0x00000000) /*i \ingroup NDDS_TransportConnectionEndpointClass Forces to send plain unencrypted data. */ #define NDDS_TRANSPORT_SEND_OPTION_FORCE_NO_ENCRYPTION (0x00000001) /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Send to connection endpoint. @param buffer \b In. The raw bytes to be sent to the connection @param length \b In. The length of the specified buffer, in bytes @return On success, returns the number of characters sent. On error, -1 is returned, and error status is set appropriately. */ typedef RTI_INT32 (*NDDS_Transport_ConnectionEndpoint_Send_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me, const void *buffer, size_t length, int flags, RTI_INT32 optionMask); #if defined(RTI_WIN32) /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Asynchronous send to connection endpoint. @param buffer_in \b In. An array of buffers that contain the data to send. @param buffer_count_in \b In. The number of buffers provided. @param flags \b In. The flags to set in the asynchronous send. @param lpOverlapped \b In. An overlapped structure with the operation information. @return The errnum obtained from the asynchronous send. */ typedef RTI_INT32 (*NDDS_Transport_ConnectionEndpoint_AsyncSend_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me, const NDDS_Transport_Buffer_t buffer_in[], RTI_INT32 buffer_count_in, RTI_INT32 flags, OVERLAPPED * lpOverlapped); #endif /*i \ingroup NDDS_TransportConnectionEndpointClass Default receive option. */ #define NDDS_TRANSPORT_RECV_OPTION_DEFAULT (0x00000000) /*i \ingroup NDDS_TransportConnectionEndpointClass Forces to receive plain unencrypted data. */ #define NDDS_TRANSPORT_RECV_OPTION_FORCE_NO_ENCRYPTION (0x00000001) /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Receive from connection endpoint. @param buffer \b Out. The buffer to store raw bytes received from the connection @param length \b In. The maximum length of the specified buffer, in bytes @return On success, returns the number of characters received. On error, -1 is returned, and error status is set appropriately. */ typedef RTI_INT32 (*NDDS_Transport_ConnectionEndpoint_Receive_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me, void *buffer, size_t length, int flags, RTI_INT32 optionMask); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Close connection endpoint. @return Return TRUE if connection closed successfully; if FALSE, need to try again after a delay. */ typedef RTIBool (*NDDS_Transport_ConnectionEndpoint_Close_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Check connection endpoint status. @return Return error state. */ typedef NDDS_Transport_ConnectionEndpointStatus (*NDDS_Transport_ConnectionEndpoint_GetStatus_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Check connection endpoint need to write. @return Return TRUE if connection is waiting for a write. */ typedef RTIBool (*NDDS_Transport_ConnectionEndpoint_NeedsWrite_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Perform handshake on endpoint when no data is available to write. @return Return TRUE if handshake completed successfully; if FALSE, need to try again after a delay. */ typedef RTIBool (*NDDS_Transport_ConnectionEndpoint_DoHandshake_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Returns the low level socket handle */ typedef int (*NDDS_Transport_ConnectionEndpoint_GetSocket_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Sets a socket option for a connection endpoint. @param optType \b In. The option to set. @param optVal \b In. The value to set for the option. @return On success, returns RTI_TRUE. */ typedef RTIBool (*NDDS_Transport_ConnectionEndpoint_SetSocketOption_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me, RTIOsapiSocketOption optType, int optVal); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Checks whether the given endpoint is the same as this one. */ typedef RTIBool (*NDDS_Transport_ConnectionEndpoint_PeerEquals_Fcn)( struct NDDS_Transport_ConnectionEndpoint *me, struct NDDS_Transport_ConnectionEndpoint *other); /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Pure virtual class for the connection functionality. */ struct NDDS_Transport_ConnectionEndpoint { /* Method pointers */ NDDS_Transport_ConnectionEndpoint_Send_Fcn send; #if defined(RTI_WIN32) /* Needed by Windows IOCP */ NDDS_Transport_ConnectionEndpoint_AsyncSend_Fcn async_send; #endif NDDS_Transport_ConnectionEndpoint_Receive_Fcn receive; NDDS_Transport_ConnectionEndpoint_Close_Fcn close_conn; NDDS_Transport_ConnectionEndpoint_GetStatus_Fcn get_status; NDDS_Transport_ConnectionEndpoint_NeedsWrite_Fcn needs_write; NDDS_Transport_ConnectionEndpoint_DoHandshake_Fcn do_handshake; NDDS_Transport_ConnectionEndpoint_GetSocket_Fcn get_socket; NDDS_Transport_ConnectionEndpoint_SetSocketOption_Fcn set_socket_option; NDDS_Transport_ConnectionEndpoint_PeerEquals_Fcn peer_equals; /* The factory that created this object */ struct NDDS_Transport_ConnectionEndpointFactory * factory; }; /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Convenience to check if the pure virtual methods have all been implemented */ #define NDDS_Transport_ConnectionEndpoint_is_valid(m) ( \ (m)->send && \ (m)->receive && \ (m)->close_conn && \ (m)->get_status && \ (m)->needs_write && \ (m)->do_handshake && \ (m)->get_socket && \ (m)->peer_equals ) /*i \ingroup NDDS_TransportConnectionEndpointClass \brief Convenience method to safely access the factory that created this connection endpoint. */ #define NDDS_Transport_ConnectionEndpoint_getFactory(m) ( (m) ? (m)->factory : NULL) /* }}} */ /* {{{ Connection Endpoint Factory Class * ================================================================= */ /*i \defgroup NDDS_TransportConnectionEndpointFactoryClass NDDS_Transport_ConnectionEndpointFactory \ingroup NDDS_TransportEndpoint \brief Interface for connection endpoint factory abstraction. */ /*i \ingroup NDDS_TransportConnectionEndpointFactoryClass \brief Interface representation for connection endpoint factory abstraction. */ struct NDDS_Transport_ConnectionEndpointFactory; /*i \ingroup NDDS_TransportConnectionEndpointFactoryClass \brief Create client connection endpoint. @pre A valid Connection Endpoint Factory. @post A valid Connection Endpoint, ready to initiate connection to specified peer. @param dest_address_in \b In. Must be the address of a valid remote peer. @param priority the transport priority or NDDS_TRANSPORT_PRIORITY_DEFAULT @return Newly created ConnectionEndpoint. */ typedef struct NDDS_Transport_ConnectionEndpoint * (*NDDS_Transport_ConnectionEndpointFactory_ConnectEndpointCreateFcn)( struct NDDS_Transport_ConnectionEndpointFactory *me, RTI_INT32 priority, const struct sockaddr *dest_address_in); /*i \ingroup NDDS_TransportConnectionEndpointFactoryClass \brief Create accept-side connection endpoint. @pre A valid Connection Endpoint Factory. @post A valid Connection Endpoint, ready to accept connection from peer. @param listen_sock_in \b In. Raw TCP socket with waiting connection to accept. @return Newly created ConnectionEndpoint. */ typedef struct NDDS_Transport_ConnectionEndpoint * (*NDDS_Transport_ConnectionEndpointFactory_AcceptEndpointCreateFcn)( struct NDDS_Transport_ConnectionEndpointFactory *me, int listen_sock_in, struct sockaddr *client_address_out, socklen_t *client_address_len_inout); /*i \ingroup NDDS_TransportConnectionEndpointFactoryClass \brief Delete a previously created connection endpoint. @pre ConnectionEndpoint no longer used, and no thread blocked on the socket. @post All resources associate with the connection endpoint released. @param endpoint_in \b In. Connection Endpoint object. */ typedef void (*NDDS_Transport_ConnectionEndpointFactory_EndpointDestroyFcn)( struct NDDS_Transport_ConnectionEndpointFactory *me, struct NDDS_Transport_ConnectionEndpoint *endpoint_in); /*i \ingroup NDDS_TransportConnectionEndpointFactoryClass \brief Pure virtual class for the socket factory functionality. */ struct NDDS_Transport_ConnectionEndpointFactory { /* Allow checking the kind of connection endpoint factory */ enum NDDS_Transport_ConnectionEndpointKind kind; /* Method pointers */ NDDS_Transport_ConnectionEndpointFactory_ConnectEndpointCreateFcn create_connect_endpoint; NDDS_Transport_ConnectionEndpointFactory_AcceptEndpointCreateFcn create_accept_endpoint; NDDS_Transport_ConnectionEndpointFactory_EndpointDestroyFcn destroy_endpoint; /* A copy of the properties for this factory. This object is owned by the ConnectionEndpointFactory * object itself and will be destroyed in the factory destructor. */ struct NDDS_Transport_ConnectionEndpointFactoryProperty *properties; }; /*i \ingroup NDDS_TransportConnectionEndpointFactoryClass \brief Convenience to check if the pure virtual methods have all been implemented */ #define NDDS_Transport_ConnectionEndpointFactory_is_valid(m) ( \ (m)->create_connect_endpoint && \ (m)->create_accept_endpoint && \ (m)->destroy_endpoint ) /* }}} */ /* {{{ Connection Endpoint Factory Prototypes * ================================================================= */ /*i \ingroup NDDS_TransportEndpoint @brief The signature of the method that create an endpoint factory */ typedef struct NDDS_Transport_ConnectionEndpointFactory * (* NDDS_Transport_ConnectionEndpointFactory_create)(struct NDDS_Transport_ConnectionEndpointFactoryProperty *); /*i \ingroup NDDS_TransportEndpoint @brief The signature of the method that destroy an endpoint factory */ typedef void (* NDDS_Transport_ConnectionEndpointFactory_delete)(struct NDDS_Transport_ConnectionEndpointFactory *); /* }}} */ #ifdef __cplusplus } /* extern "C" */ #endif #endif /* rtitls_endpoint_h */