Macros
#define	INVALID_SOCKET -1
	A constant representing an invalid socket. More...

#define	SOCKET_ERROR -1
	A constant representing an error on a socket. More...

Typedefs
typedef int	sock_t
	The network socket datatype. More...

Functions
sock_t	ds_accept_socket (sock_t fd)
	Accepts a connection from a listen socket. More...

sock_t	ds_client_socket (const char *serv, unsigned short port)
	Creates a client socket with which to connect to a host. More...

sock_t	ds_client_socket_nonblocking (const char *serv, unsigned short port)
	Creates a client socket with which to connect to a host. More...

struct sockaddr_storage *	ds_gethostsockaddr (const char name, struct sockaddr_storage serv_addr)
	Return the socket address for a given hostname. More...

char *	ds_getnameinfo (const struct sockaddr_storage addr, char buf, size_t buflen)
	return the string representation of the address passed in More...

sock_t	ds_listen_socket (const char *addr, int port, int backlog)
	Creates a listen socket on the specified local address and TCP port. More...

sock_t	ds_listen_socket_log (const char addr, int port, int backlog, ds_log_t log, const char *context)
	Wrapper for ds_listen_socket that creates a listen socket and logs that creation. More...

sock_t	ds_multicast_listen_socket (const char iface, const char addr, int port)
	Creates a multicast listen socket. More...

int	ds_pipe (sock_t fds[2])
	Creates a UNIX-style pipe. More...

void	ds_setnonblocking (sock_t fd)
	Set a socket to be non-blocking. More...

int	ds_udp_bind_client_socket (sock_t sock, const char *addr, int port)
	Binds a UDP socket to a local address. More...

sock_t	ds_udp_client_socket (const char addr, int port, struct sockaddr_storage serv_addr)
	Creates a UDP client socket. More...

sock_t	ds_udp_listen_socket (const char *iface, int port)
	Creates a UDP listen socket. More...

int	ds_udp_send (const char data, int len, const char addr, int port)
	Sends data to a UDP address. More...

int	ds_udp_sendto (const char data, int len, struct sockaddr_storage serv_addr)
	Sends data to a UDP address. More...

Detailed Description

DataSource SDK provides a simplified network programming API, including wrappers to standard system calls and library functions.

Using these wrappers will ensure that the network code in your DataSource application will work across all supported platforms.

Macro Definition Documentation

#define INVALID_SOCKET -1

A constant representing an invalid socket.

This is provided for compatibility between Win32 and UNIX systems

#define SOCKET_ERROR -1

A constant representing an error on a socket.

This is provided for compatibility between Win32 and UNIX systems

Typedef Documentation

typedef int sock_t

The network socket datatype.

Function Documentation

sock_t ds_accept_socket ( sock_t fd )

Accepts a connection from a listen socket.

Parameters

fd	The listen socket to accept the connection from.

Returns: The accepted socket; or INVALID_SOCKET

Example: Accepting a pending TCP connection.

 struct sockaddr_in  saddr;
 sock_t              sock;
 sock_t              newsock;
 
 if ( (newsock = ds_accept_socket(sock,(struct sockaddr *)&saddr, &len) ) != INVALID_SOCKET ) {
     // Success
 }

sock_t ds_client_socket	(	const char *	serv,
		unsigned short	port
	)

Creates a client socket with which to connect to a host.

Parameters

serv	The IP address or hostname of the server
port	The port to connect to

Returns: The created socket; or INVALID_SOCKET.

Example: connecting to port 25 of localhost.

 sock_t             sock;
 
 if ( (sock = ds_client_socket("localhost",25) ) != INVALID_SOCKET ) {
     // Success
 }

sock_t ds_client_socket_nonblocking	(	const char *	serv,
		unsigned short	port
	)

Creates a client socket with which to connect to a host.

Parameters

serv	The IP address or hostname of the server
port	The port to connect to

Returns: The created socket; or INVALID_SOCKET.

Example: connecting to port 25 of localhost.

 sock_t             sock;
 
 if ( (sock = ds_client_socket_nonblocking("localhost",25) ) != INVALID_SOCKET ) {
     // Success
 }

Following this read and write events should be registered as necessary to catch the result of the non-blocking connect.

Hint:

If the descriptor comes back as writable ONLY then the connection has successful.
If the descriptor comes back both writeable and readable then:
- The connection has been established and data has been rcvd from the remote end before select was called / returned.
- An error occurred and the connection could not be properly established.

When #2 occurs, I typically just call connect(...) again and if I get a -1 and errno == EISCONN I know I can continue on while any other errno should mean a failure.

