#ifndef DK4SOCKA_H_INCLUDED #define DK4SOCKA_H_INCLUDED 1 /** @file dk4socka.h Socket functions with application support. */ #ifndef DK4CONF_H_INCLUDED #include "dk4conf.h" #endif #ifndef DK4TYPES_H_INCLUDED #include "dk4types.h" #endif #ifndef DK4CONST_H_INCLUDED #include "dk4const.h" #endif #ifndef DK4SOCK_H_INCLUDED #include "dk4sock.h" #endif #ifndef DK4APP_H_INCLUDED #include "dk4app.h" #endif #ifdef __cplusplus extern "C" { #endif /* Logging functions. ------------------ Module: dk4socka01 */ /** Retrieve number of log texts in localized string array. @return Number of elements. */ size_t dk4socket_log_num_texts(void); /** Retrieve function name and error code text. On success the function sets the output variables to valid pointers, on error they are set to NULL. @param fctname Address of pointer variable for function name. @param msgtext Address of pointer variable for error code text. @param app Application structure. @param erp Error report. */ void dk4socket_log_fctname_msg( const dkChar **fctname, const dkChar **msgtext, dk4_app_t *app, dk4_er_t *erp ); /** Retrieve array containing localized strings. @param app Application structure, required here. @return Pointer to localized strings array. */ const dkChar * const * dk4socket_log_texts(dk4_app_t *app); /** Issue simple log message, one component. @param app Application structure. @param ll Log level. @param imain Index of main text in array of localized texts. @param erp Error report containing details, may be NULL. */ void dk4socket_log_simple_1( dk4_app_t *app, int ll, size_t imain, dk4_er_t *erp ); /** Issue simple log message, one component. @param app Application structure. @param ll Log level. @param i1 Index of main text in array of localized texts. @param i2 Index of second text in array of localized texts. @param ctext Customized text piece. @param erp Error report containing details, may be NULL. */ void dk4socket_log_simple_3( dk4_app_t *app, int ll, size_t i1, size_t i2, const dkChar *ctext, dk4_er_t *erp ); /** Issue simple log message, five components. @param app Application structure. @param ll Log level. @param i1 Index of main text in array of localized texts. @param i2 Index of third text in array of localized texts. @param i3 Index of fifth text in array of localized texts. @param ct1 Customized text piece 1. @param ct2 Customized text piece 2. @param erp Error report containing details, may be NULL. */ void dk4socket_log_simple_5( dk4_app_t *app, int ll, size_t i1, size_t i2, size_t i3, const dkChar *ct1, const dkChar *ct2, dk4_er_t *erp ); /* Bring socket subsystem up and down. ----------------------------------- Module: dk4socka02 */ /** Bring socket subsystem up. @param app Application structure for diagnostics. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_FAILED on error. Error codes: * DK4_E_SOCKET_UP
with WSAGetLastError() result in iDetails1 if a WinSock error occured. */ int dk4socket_up_app(dk4_app_t *app); /** Bring socket subsystem down. @param app Application structure for diagnostics. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_FAILED on error. Error codes: * DK4_E_SOCKET_DOWN
with WSAGetLastError() result in iDetails1 if a WinSock error occured. */ int dk4socket_down_app(dk4_app_t *app); /* Open and close sockets. ----------------------- Module: dk4socka03 */ /** Open a socket. @param af Address family (AF_INET or AF_INET6). @param tp Socket type (SOCK_STREAM or SOCK_DGRAM). @param pr Protocol number. @param app Application structure for diagnostics, may be NULL. @return Valid socket on success, INVALID_SOCKET on error. */ dk4_socket_t dk4socket_open_app(int af, int tp, int pr, dk4_app_t *app); /** Shut down a socket. @param so Socket to shutdown. @param how How to shut down the socket, one from: DK4_SOCKET_SHUT_READ, DK4_SOCKET_SHUT_WRITE, or DK4_SOCKET_SHUT_RDWR. @param app Application structure for diagnostics, may be NULL. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_FAILED on error. */ int dk4socket_shutdown_app(dk4_socket_t so, int how, dk4_app_t *app); /** Close a socket. @param so Socket to close. @param app Application structure for diagnostics, may be NULL. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_FAILED on error. */ int dk4socket_close_app(dk4_socket_t so, dk4_app_t *app); /* Bind local address. ------------------- Module: dk4socka04 */ /** Bind local address. @param sock Socket to configure. @param pAddr Pointer to address variable. @param szAddr Size of address. @param app Application structure for diagnostics, may be NULL. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_FAILED on error. */ int dk4socket_bind_app( dk4_socket_t sock, const struct sockaddr *pAddr, size_t szAddr, dk4_app_t *app ); /* Listen and accept incoming connection requests. ----------------------------------------------- Module: dk4socka05 */ /** Listen for incoming connection requests. @param sock Server side socket already bound to local address. @param bl Backlog (number of connection requests to keep in the queue). @param app Application structure for diagnostics, may be NULL. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_FAILED on error. */ int dk4socket_listen_app( dk4_socket_t sock, int bl, dk4_app_t *app ); /** Accept an incoming connection. @param sock Server socket in listening state. @param pAddr Buffer for remote address. @param pSzAddr Pointer to address buffer size variable, in: buffer size, out: used buffer size. @param app Application structure for diagnostics, may be NULL. @return Valid socket on success, INVALID_SOCKET on error. */ dk4_socket_t dk4socket_accept_app( dk4_socket_t sock, struct sockaddr *pAddr, size_t *pSzAddr, dk4_app_t *app ); /* Create a tcp client socket. --------------------------- Module: dk4socka07 */ /** Create TCP connection to specified remote host and service. @param hostname Remote host name to connect to. @param svcname Remote service name to connect to. @param lsvcname Local service name, may be NULL. @param secs Seconds for timeout. @param usecs Microseconds for timeout. @param app Application structure for diagnostics, may be NULL. @return Valid socket on success, INVALID_SOCKET on error. */ dk4_socket_t dk4socket_tcp_client_for_host_service_app( const dkChar *hostname, const dkChar *svcname, const dkChar *lsvcname, long secs, long usecs, dk4_app_t *app ); /** Create TCP connection to specified remote host and service. @param hostname Remote host name to connect to. @param svcname Remote service name to connect to. @param lsvcname Local service name, may be NULL. @param secs Seconds for timeout. @param usecs Microseconds for timeout. @param nsrv Flag: Service names contain numbers only. @param app Application structure for diagnostics, may be NULL. @return Valid socket on success, INVALID_SOCKET on error. */ dk4_socket_t dk4socket_tcp_client_for_host_num_service_app( const dkChar *hostname, const dkChar *svcname, const dkChar *lsvcname, long secs, long usecs, int nsrv, dk4_app_t *app ); /** Create TCP connection to specified remote host and port. @param hostname Remote host name to connect to. @param portno Remote port to connect to. @param lportno Local port number, 0 for arbitrary port. @param secs Seconds for timeout. @param usecs Microseconds for timeout. @param app Application structure for diagnostics, may be NULL. @return Valid socket on success, INVALID_SOCKET on error. */ dk4_socket_t dk4socket_tcp_client_for_host_port_app( const dkChar *hostname, unsigned short portno, unsigned short lportno, long secs, long usecs, dk4_app_t *app ); /* Send and receive data. ---------------------- Module: dk4socka08 */ /** Attempt to send data. @param sock Socket to use. @param buf Address of buffer containing data. @param pszbuf Pointer to size variable (in: buffer size, out: bytes transferred). @param flags Flags. @param secs Seconds for timeout. @param usecs Microseconds for timeout. @param app Application structure for diagnostics, may be NULL. @param complain Flag: Complain on partial send. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_IN_PROGRESS on partial success (not all bytes transferred), DK4_SOCKET_RESULT_FAILED on error. */ int dk4socket_send_attempt_app( dk4_socket_t sock, const void *buf, size_t *pszbuf, int flags, long secs, long usecs, dk4_app_t *app, int complain ); /** Send data. @param sock Socket to use. @param buf Address of buffer containing data. @param pszbuf Pointer to size variable (in: buffer size, out: bytes transferred). @param flags Flags. @param secs Seconds for timeout. @param usecs Microseconds for timeout. @param app Application structure for diagnostics, may be NULL. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_IN_PROGRESS on partial success (not all bytes transferred), DK4_SOCKET_RESULT_FAILED on error. */ int dk4socket_send_app( dk4_socket_t sock, const void *buf, size_t *pszbuf, int flags, long secs, long usecs, dk4_app_t *app ); /** Receive data. @param sock Socket to use. @param buf Address of buffer for data. @param pszbuf Pointer to size variable (in: buffer size, out: bytes received). @param flags Flags. @param secs Seconds for timeout. @param usecs Microseconds for timeout. @param app Application structure for diagnostics, may be NULL. @return DK4_SOCKET_RESULT_SUCCESS on success, DK4_SOCKET_RESULT_FAILED on error. */ int dk4socket_recv_app( dk4_socket_t sock, void *buf, size_t *pszbuf, int flags, long secs, long usecs, dk4_app_t *app ); /** Create listener socket set. @param servicename Service name or number. @param backlog Number of queued requests. @param local Flag: Listen on localhost interface only. @param app Application structure for diagnostics, may be NULL. @return Pointer to socket set on success, NULL on error. */ dk4_socket_set_t * dk4socket_set_service_app( const dkChar *servicename, int backlog, int local, dk4_app_t *app ); #ifdef __cplusplus } #endif #endif /* ifndef DK4SOCKA_H_INCLUDED */