ext_tcp_utils.h File Reference

External interface for socket manipulations used by Kaa transport channel implementations. More...

#include <platform/sock.h>
#include "kaa_error.h"

Go to the source code of this file.

Data Structures
struct	kaa_dns_resolve_listener_t
	Interface for the deferred DNS results. More...
struct	kaa_dns_resolve_info_t
	The target host information which is used for the DNS resolve needs. More...

Macros
#define	KAA_TCP_SOCKET_NOT_SET   -1

Typedefs
typedef kaa_error_t(*	on_dns_resolve_complete_fn )(void *context, const kaa_sockaddr_t *addr, kaa_socklen_t addr_size)
	The callback for successful DNS results. More...
typedef kaa_error_t(*	on_dns_resolve_failed_fn )(void *context)
	The callback for negative host resolve results. More...

Enumerations
enum	ext_tcp_utils_function_return_state_t { RET_STATE_VALUE_ERROR = 0, RET_STATE_BUFFER_NOT_ENOUGH, RET_STATE_VALUE_READY, RET_STATE_VALUE_IN_PROGRESS }
enum	ext_tcp_socket_state_t { KAA_TCP_SOCK_ERROR = 0, KAA_TCP_SOCK_CONNECTING, KAA_TCP_SOCK_CONNECTED }
enum	ext_tcp_socket_io_errors_t { KAA_TCP_SOCK_IO_OK = 0, KAA_TCP_SOCK_IO_EOF, KAA_TCP_SOCK_IO_ERROR }

Functions
ext_tcp_utils_function_return_state_t	ext_tcp_utils_getaddrbyhost (kaa_dns_resolve_listener_t *resolve_listener, const kaa_dns_resolve_info_t *resolve_props, kaa_sockaddr_t *result, kaa_socklen_t *result_size)
	Resolves the address of the target host. More...
kaa_error_t	ext_tcp_utils_set_sockaddr_port (kaa_sockaddr_t *addr, uint16_t port)
	Sets a new port value to the given sockaddr structure. More...
kaa_error_t	ext_tcp_utils_open_tcp_socket (kaa_fd_t *fd, const kaa_sockaddr_t *destination, kaa_socklen_t destination_size)
	Creates a non-blocking TCP socket and connects it to the given target host. More...
ext_tcp_socket_state_t	ext_tcp_utils_tcp_socket_check (kaa_fd_t fd, const kaa_sockaddr_t *destination, kaa_socklen_t destination_size)
	Checks the state of the given socket descriptor. More...
ext_tcp_socket_io_errors_t	ext_tcp_utils_tcp_socket_write (kaa_fd_t fd, const char *buffer, size_t buffer_size, size_t *bytes_written)
	Writes the buffer into the given socket. More...
ext_tcp_socket_io_errors_t	ext_tcp_utils_tcp_socket_read (kaa_fd_t fd, char *buffer, size_t buffer_size, size_t *bytes_read)
	Reads bytes from the given socket. More...
kaa_error_t	ext_tcp_utils_tcp_socket_close (kaa_fd_t fd)
	Closes the given socket. More...

Detailed Description

External interface for socket manipulations used by Kaa transport channel implementations.

Author

Andriy Panasenko apana.nosp@m.senk.nosp@m.o@cyb.nosp@m.ervi.nosp@m.siont.nosp@m.ech..nosp@m.com

Macro Definition Documentation

#define KAA_TCP_SOCKET_NOT_SET   -1

Typedef Documentation

typedef kaa_error_t(* on_dns_resolve_complete_fn)(void *context, const kaa_sockaddr_t *addr, kaa_socklen_t addr_size)

The callback for successful DNS results.

See ext_tcp_utils_getaddrbyhost.

Parameters

[in]	context	Callback's context.
[in]	addr	The sockaddr structure of the resolved target host.
[in]	addr_size	The size of the sockaddr structure.

Returns

Error code.

typedef kaa_error_t(* on_dns_resolve_failed_fn)(void *context)

The callback for negative host resolve results.

See ext_tcp_utils_getaddrbyhost.

Parameters

[in]

context

Callback's context.

Returns

Error code.

Enumeration Type Documentation

enum ext_tcp_socket_io_errors_t

Enumerator
KAA_TCP_SOCK_IO_OK
KAA_TCP_SOCK_IO_EOF
KAA_TCP_SOCK_IO_ERROR

enum ext_tcp_socket_state_t

