Winsock Sockets API Reference

Sockets API Reference

This section provides detailed documentation for the socket functions available in the Windows Sockets API (Winsock). These functions enable applications to perform network communication using the socket interface.

`socket`

Description: Creates a socket that is an endpoint for communication.

Syntax:

SOCKET socket(
  [in] int af,
  [in] int type,
  [in] int protocol
);

Parameters:

af: The address family. For TCP/IP, use AF_INET (IPv4) or AF_INET6 (IPv6).
type: The socket type. Use SOCK_STREAM for connection-oriented sockets (TCP) or SOCK_DGRAM for datagram sockets (UDP).
protocol: The protocol for the socket. For TCP/IP, this is usually IPPROTO_TCP or IPPROTO_UDP. If set to 0, the system selects the appropriate protocol for the specified socket type.

Return Value: If no error occurs, socket returns a descriptor for the newly created socket. Otherwise, a SOCKET value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.

`bind`

Description: Associates a local address with a socket.

Syntax:

int bind(
  [in] SOCKET s,
  [in] const struct sockaddr *name,
  [in] int namelen
);

Parameters:

s: A descriptor identifying an unbound socket.
name: A pointer to a sockaddr structure that specifies the local address to which to bind the socket.
namelen: The length, in bytes, of the structure pointed to by the name parameter.

Return Value: If no error occurs, bind returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`connect`

Description: Establishes a connection to a specified peer.

Syntax:

int connect(
  [in] SOCKET s,
  [in] const struct sockaddr *name,
  [in] int namelen
);

Parameters:

s: A descriptor identifying an unconnected socket.
name: A pointer to a sockaddr structure that specifies the peer address to which to connect.
namelen: The length, in bytes, of the structure pointed to by the name parameter.

Return Value: If no error occurs, connect returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`listen`

Description: Places a socket in a state in which it is listening for incoming connection requests.

Syntax:

int listen(
  [in] SOCKET s,
  [in] int backlog
);

Parameters:

s: A descriptor identifying an unbound socket.
backlog: The maximum length of the queue of pending connections.

Return Value: If no error occurs, listen returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`accept`

Description: Accepts a connection request on a socket.

Syntax:

SOCKET accept(
  [in] SOCKET s,
  [out] struct sockaddr *addr,
  [in, out] int *addrlen
);

Parameters:

s: A descriptor identifying a socket that is listening for connections.
addr: An optional pointer to a buffer that receives the address of the connecting entity.
addrlen: A pointer to an integer value that specifies the size, in bytes, of the buffer pointed to by the addr parameter.

Return Value: If no error occurs, accept returns a descriptor for a newly created socket that is connected to the peer. Otherwise, it returns INVALID_SOCKET, and a specific error code can be retrieved by calling WSAGetLastError.

`send`

Description: Sends data on a socket.

Syntax:

int send(
  [in] SOCKET s,
  [in] const char *buf,
  [in] int len,
  [in] int flags
);

Parameters:

s: A descriptor identifying an connected socket.
buf: A pointer to a buffer containing the data to be sent.
len: The number of bytes to send from the buffer.
flags: Flags that influence the transmission.

Return Value: If no error occurs, send returns the number of bytes sent. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`recv`

Description: Receives data from a connected socket or a socket that has a connection pending.

Syntax:

int recv(
  [in] SOCKET s,
  [out] char *buf,
  [in] int len,
  [in] int flags
);

Parameters:

s: A descriptor identifying a socket.
buf: A buffer that receives the data sent from the remote host.
len: The maximum number of bytes to receive.
flags: Flags that influence the reception.

Return Value: If no error occurs, recv returns the number of bytes received. If the connection has been gracefully closed, the return value is zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`closesocket`

Description: Closes an existing socket.

Syntax:

int closesocket(
  [in] SOCKET s
);

Parameters:

s: A descriptor identifying the socket to be closed.

Return Value: If no error occurs, closesocket returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

`gethostbyname`

Description: Retrieves the IP address associated with a host name.

Syntax:

struct hostent FAR * gethostbyname(
  const char FAR * name
);

Parameters:

name: The name of the host to resolve.

Return Value: If successful, gethostbyname returns a pointer to a hostent structure. Otherwise, it returns NULL, and a specific error code can be retrieved by calling WSAGetLastError.

`gethostbyaddr`

Description: Retrieves the name associated with an IP address.

Syntax:

struct hostent FAR * gethostbyaddr(
  const char FAR * addr,
  int len,
  int type
);

Parameters:

addr: A pointer to the IP address structure.
len: The length, in bytes, of the address.
type: The address family (e.g., AF_INET).

Return Value: If successful, gethostbyaddr returns a pointer to a hostent structure. Otherwise, it returns NULL, and a specific error code can be retrieved by calling WSAGetLastError.

`ntohs`

Description: Converts a 16-bit quantity from network byte order to host byte order.

Syntax:

unsigned short ntohs(
  unsigned short netshort
);

Parameters:

netshort: A 16-bit quantity in network byte order.

Return Value: ntohs returns the value of the 16-bit quantity in host byte order.

`htons`

Description: Converts a 16-bit quantity from host byte order to network byte order.

Syntax:

unsigned short htons(
  unsigned short hostshort
);

Parameters:

hostshort: A 16-bit quantity in host byte order.

Return Value: htons returns the value of the 16-bit quantity in network byte order.

`inet_addr`

Description: Converts an IPv4 address string to its numerical representation.

Syntax:

unsigned long inet_addr(
  const char FAR * cp
);

Parameters:

cp: A pointer to a NULL-terminated string that contains an IPv4 address in the standard dot-decimal notation.

Return Value: If the string is a valid IPv4 address, inet_addr returns the numerical representation of the address. If the string is not a valid IPv4 address, it returns INADDR_NONE.

`inet_ntoa`

Description: Converts an IPv4 address numerical representation to its standard dot-decimal string format.

Syntax:

char FAR * inet_ntoa(
  struct in_addr in
);

Parameters:

in: An in_addr structure containing the IPv4 address.

Return Value: If successful, inet_ntoa returns a pointer to a character string representing the IP address in dot-decimal notation. Otherwise, it returns NULL.