socketbase.h

Go to the documentation of this file.

/* 2025 Quantum Resistant Cryptographic Solutions Corporation
 * All Rights Reserved.
 *
 * NOTICE: This software and all accompanying materials are the exclusive 
 * property of Quantum Resistant Cryptographic Solutions Corporation (QRCS).
 * The intellectual and technical concepts contained within this implementation 
 * are proprietary to QRCS and its authorized licensors and are protected under 
 * applicable U.S. and international copyright, patent, and trade secret laws.
 *
 * CRYPTOGRAPHIC STANDARDS:
 * - This software includes implementations of cryptographic algorithms such as 
 *   SHA3, AES, and others. These algorithms are public domain or standardized 
 *   by organizations such as NIST and are NOT the property of QRCS.
 * - However, all source code, optimizations, and implementations in this library 
 *   are original works of QRCS and are protected under this license.
 *
 * RESTRICTIONS:
 * - Redistribution, modification, or unauthorized distribution of this software, 
 *   in whole or in part, is strictly prohibited.
 * - This software is provided for non-commercial, educational, and research 
 *   purposes only. Commercial use in any form is expressly forbidden.
 * - Licensing and authorized distribution are solely at the discretion of QRCS.
 * - Any use of this software implies acceptance of these restrictions.
 *
 * DISCLAIMER:
 * This software is provided "as is," without warranty of any kind, express or 
 * implied, including but not limited to warranties of merchantability or fitness 
 * for a particular purpose. QRCS disclaims all liability for any direct, indirect, 
 * incidental, or consequential damages resulting from the use or misuse of this software.
 *
 * FULL LICENSE:
 * This software is subject to the **Quantum Resistant Cryptographic Solutions 
 * Proprietary License (QRCS-PL)**. The complete license terms are included 
 * in the LICENSE.txt file distributed with this software.
 *
 * Written by: John G. Underhill
 * Contact: john.underhill@protonmail.com
 */
 
#ifndef QSC_SOCKETBASE_H
#define QSC_SOCKETBASE_H
 
#include "common.h"
#include "intutils.h"
#include "ipinfo.h"
#include "memutils.h"
#include "socket.h"
 
QSC_CPLUSPLUS_ENABLED_START

 
/* bogus winbase.h error */
QSC_SYSTEM_CONDITION_IGNORE(5105)
 
#if defined(QSC_SYSTEM_OS_WINDOWS)
#   include <WinSock2.h>
#   include <WS2tcpip.h>
#   include <ws2def.h>
#   include <objbase.h>
#   include <inaddr.h>
#   include <iphlpapi.h>
#   if defined(QSC_SYSTEM_COMPILER_MSC) && defined(QSC_SYSTEM_MAX_PATH)
#       pragma comment(lib, "iphlpapi.lib")
#       pragma comment(lib, "ws2_32.lib")
#   endif
#elif defined(QSC_SYSTEM_OS_POSIX)
#   include <errno.h>
#   include <netdb.h>
#   include <ifaddrs.h>
#   include <netinet/in.h>
#   include <arpa/inet.h>
#   include <sys/select.h>
#   include <sys/socket.h>
#   include <string.h>
#   include <sys/types.h>
#   include <sys/un.h>
#   include <unistd.h>
#   if defined(QSC_SYSTEM_OS_LINUX)
#       include <netpacket/packet.h>
#   elif defined(QSC_SYSTEM_OS_APPLE)
#       include <net/if_dl.h>
#       include <netinet/in.h>
//#     include <netinet/in6.h>
#       if !defined(AF_PACKET)
#           define AF_PACKET PF_INET
#       endif
#   elif defined(QSC_SYSTEM_OS_UNIX)
 
#   endif
//#else
//# error "The operating system is not supported!"
#endif

//\def QSC_SOCKET_DUAL_IPV6_STACK
//* \brief Enables a dual stack ipv4 and ipv6 listener.
//*/
//#if !defined(QSC_SOCKET_DUAL_IPV6_STACK)
//# define QSC_SOCKET_DUAL_IPV6_STACK
//#endif
 
