gi_tcp.h File Reference

Utility module for TCP sockets. More...

#include "fdbuf.h"
#include "array.h"

Go to the source code of this file.

Classes
struct	gi_tcp
Typedefs
typedef gi_tcp	GiTcp
Enumerations
enum	gi_tcp_direction_t { GI_TCP_INCOMING, GI_TCP_OUTGOING }
Functions
LIBGIFT_EXPORT int	gi_tcpsock_connect (in_addr_t host, in_port_t port, bool blocking)
LIBGIFT_EXPORT int	gi_tcpsock_accept (int fd, bool blocking)
LIBGIFT_EXPORT int	gi_tcpsock_bind (in_port_t port, bool blocking)
LIBGIFT_EXPORT GiTcp *	gi_tcp_wrap (int fd, gi_tcp_direction_t direction, void *udata)
LIBGIFT_EXPORT void	gi_tcp_unwrap (GiTcp *gitcp)
LIBGIFT_EXPORT GiTcp *	gi_tcp_open (in_addr_t host, in_port_t port, bool blocking)
LIBGIFT_EXPORT GiTcp *	gi_tcp_accept (GiTcp *gitcp, bool blocking)
LIBGIFT_EXPORT GiTcp *	gi_tcp_bind (in_port_t port, bool blocking)
LIBGIFT_EXPORT void	gi_tcp_close (GiTcp *gitcp)
LIBGIFT_EXPORT unsigned int	gi_tcp_flush (GiTcp *gitcp)
LIBGIFT_EXPORT int	gi_tcp_send (GiTcp *gitcp, const void *buf, size_t len)
LIBGIFT_EXPORT int	gi_tcp_write (GiTcp *gitcp, const void *buf, size_t len)
LIBGIFT_EXPORT int	gi_tcp_recv (GiTcp *gitcp, void *buf, size_t len)
LIBGIFT_EXPORT int	gi_tcp_peek (GiTcp *gitcp, void *buf, size_t len)
LIBGIFT_EXPORT int	gi_tcp_err (GiTcp *gitcp)
LIBGIFT_EXPORT FDBuf *	gi_tcp_readbuf (GiTcp *gitcp)
LIBGIFT_EXPORT int	gi_tcp_fd (GiTcp *gitcp)
LIBGIFT_EXPORT in_addr_t	gi_tcp_addr (GiTcp *gitcp)
LIBGIFT_EXPORT in_port_t	gi_tcp_port (GiTcp *gitcp)
LIBGIFT_EXPORT char *	gi_tcp_addrstr (GiTcp *gitcp)
LIBGIFT_EXPORT char *	gi_tcp_addrstr_r (GiTcp *gitcp, char *buf, size_t len)

---

Detailed Description

Utility module for TCP sockets.

Two interfaces are provided (unlike gi_udp.h): procedural and object-oriented. The object-oriented interface is preferred by the main giFT developers.

---

Typedef Documentation

typedef struct gi_tcp GiTcp

High-level TCP connection object.

---

Function Documentation

LIBGIFT_EXPORT GiTcp* gi_tcp_accept (  GiTcp *  gitcp, bool  blocking )

Construct a new GiTcp object from the result of a gi_tcpsock_accept call.

LIBGIFT_EXPORT in_addr_t gi_tcp_addr (  GiTcp *  gitcp  )

Accessor for the peer address reported by gi_sock_peername.

LIBGIFT_EXPORT char* gi_tcp_addrstr (  GiTcp *  gitcp  )

Format the result of gi_tcp_addr using dots-and-decimals notation. Please consider using the thread-safe alternative, gi_tcp_addrstr_r. Returns: NUL-terminated string pointed to by static memory.

LIBGIFT_EXPORT char* gi_tcp_addrstr_r (  GiTcp *  gitcp, char *  buf, size_t  len )