Another often heard suggestion is to do a read against the socket with a requested length of 0 - you should get a 0 on return and a -1 if there is a problem. While certainly valid, some people find this a bit counter intuitive to use since a return of 0 on a read normally means EOF / shutdown of the connection by the remote side.

struct sockaddr_storage* ds_gethostsockaddr	(	const char *	name,
		struct sockaddr_storage *	serv_addr
	)

Return the socket address for a given hostname.

Parameters

name	- Hostname
serv_addr	- Address to be populated

Return values

NULL	- Could not determine name of server
serv_addr	- Serv_addr contains some valid information

char* ds_getnameinfo	(	const struct sockaddr_storage *	addr,
		char *	buf,
		size_t	buflen
	)

return the string representation of the address passed in

Parameters

addr	- Address to be formatted into a string
buf	- Buffer to write string representation of addr into
buflen	- lenght of buffer

Return values

NULL	on failure and a pointer to buf holding the string representation on success

sock_t ds_listen_socket	(	const char *	addr,
		int	port,
		int	backlog
	)

Creates a listen socket on the specified local address and TCP port.

Parameters

addr	The local address to bind to
port	The port to bind to.
backlog	Queue size of pending connections.

Returns: The created sock_t on success, or INVALID_SOCKET on failure

If the address is NULL then all local interfaces will be bound to.

Example: Listening on TCP port 1025 with a backlog of 5 pending connections.

 sock_t  sock;
 
 if ( (sock = ds_listen_socket(NULL,1025,5)) != INVALID_SOCKET ) {
     // success
 }

or, using a network interface returned from ds_getaddr()

 if ( (sock = ds_listen_socket(&addr,1025,5)) != INVALID_SOCKET ) {
     // success
 }

sock_t ds_listen_socket_log	(	const char *	addr,
		int	port,
		int	backlog,
		ds_log_t *	log,
		const char *	context
	)

Wrapper for ds_listen_socket that creates a listen socket and logs that creation.

Parameters

addr	The local address to bind to.
port	The port to bind to.
backlog	Queue size of pending connections.
log	Logfile to log the socket creation.
context	A context string to print in the log.

Returns: The created sock_t on success, or INVALID_SOCKET on failure

See also: ds_listen_socket()

sock_t ds_multicast_listen_socket	(	const char *	iface,
		const char *	addr,
		int	port
	)

Creates a multicast listen socket.

Parameters

iface	Local multicast interface
addr	Multicast address to listen for
port	Multicast port to listen for

Returns: The created socket; or INVALID_SOCKET

The iface parameter is needed on a multi-network machine on some operating systems, it defines the local network interface on which the multicast data will be received.

int ds_pipe ( sock_t fds[2] )

Creates a UNIX-style pipe.

Parameters

fds	An array of 2 sock_t variables

Return values

0	- Success
SOCKET_ERROR	- Failure

Note: On UNIX systems this function simply calls pipe(); on Win32 ds_pipe() creates a socket connection to itself, simulating a UNIX-style pipe

void ds_setnonblocking ( sock_t fd )

Set a socket to be non-blocking.

Parameters

fd	The socket

int ds_udp_bind_client_socket	(	sock_t	sock,
		const char *	addr,
		int	port
	)

Binds a UDP socket to a local address.

Parameters

sock	The UDP socket
addr	The local interface IP address
port	The local port

Return values

0	- Success
SOCKET_ERROR	- failure

The addr parameter can be NULL, in which case all local addresses will be bound to.

sock_t ds_udp_client_socket	(	const char *	addr,
		int	port,
		struct sockaddr_storage *	serv_addr
	)

Creates a UDP client socket.

Parameters

addr	IP address to send to
port	Port to send to
serv_addr	Return parameter

Returns: The created socket; or INVALID_SOCKET

sock_t ds_udp_listen_socket	(	const char *	iface,
		int	port
	)

Creates a UDP listen socket.

Parameters

iface	Local address to bind to
port	Local port to bind to

Returns: The created socket; or INVALID_SOCKET.

int ds_udp_send	(	const char *	data,
		int	len,
		const char *	addr,
		int	port
	)

Sends data to a UDP address.

Parameters

data	The data to send
len	Length of the data to send
addr	The IP address or hostname to send to
port	The port to send to

Returns: Number of bytes sent; or SOCKET_ERROR

int ds_udp_sendto	(	const char *	data,
		int	len,
		struct sockaddr_storage *	serv_addr
	)

Sends data to a UDP address.

Parameters

data	The data to send
len	Length of the data to send
serv_addr	The network address to send to

Returns: Number of bytes sent; or SOCKET_ERROR

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation