socketclient.h File Reference

The socket client function definitions. More...

#include "common.h"
#include "ipinfo.h"
#include "socketbase.h"

Go to the source code of this file.

Functions
QSC_EXPORT_API qsc_socket_address_families	qsc_socket_client_address_family (const qsc_socket *sock)
	Get the sockets address family, IPv4 or IPv6.
QSC_EXPORT_API qsc_socket_protocols	qsc_socket_client_socket_protocol (const qsc_socket *sock)
	Get the socket protocol type.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_client_connect_host (qsc_socket *sock, const char *host, const char *service)
	Connect to a remote host using the network host name and service name.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_client_connect_ipv4 (qsc_socket *sock, const qsc_ipinfo_ipv4_address *address, uint16_t port)
	Establishes a socket connection to a remote host using IPv4 addressing.
QSC_EXPORT_API qsc_socket_exceptions	qsc_socket_client_connect_ipv6 (qsc_socket *sock, const qsc_ipinfo_ipv6_address *address, uint16_t port)
	Establishes a socket connection to a remote host using IPv6 addressing.
QSC_EXPORT_API qsc_socket_transports	qsc_socket_client_socket_transport (const qsc_socket *sock)
	Get the socket transport type.
QSC_EXPORT_API void	qsc_socket_client_initialize (qsc_socket *sock)
	Initialize the server socket.
QSC_EXPORT_API size_t	qsc_socket_client_receive (const qsc_socket *sock, char *output, size_t otplen, qsc_socket_receive_flags flag)
	Receive data from a synchronous connected socket or a bound connectionless socket.
QSC_EXPORT_API size_t	qsc_socket_client_receive_from (qsc_socket *sock, char *address, uint16_t port, char *output, size_t otplen, qsc_socket_receive_flags flag)
	Receive UDP data from a remote host.
QSC_EXPORT_API size_t	qsc_socket_client_send (const qsc_socket *sock, const char *input, size_t inplen, qsc_socket_send_flags flag)
	Sends data on a connected socket.
QSC_EXPORT_API size_t	qsc_socket_client_send_to (const qsc_socket *sock, const char *address, uint16_t port, const char *input, size_t inplen, qsc_socket_send_flags flag)
	Sends UDP data to a remote host.
QSC_EXPORT_API void	qsc_socket_client_shut_down (qsc_socket *sock)
	Shut down channels and close the socket.

Detailed Description

The socket client function definitions.

This header provides the interface for socket client operations, including connecting to remote hosts via host names or IP addresses (IPv4 and IPv6). It defines functions to retrieve socket attributes such as address family, protocol, and transport type, as well as functions to initialize client sockets, connect, send and receive data, and gracefully shut down socket connections.

// Example: Creating a client socket, connecting, sending and receiving data
qsc_socket client;
qsc_socket_client_initialize(&client);
 
// Connect using a host name and service (e.g., HTTP port 80)
if (qsc_socket_client_connect_host(&client, "example.com", "80") != QSC_SOCKET_RET_SUCCESS) {
    // Handle connection error...
}
 
// Send data over the connection
size_t bytesSent = qsc_socket_client_send(&client, "Hello, world!", 13, 0);
 
// Receive response from the remote host
char buffer[1024];
size_t bytesReceived = qsc_socket_client_receive(&client, buffer, sizeof(buffer), 0);
 
// Shutdown and close the socket
qsc_socket_client_shut_down(&client);

Reference Links:

• Windows Sockets (Winsock) Documentation
• POSIX Sockets Documentation

Function Documentation

qsc_socket_client_address_family()

QSC_EXPORT_API qsc_socket_address_families qsc_socket_client_address_family

(

const qsc_socket *

sock

)

Get the sockets address family, IPv4 or IPv6.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket

Returns

[qsc_socket_address_families] The socket address family

qsc_socket_client_connect_host()

QSC_EXPORT_API qsc_socket_exceptions qsc_socket_client_connect_host	(	qsc_socket *	sock,
		const char *	host,
		const char *	service )

Connect to a remote host using the network host name and service name.

Parameters

sock	[qsc_socket*] A pointer to the initialized socket
host	[const char*] The remote host name
service	[const char*] The service name

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_client_connect_ipv4()

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

