path: root/support/dktools/dk4socka.h

#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<br>
	  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<br>
	  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 */