/*** Function State ***/

#define QSC_SOCKET_RECEIVE_BUFFER_SIZE 1600ULL

typedef enum
{
    qsc_socket_exception_success = 0,                               
    qsc_socket_exception_error = -1,                              
    qsc_socket_invalid_input = -2,                                  
#if defined(QSC_SYSTEM_OS_WINDOWS)
    qsc_socket_exception_address_in_use = WSAEADDRINUSE,         
    qsc_socket_exception_address_required = WSAEDESTADDRREQ,       
    qsc_socket_exception_address_unsupported = WSAEAFNOSUPPORT,     
    qsc_socket_exception_already_in_use = WSAEISCONN,                
    qsc_socket_exception_blocking_cancelled = WSAEINTR,              
    qsc_socket_exception_blocking_in_progress = WSAEINPROGRESS,        
    qsc_socket_exception_broadcast_address = WSAEACCES,               
    qsc_socket_exception_buffer_fault = WSAEFAULT,                 
    qsc_socket_exception_circuit_reset = WSAECONNRESET,               
    qsc_socket_exception_circuit_terminated = WSAECONNABORTED,       
    qsc_socket_exception_circuit_timeout = WSAETIMEDOUT,            
    qsc_socket_exception_connection_refused = WSAECONNREFUSED,       
    qsc_socket_exception_descriptor_not_socket = WSAENOTSOCK,     
    qsc_socket_exception_disk_quota_exceeded = WSAEDQUOT,           
    qsc_socket_exception_dropped_connection = WSAENETRESET,          
    qsc_socket_exception_family_unsupported = WSAEPFNOSUPPORT,       
    qsc_socket_exception_host_is_down = WSAEHOSTDOWN,              
    qsc_socket_exception_host_unreachable = WSAEHOSTUNREACH,       
    qsc_socket_exception_in_progress = WSAEALREADY,                 
    qsc_socket_exception_invalid_address = WSAEADDRNOTAVAIL,        
    qsc_socket_exception_invalid_parameter = WSA_INVALID_PARAMETER, 
    qsc_socket_exception_invalid_protocol = WSAEPROTOTYPE,         
    qsc_socket_exception_invalid_protocol_option = WSAENOPROTOOPT,  
    qsc_socket_exception_invalid_provider = WSAEINVALIDPROVIDER,    
    qsc_socket_exception_item_is_remote = WSAEREMOTE,                
    qsc_socket_exception_message_too_long = WSAEMSGSIZE,           
    qsc_socket_exception_name_too_long = WSAENAMETOOLONG,         
    qsc_socket_exception_network_failure = WSAENETDOWN,             
    qsc_socket_exception_network_unreachable = WSAENETUNREACH,      
    qsc_socket_exception_no_buffer_space = WSAENOBUFS,              
    qsc_socket_exception_no_descriptors = WSAEMFILE,             
    qsc_socket_exception_no_memory = WSA_NOT_ENOUGH_MEMORY,         
    qsc_socket_exception_not_bound = WSAEINVAL,                       
    qsc_socket_exception_not_connected = WSAENOTCONN,             
    qsc_socket_exception_not_initialized = WSANOTINITIALISED,       
    qsc_socket_exception_operation_unsupported = WSAEOPNOTSUPP,       
    qsc_socket_exception_protocol_unsupported = WSAEPROTONOSUPPORT,    
    qsc_socket_exception_shut_down = WSAESHUTDOWN,                    
    qsc_socket_exception_socket_unsupported = WSAESOCKTNOSUPPORT,    
    qsc_socket_exception_system_not_ready = WSASYSNOTREADY,            
    qsc_socket_exception_too_many_processes = WSAEPROCLIM,          
    qsc_socket_exception_too_many_users = WSAEUSERS,             
    qsc_socket_exception_translation_failed = WSAELOOP,              
    qsc_socket_exception_would_block = WSAEWOULDBLOCK,              
#else
    qsc_socket_exception_address_in_use = EADDRINUSE,                
    qsc_socket_exception_address_required = EDESTADDRREQ,          
    qsc_socket_exception_address_unsupported = EAFNOSUPPORT,        
    qsc_socket_exception_already_in_use = EISCONN,                   
    qsc_socket_exception_blocking_cancelled = EINTR,             
    qsc_socket_exception_blocking_in_progress = EINPROGRESS,       
    qsc_socket_exception_broadcast_address = EACCES,              
    qsc_socket_exception_buffer_fault = EFAULT,                        
    qsc_socket_exception_circuit_terminated = ECONNABORTED,          
    qsc_socket_exception_circuit_reset = ECONNRESET,              
    qsc_socket_exception_circuit_timeout = ETIMEDOUT,               
    qsc_socket_exception_connection_refused = ECONNREFUSED,          
    qsc_socket_exception_descriptor_not_socket = ENOTSOCK,            
    qsc_socket_exception_disk_quota_exceeded = EDQUOT,              
    qsc_socket_exception_dropped_connection = ENETRESET,         
    qsc_socket_exception_family_unsupported = EPFNOSUPPORT,          
    qsc_socket_exception_host_is_down = EHOSTDOWN,                 
    qsc_socket_exception_host_unreachable = EHOSTUNREACH,          
    qsc_socket_exception_in_progress = EALREADY,                    
    qsc_socket_exception_invalid_address = EADDRNOTAVAIL,           
    //qsc_socket_exception_invalid_parameter = EOTHER,              /*!< One or more parameters are invalid */
    qsc_socket_exception_invalid_protocol = EPROTOTYPE,                
    qsc_socket_exception_invalid_protocol_option = ENOPROTOOPT,     
    //qsc_socket_exception_invalid_provider = EINVALIDPROVIDER,     /*!< The service provider is invalid */
    qsc_socket_exception_item_is_remote = EREMOTE,                   
    qsc_socket_exception_message_too_long = EMSGSIZE,              
    qsc_socket_exception_name_too_long = ENAMETOOLONG,                
    qsc_socket_exception_network_failure = ENETDOWN,                
    qsc_socket_exception_network_unreachable = ENETUNREACH,         
    qsc_socket_exception_no_buffer_space = ENOBUFS,                 
    qsc_socket_exception_no_descriptors = EMFILE,                    
    qsc_socket_exception_not_bound = EINVAL,                      
    qsc_socket_exception_not_connected = ENOTCONN,                    
    qsc_socket_exception_operation_unsupported = EOPNOTSUPP,      
    qsc_socket_exception_protocol_unsupported = EPROTONOSUPPORT,   
    qsc_socket_exception_socket_unsupported = ESOCKTNOSUPPORT,       
    qsc_socket_exception_shut_down = ESHUTDOWN,                       
    qsc_socket_exception_system_not_ready = ETXTBSY,               
    //qsc_socket_exception_too_many_processes = EPROCLIM,           /*!< The host is using too many processes */
    qsc_socket_exception_too_many_users = EUSERS,                    
    qsc_socket_exception_translation_failed = ELOOP,             
    qsc_socket_exception_would_block = EWOULDBLOCK,                 
 
#endif
} qsc_socket_exceptions;