Establishes a socket connection to a remote host using IPv4 addressing.

Parameters

sock	[qsc_socket*] A pointer to the initialized socket
address	[const qsc_ipinfo_ipv4_address*] The remote hosts IPv4 address
port	[uint16_t] The remote hosts service port number

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_client_connect_ipv6()

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

Establishes a socket connection to a remote host using IPv6 addressing.

Parameters

sock	[qsc_socket*] A pointer to the initialized socket
address	[const qsc_ipinfo_ipv6_address*] The remote hosts IPv6 address
port	[uint16_t] The remote hosts service port number

Returns

[qsc_socket_exceptions] Returns an exception code on failure, or success(0)

qsc_socket_client_initialize()

QSC_EXPORT_API void qsc_socket_client_initialize

(

qsc_socket *

sock

)

Initialize the server socket.

Parameters

sock	[qsc_socket*] A pointer to the socket structure

qsc_socket_client_receive()

QSC_EXPORT_API size_t qsc_socket_client_receive	(	const qsc_socket *	sock,
		char *	output,
		size_t	otplen,
		qsc_socket_receive_flags	flag )

Receive data from a synchronous connected socket or a bound connectionless socket.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket
output	[size_t] The buffer that receives incoming data
otplen	[size_t] The length of the output buffer
flag	[qsc_socket_receive_flags] Flag that influences the behavior of the receive function

Returns

[size_t] Returns the number of bytes received from the remote host

qsc_socket_client_receive_from()

QSC_EXPORT_API size_t qsc_socket_client_receive_from	(	qsc_socket *	sock,
		char *	address,
		uint16_t	port,
		char *	output,
		size_t	otplen,
		qsc_socket_receive_flags	flag )

Receive UDP data from a remote host.

Parameters

sock	[qsc_socket*] A pointer to the initialized socket
address	[char*] The remote host address
port	[uint16_t] The remote port
output	[char*] The output buffer receiving the data
otplen	[size_t] The number of bytes in the output buffer
flag	[qsc_socket_receive_flags] Flag that influence the behavior of the receive function

Returns

[size_t] Returns the number of bytes sent by the remote host

qsc_socket_client_send()

QSC_EXPORT_API size_t qsc_socket_client_send	(	const qsc_socket *	sock,
		const char *	input,
		size_t	inplen,
		qsc_socket_send_flags	flag )

Sends data on a connected socket.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket
input	[const char*] The input buffer containing the data to be transmitted
inplen	[size_t] The number of bytes to send
flag	[qsc_socket_send_flags] Flag that influence the behavior of the send function

Returns

[size_t] Returns the number of bytes sent to the remote host

qsc_socket_client_send_to()

QSC_EXPORT_API size_t qsc_socket_client_send_to	(	const qsc_socket *	sock,
		const char *	address,
		uint16_t	port,
		const char *	input,
		size_t	inplen,
		qsc_socket_send_flags	flag )

Sends UDP data to a remote host.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket
address	[const char*] The remote host address
port	[uint16_t] The remote port
input	[const char*] The input buffer containing the data to be transmitted
inplen	[size_t] The number of bytes to send
flag	[qsc_socket_send_flags] Flag that influence the behavior of the send function

Returns

[size_t] Returns the number of bytes sent to the remote host

qsc_socket_client_shut_down()

QSC_EXPORT_API void qsc_socket_client_shut_down

(

qsc_socket *

sock

)

Shut down channels and close the socket.

Parameters

sock	[qsc_socket*] A pointer to the initialized socket

qsc_socket_client_socket_protocol()

QSC_EXPORT_API qsc_socket_protocols qsc_socket_client_socket_protocol

(

const qsc_socket *

sock

)

Get the socket protocol type.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket

Returns

[qsc_socket_protocols] The socket protocol type

qsc_socket_client_socket_transport()

QSC_EXPORT_API qsc_socket_transports qsc_socket_client_socket_transport

(

const qsc_socket *

sock

)

Get the socket transport type.

Parameters

sock	[const qsc_socket*] A pointer to the initialized socket

Returns

[qsc_socket_transports] The socket transport type