Thread-safe alternative to gi_tcp_addrstr. The string will be copied into `buf' up to `len' - 1 bytes. NUL termination is guaranteed. For sanity sake, please provide at least 16 bytes for `buf'. Returns: On success, `buf' is returned; on error, NULL. An error condition is met when not enough input space has been provided to store the entire address string.

LIBGIFT_EXPORT GiTcp* gi_tcp_bind (  in_port_t  port, bool  blocking )

Construct a new GiTcp object from the result of a gi_tcp_bind call.

LIBGIFT_EXPORT void gi_tcp_close (  GiTcp *  gitcp  )

Destroy a GiTcp object wrapper using gi_tcp_unwrap and cleanup the underlying socket descriptor. There is a side-effect with usage of this function that will remove all inputs registered to this file descriptor.

LIBGIFT_EXPORT int gi_tcp_err (  GiTcp *  gitcp  )

Get and clear the the error option on the underlying socket. The error is returned either as a valid value for errno or the WinSock equivalent. To format the error as a string, use ::gi_sockerr_str.

LIBGIFT_EXPORT int gi_tcp_fd (  GiTcp *  gitcp  )

Accessor for the underlying object's file descriptor.

LIBGIFT_EXPORT unsigned int gi_tcp_flush (  GiTcp *  gitcp  )

Abort all buffered writes as with gi_tcp_write. This will be done automatically when the socket is closed or unwrapped with gi_tcp_close or gi_tcp_unwrap, respectively. Note: In contrast with fflush(), this does not write the buffered data. The queue is cleared out and all data that was scheduled for send() is dropped. Returns: Number of messages flushed. This is always the same as the number of messages left in the queue at the time of calling.

LIBGIFT_EXPORT GiTcp* gi_tcp_open (  in_addr_t  host, in_port_t  port, bool  blocking )

Construct a new GiTcp object from the result of a gi_tcpsock_connect call.

LIBGIFT_EXPORT int gi_tcp_peek (  GiTcp *  gitcp, void *  buf, size_t  len )

Simple peek abstraction without relying on MSG_PEEK as part of the API.

LIBGIFT_EXPORT in_port_t gi_tcp_port (  GiTcp *  gitcp  )

Accessor for the peer port reported by gi_sock_peername.

LIBGIFT_EXPORT FDBuf* gi_tcp_readbuf (  GiTcp *  gitcp  )

Accessor for the internally managed FDBuf object. This is the recommended interface for reading structured data from the GiTcp object.

LIBGIFT_EXPORT int gi_tcp_recv (  GiTcp *  gitcp, void *  buf, size_t  len )

Object-oriented wrapper for gi_sock_recv which tracks input/output statistics.

LIBGIFT_EXPORT int gi_tcp_send (  GiTcp *  gitcp, const void *  buf, size_t  len )

Object-oriented wrapper for gi_sock_send which tracks input/output statistics.

LIBGIFT_EXPORT void gi_tcp_unwrap (  GiTcp *  gitcp  )

Destroy a GiTcp object wrapper. This does not affect the underlying file descriptor. If you wish to combine the close and destroy operations, use gi_tcp_close.

LIBGIFT_EXPORT GiTcp* gi_tcp_wrap (  int  fd, gi_tcp_direction_t  direction, void *  udata )

Construct a new GiTcp object to wrap the supplied file descriptor. You may specify the `udata' parameter here or optionally set GiTcp::udata at any time after this call.

LIBGIFT_EXPORT int gi_tcp_write (  GiTcp *  gitcp, const void *  buf, size_t  len )

Implements a user-space buffer to transport the message. It is safe to make subsequent calls without regard for the storage lifetime of the calling arguments or the kernel-space send() buffer. Returns: On successful queueing, `len' cast to an int will be returned; otherwise, -1.

LIBGIFT_EXPORT int gi_tcpsock_accept (  int  fd, bool  blocking )

Similar in spirit to ::gi_tcp_connect.

LIBGIFT_EXPORT int gi_tcpsock_bind (  in_port_t  port, bool  blocking )

Similar in spirit to gi_tcp_bind.

LIBGIFT_EXPORT int gi_tcpsock_connect (  in_addr_t  host, in_port_t  port, bool  blocking )

Greatly simplified interface to connect() which offers very little in the way of flexibility but will do What You Want (TM) in most cases.

---