static const char QSC_SOCKET_ERROR_STRINGS[48][128] =
{
    "SUCCESS: The operation completed successfully.",
    "ERROR: The operation has failed.",
    "INVALID: The input parameters are incorrect.",
    "EADDRINUSE: The socket's local address is in use and the socket was not marked to allow address reuse with SO_REUSEADDR.",
    "EDESTADDRREQ: A destination address is required.",
    "EAFNOSUPPORT: The address family is not supported.",
    "EISCONN: The socket is already connected.",
    "EINTR: A blocking sockets call was canceled.",
    "EINPROGRESS: A blocking sockets call is in progress, or the service provider is still processing a callback function.",
    "EACCES: The requested address is a broadcast address, but the appropriate flag was not set.",
    "EFAULT: The buffer parameter is not completely contained in a valid part of the user address space.",
    "ECONNRESET: The virtual circuit was reset by the remote side executing a hard or abortive close.",
    "ECONNABORTED: The virtual circuit was terminated due to a time-out or other failure.",
    "ETIMEDOUT: The connection has been dropped, because of a network failure.",
    "ECONNREFUSED: The connection was refused.",
    "ENOTSOCK: The descriptor is not a socket.",
    "EDQUOT: The disk quota is exceeded.",
    "ENETRESET: The connection has been broken due to the keep-alive activity detecting a failure.",
    "EPFNOSUPPORT: The protocol family is not supported.",
    "EHOSTDOWN: The destination host is down.",
    "EHOSTUNREACH: The remote host cannot be reached from this host at this time.",
    "EALREADY: Operation in progress.",
    "EADDRNOTAVAIL: The address is not available.",
    "INVALID_PARAMETER: One or more parameters are invalid.",
    "EPROTOTYPE: The protocol type is invalid for the socket.",
    "ENOPROTOOPT: The protocol option is invalid.",
    "EINVALIDPROVIDER: The service provider is invalid.",
    "EREMOTE: The item is not available locally.",
    "EMSGSIZE: The message size is too long.",
    "ENAMETOOLONG: The name is too long.",
    "ENETDOWN: The network subsystem has failed.",
    "ENETUNREACH: The network is unreachable.",
    "ENOBUFS: No buffer space is available.",
    "EMFILE: No more socket descriptors are available.",
    "_NOT_ENOUGH_MEMORY: The system does not have enough memory available.",
    "EINVAL: The socket has not been bound with bind, or MSG_OOB was specified for a socket with SO_OOBINLINE enabled.",
    "ENOTCONN: The socket is not connected.",
    "NOTINITIALISED: A successful Startup call must occur before using this function.",
    "EOPNOTSUPP: The socket operation is not supported.",
    "EPROTONOSUPPORT: The protocol is not supported.",
    "ESHUTDOWN: The socket has been shut down.",
    "ESOCKTNOSUPPORT: The socket type is not supported.",
    "SYSNOTREADY: The subsystem is unavailable.",
    "EPROCLIM: The host is using too many processes.",
    "EUSERS: The user quota is exceeded.",
    "ELOOP: Can not translate name.",
    "EWOULDBLOCK: The socket is marked as nonblocking and the requested operation would block.",
    "",
};