Enumerator
KAA_TCP_SOCK_ERROR
KAA_TCP_SOCK_CONNECTING
KAA_TCP_SOCK_CONNECTED

enum ext_tcp_utils_function_return_state_t

Enumerator
RET_STATE_VALUE_ERROR
RET_STATE_BUFFER_NOT_ENOUGH
RET_STATE_VALUE_READY
RET_STATE_VALUE_IN_PROGRESS

Function Documentation

ext_tcp_utils_function_return_state_t ext_tcp_utils_getaddrbyhost	(	kaa_dns_resolve_listener_t *	resolve_listener,
		const kaa_dns_resolve_info_t *	resolve_props,
		kaa_sockaddr_t *	result,
		kaa_socklen_t *	result_size
	)

Resolves the address of the target host.

Parameters

[in]	resolve_listener	The listener properties. It is used in case when this function can't resolve a hostname right now.
[in]	resolve_props	The target host properties (like hostname and port).
[out]	result	The sockaddr_* structure to which the result will be copied.
[in,out]	result_size	The total size of the given storage. It will be updated by the actual result size.

Returns

RET_STATE_VALUE_READY - the address was successfully resolved. RET_STATE_VALUE_IN_PROGRESS - the address will be resolved later. See kaa_dns_resolve_listener_t. RET_STATE_VALUE_ERROR - the resolve failed. RET_STATE_BUFFER_NOT_ENOUGH - the given buffer is not enough to store the result.

kaa_error_t ext_tcp_utils_open_tcp_socket	(	kaa_fd_t *	fd,
		const kaa_sockaddr_t *	destination,
		kaa_socklen_t	destination_size
	)

Creates a non-blocking TCP socket and connects it to the given target host.

Parameters

[out]	fd	The valid pointer to a socket descriptor where the result will be saved.
[in]	destination	The destination address of the target host.
[in]	destination_size	The size of the destination address.

Returns

Error code.

kaa_error_t ext_tcp_utils_set_sockaddr_port	(	kaa_sockaddr_t *	addr,
		uint16_t	port
	)

Sets a new port value to the given sockaddr structure.

Parameters

[in]	addr	The valid pointer to a sockaddr structure.
[in]	port	The new port value in a host byte order.

Returns

Error code.

ext_tcp_socket_state_t ext_tcp_utils_tcp_socket_check	(	kaa_fd_t	fd,
		const kaa_sockaddr_t *	destination,
		kaa_socklen_t	destination_size
	)

Checks the state of the given socket descriptor.

Parameters

[in]	fd	The socket descriptor which is going to be checked.
[in]	destination	The destination address of the target host.
[in]	destination_size	The size of the destination address.

Returns

KAA_TCP_SOCK_ERROR - the connection failed. KAA_TCP_SOCK_CONNECTING - the socket is still connecting. KAA_TCP_SOCK_CONNECTED - the socket was successfully connected.

kaa_error_t ext_tcp_utils_tcp_socket_close

(

kaa_fd_t

fd

)

Closes the given socket.

Parameters

[in]

fd

The socket descriptor which is going to be closed.

Returns

Error code.

ext_tcp_socket_io_errors_t ext_tcp_utils_tcp_socket_read	(	kaa_fd_t	fd,
		char *	buffer,
		size_t	buffer_size,
		size_t *	bytes_read
	)

Reads bytes from the given socket.

Parameters

[in]	fd	The socket descriptor.
[in]	buffer	The buffer to which the read result will be saved.
[in]	buffer_size	The maximum number of bytes to be read.
[out]	bytes_read	The actual number of bytes which were read from the socket.

Returns

KAA_TCP_SOCK_IO_OK - the buffer was successfully obtained from the socket. KAA_TCP_SOCK_IO_EOF - EOF occurred. KAA_TCP_SOCK_IO_ERROR - the operation failed.

ext_tcp_socket_io_errors_t ext_tcp_utils_tcp_socket_write	(	kaa_fd_t	fd,
		const char *	buffer,
		size_t	buffer_size,
		size_t *	bytes_written
	)

Writes the buffer into the given socket.

Parameters

[in]	fd	The socket descriptor.
[in]	buffer	The buffer which is going to be written into the socket.
[in]	buffer_size	The size of the given buffer.
[out]	bytes_written	The actual number of bytes which were successfully written into the socket.

Returns

KAA_TCP_SOCK_IO_OK - the buffer was successfully written into the socket. KAA_TCP_SOCK_IO_ERROR - the operation failed.