DataSource for C SDK  7.1.28.98838-0467ac22
Network Programming

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
fdThe listen socket to accept the connection from.
Returns
The accepted socket; or INVALID_SOCKET

Example: Accepting a pending TCP connection.

1 struct sockaddr_in saddr;
2 sock_t sock;
3 sock_t newsock;
4 
5 if ( (newsock = ds_accept_socket(sock,(struct sockaddr *)&saddr, &len) ) != INVALID_SOCKET ) {
6  // Success
7 }
sock_t ds_client_socket ( const char *  serv,
unsigned short  port 
)

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

Parameters
servThe IP address or hostname of the server
portThe port to connect to
Returns
The created socket; or INVALID_SOCKET.

Example: connecting to port 25 of localhost.

1 sock_t sock;
2 
3 if ( (sock = ds_client_socket("localhost",25) ) != INVALID_SOCKET ) {
4  // Success
5 }
sock_t ds_client_socket_nonblocking ( const char *  serv,
unsigned short  port 
)

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

Parameters
servThe IP address or hostname of the server
portThe port to connect to
Returns
The created socket; or INVALID_SOCKET.

Example: connecting to port 25 of localhost.

1 sock_t sock;
2 
3 if ( (sock = ds_client_socket_nonblocking("localhost",25) ) != INVALID_SOCKET ) {
4  // Success
5 }

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
NULLon 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
addrThe local address to bind to
portThe port to bind to.
backlogQueue 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.

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

or, using a network interface returned from ds_getaddr()

1 if ( (sock = ds_listen_socket(&addr,1025,5)) != INVALID_SOCKET ) {
2  // success
3 }
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
addrThe local address to bind to.
portThe port to bind to.
backlogQueue size of pending connections.
logLogfile to log the socket creation.
contextA 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
ifaceLocal multicast interface
addrMulticast address to listen for
portMulticast 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
fdsAn 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
fdThe socket
int ds_udp_bind_client_socket ( sock_t  sock,
const char *  addr,
int  port 
)

Binds a UDP socket to a local address.

Parameters
sockThe UDP socket
addrThe local interface IP address
portThe 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
addrIP address to send to
portPort to send to
serv_addrReturn 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
ifaceLocal address to bind to
portLocal 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
dataThe data to send
lenLength of the data to send
addrThe IP address or hostname to send to
portThe 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
dataThe data to send
lenLength of the data to send
serv_addrThe network address to send to
Returns
Number of bytes sent; or SOCKET_ERROR

Generated on Fri Jan 20 2023 17:49:17 for DataSource for C SDK