typedef struct
{
    void (*callback)(qsc_socket* sock, const uint8_t* message, size_t* msglen);   
    void (*error)(const qsc_socket* sock, qsc_socket_exceptions exception);     
    qsc_socket* source;                                                         
    uint8_t buffer[QSC_SOCKET_RECEIVE_BUFFER_SIZE];                             
} qsc_socket_receive_async_state;

typedef struct
{
    qsc_socket** sockarr;                                                      
    void (*callback)(qsc_socket* sock, size_t id);                                
    void (*error)(qsc_socket* sock, qsc_socket_exceptions exception);           
    uint32_t count;                                                                
} qsc_socket_receive_poll_state;
 
/*** Function Prototypes ***/

//* \brief The socket exception callback prototype
//*
//* \param source:  [qsc_socket*] The socket source
//* \param error:       [qsc_socket_exceptions] The socket exception
//*/
//QSC_EXPORT_API void qsc_socket_exception_callback(qsc_socket* source, qsc_socket_exceptions error);

//* \brief The socket receive asynchronous callback prototype
//*
//* \param source:  [qsc_socket*] The socket source
//* \param message: [const uint8_t*] The socket message buffer
//* \param msglen:  [size_t*] A pointer to the size of the message
//*/
//QSC_EXPORT_API void qsc_socket_receive_async_callback(qsc_socket* source, const uint8_t* message, size_t* msglen);

//* \brief The receive polling callback prototype
//*
//* \param source:  [const qsc_socket*] The socket source
//* \param error:       [size_t] The socket exception
//*/
//QSC_EXPORT_API void qsc_socket_receive_poll_callback(const qsc_socket* source, size_t error);
 
