qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/rtitls/rtitls_endpoint.h

/*
 * 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 <socket.h>
  #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 */