/*** Accessors ***/

QSC_EXPORT_API bool qsc_socket_ipv4_valid_address(const char* address);

QSC_EXPORT_API bool qsc_socket_ipv6_valid_address(const char* address);

QSC_EXPORT_API bool qsc_socket_is_blocking(const qsc_socket* sock);

QSC_EXPORT_API bool qsc_socket_is_connected(const qsc_socket* sock);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_accept(const qsc_socket* source, qsc_socket* target);

QSC_EXPORT_API void qsc_socket_attach(qsc_socket* source, qsc_socket* target);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_bind(qsc_socket* sock, const char* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_bind_ipv4(qsc_socket* sock, const qsc_ipinfo_ipv4_address* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_bind_ipv6(qsc_socket* sock, const qsc_ipinfo_ipv6_address* address, uint16_t port);

QSC_EXPORT_API void qsc_socket_clear_socket(qsc_socket* sock);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_close_socket(qsc_socket* sock);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_connect(qsc_socket* sock, const char* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_connect_ipv4(qsc_socket* sock, const qsc_ipinfo_ipv4_address* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_connect_ipv6(qsc_socket* sock, const qsc_ipinfo_ipv6_address* address, uint16_t port);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_create(qsc_socket* sock, qsc_socket_address_families family, qsc_socket_transports transport, qsc_socket_protocols protocol);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_listen(const qsc_socket* sock, int32_t backlog);

QSC_EXPORT_API size_t qsc_socket_max_send_buffer_size(const qsc_socket* sock);

QSC_EXPORT_API size_t qsc_socket_peek(const qsc_socket* sock, uint8_t* output, size_t otplen);

QSC_EXPORT_API size_t qsc_socket_receive(const qsc_socket* sock, uint8_t* output, size_t otplen, qsc_socket_receive_flags flag);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_receive_async(qsc_socket_receive_async_state* state);

QSC_EXPORT_API size_t qsc_socket_receive_all(const qsc_socket* sock, uint8_t* output, size_t otplen, qsc_socket_receive_flags flag);

QSC_EXPORT_API size_t qsc_socket_receive_from(qsc_socket* sock, char* dest, uint16_t port, uint8_t* output, size_t otplen, qsc_socket_receive_flags flag);

QSC_EXPORT_API uint32_t qsc_socket_receive_poll(const qsc_socket_receive_poll_state* state);

QSC_EXPORT_API size_t qsc_socket_send(const qsc_socket* sock, const uint8_t* input, size_t inplen, qsc_socket_send_flags flag);

QSC_EXPORT_API size_t qsc_socket_send_to(const qsc_socket* sock, const uint8_t* input, size_t inplen, qsc_socket_send_flags flag);

QSC_EXPORT_API size_t qsc_socket_send_all(const qsc_socket* sock, const uint8_t* input, size_t inplen, qsc_socket_send_flags flag);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_shut_down(qsc_socket* sock, qsc_socket_shut_down_flags params);
 
/*~~~ Helper Functions ~~~*/

QSC_EXPORT_API const char* qsc_socket_error_to_string(qsc_socket_exceptions code);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_get_last_error(void);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_ioctl(const qsc_socket* sock, int32_t command, uint32_t* arguments);

QSC_EXPORT_API bool qsc_socket_receive_ready(const qsc_socket* sock, const struct timeval* timeout);

QSC_EXPORT_API bool qsc_socket_send_ready(const qsc_socket* sock, const struct timeval* timeout);

QSC_EXPORT_API void qsc_socket_set_last_error(qsc_socket_exceptions error);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_shut_down_sockets(void);

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_set_option(const qsc_socket* sock, qsc_socket_protocols level, qsc_socket_options option, int32_t optval);

QSC_EXPORT_API bool qsc_socket_start_sockets(void);
 
QSC_CPLUSPLUS_ENABLED_END
 
#endif