Winsock API

Abstracted from MSDN

网络字节顺序/主机字节顺序(IP address, Port)
Function	Parameter	Return Value
unsigned long inet_addr( __in const char* cp );	const char* cp	点分法IP地址字符串	SUCCEED: unsigned long类型的网络字节顺序格式IP地址. FAIL: INADDR_NONE: cp不是有效的IP地址字符串
Remarks:
1. 功能: 点分法IP地址字符串 à 网络字节顺序(struct in_addr)IP地址
char* FAR inet_ntoa( __in struct in_addr in ); (Net TO Asci)	struct in_addr in	网络字节顺序(struct in_addr)IP地址	SUCCEED: 点分法IP地址字符串. FAIL: NULL
Related Struct:
用来保存网络字节顺序格式的IP地址	typedef struct in_addr { union { struct { u_char s_b1,s_b2,s_b3,s_b4; } S_un_b; struct { u_short s_w1,s_w2; } S_un_w; u_long S_addr; } S_un; } IN_ADDR, *PIN_ADDR, FAR *LPIN_ADDR;
Remarks:
1. 功能: 网络字节顺序(struct in_addr)IP地址 à 点分法IP地址字符串
u_long htonl( __in u_long hostlong ); (Host TO Net Long)	u_long hostlong	主机字节顺序的u_long 值	SUCCEED: 网络字节顺序的u_long FAIL: N/A
Remarks:
1. 功能: 主机字节顺序的u_long (32-bit) à 网络字节顺序的u_long (32-bit)
u_short htons( __in u_short hostshort ); (Host TO Net Short)	u_short hostshort	主机字节顺序的u_short值	SUCCEED: 网络字节顺序的u_short FAIL: N/A
Remarks:
1. 功能: 主机字节顺序的u_short (16-bit) à 网络字节顺序的u_short (16-bit)
u_long ntohl( __in u_long netlong ); (Net TO Host Long)	u_long netlong	网络字节顺序的u_long值	SUCCEED: 主机字节顺序的u_long FAIL: N/A
Remarks:
1. 功能: 网络字节顺序的u_long (32-bit)à 主机字节顺序的u_long (32-bit)
u_short ntohs( __in u_short netshort ); (Net TO Host Short)	u_short netshort	网络字节顺序的u_short值	SUCCEED: 主机字节顺序的u_long FAIL: N/A
Remarks:
1. 功能: 网络字节顺序的u_short (16-bit)à 主机字节顺序的u_short (16-bit)

TCP(面向连接的socket)
Function	Parameter	Return Value
SOCKET socket( __in int af, __in int type, __in int protocol );	int af	指定协议的地址家族. AF_INET: for IPv4; AF_INET6: for IPv6.	SUCCEED: 返回新创建的socket句柄 FAIL: INVALID_SOCKET
int type	指定套接字的类型. SOCK_STREAM(1): for TCP; SOCK_DGRAM(2): for UDP; SOCK_RAW(3): 原始套接字，可用来操纵下层协议(IP)的头.
int protocol	指定套接字使用的协议. IPPROTO_TCP(6): when type is SOCK_STREAM. IPPROTO_UDP(17): when type is SOCK_DGRAM.
Remarks: N/A
int bind( __in SOCKET s, __in const struct sockaddr* name, __in int namelen );	SOCKET s	标识一个未绑定的socket句柄.	SUCCEED: 0 FAIL: SOCKET_ERROR
const struct sockaddr* name	绑定到s的struct sockaddr地址.
int namelen	参数name长度
Related Struct:
通用的socket地址	struct sockaddr { ushort sa_family; char sa_data[14]; }; WindowsVista及以后, sockaddr 被typedef为SOCKADDR: typedef struct sockaddr { #if (_WIN32_WINNT < 0x0600) u_short sa_family; #else ADDRESS_FAMILY sa_family; #endif //(_WIN32_WINNT < 0x0600) CHAR sa_data[14]; } SOCKADDR, *PSOCKADDR, FAR *LPSOCKADDR;
internet环境下套接字的地址形式	struct sockaddr_in { short sin_family; u_short sin_port; struct in_addr sin_addr; char sin_zero[8]; }; WindowsVista及以后, sockaddr_in被typedef为SOCKADDR_IN: typedef struct sockaddr_in { #if(_WIN32_WINNT < 0x0600) short sin_family; #else //(_WIN32_WINNT < 0x0600) ADDRESS_FAMILY sin_family; #endif //(_WIN32_WINNT < 0x0600) USHORT sin_port; IN_ADDR sin_addr; CHAR sin_zero[8]; } SOCKADDR_IN, *PSOCKADDR_IN;
Remarks:
1. 作用: 当socket句柄被创建后, 它就存在于一个命名空间内 (address family), 但没有给它指定名字. 通过bind函数, 指定一个名字与socket关联起来. 2. sockaddr与sockaddr_in sockaddr是通用的socket地址， sockaddr_in是internet环境下套接字的地址形式. 填值的时候使用sockaddr_in结构, 而作为函数(如socket, listen, bind等) 的参数传入的时候转换成sockaddr结构, 因为二者都是16个字节长度. 3. struct sockaddr_in的组成部分: (1) sin_family: 地址家族. AF_INET for IPv4 (2) sin_port: 端口. If sin_port=0, 服务提供者会分配一个1024-5000之间的端口值. If指定端口: sin_port = htons(27015). htons将端口值转为网络字节顺序格式 (3) sin_addr: 主机地址, struct in_addr类型,网络字节顺序格式的IP地址. If sin_addr=ADDR_ANY, 服务提供者指定该socket和0.0.0.0绑定. If指定地址:sin_addr= inet_addr("127.0.0.1");
int listen( __in SOCKET s, __in int backlog );	SOCKET s	指定一个已经绑定但尚未连接的socket.	SUCCEED: 0 FAIL: SOCKET_ERROR
int backlog	指定等待连接队列的最大长度
Remarks:
1. listen函数中backlog参数的意义
SOCKET accept( __in SOCKET s, __out struct sockaddr* addr, __in_out int* addrlen );	SOCKET s	已设置为监听状态的socket	SUCCEED: 返回一个新建的socket句柄 FAIL: INVALID_SOCKET
struct sockaddr* addr	用于接收新建立的socket的地址信息. 可选参数,可设为NULL.
int* addrlen	指定参数 addr的长度. 可选参数,可设为NULL.
Remarks: N/A
int send( __in SOCKET s, __in const char* buf, __in int len, __in int flags );	SOCKET s	已连接的socket	SUCCEED: 返回发送数据的字节数,可能小于len中指定的数据长度. FAIL: SOCKET_ERROR
const char* buf	要发送数据的缓冲区
int len	buf长度
int flags	指定函数调用方式: 0: 指明该函数无特殊行为. DONTROUTE: 指定传输层不要将数据路由出去. MSG_OOB: 从带外 (Out of Band) 发送数据.
Remarks:
1. 允许发送len=0的数据, 此时send返回0
int recv( __in SOCKET s, __out char* buf, __in int len, __in int flags );	SOCKET s	已连接的socket	SUCCEED: 返回接收到的数据的字节数. 返回0:连接已经关闭. FAIL: SOCKET_ERROR
char* buf	用于接收数据的缓冲区
int len	buf长度
int flags	指定函数调用方式: 0: 一般设为0,指明该函数无特殊行为. MSG_PEEK: 复制数据到缓冲区buf,但并不从输入队列中移除这些数据. MSG_OOB: 处理带外数据 MSG_WAITALL: recv返回一直阻塞，直到指定的条件满足时，或者是发生了错误
Remarks: N/A
int shutdown( __in SOCKET s, __in int how );	SOCKET s	指定要禁用的socket.	SUCCEED: 0 FAIL: SOCKET_ERROR
int how	指定禁用的操作: SD_RECEIVE: 不允许该socket再次recv. SD_SEND: 不允许该socket再次send SD_RECEIVE: 不允许该socket再次recv和send.
Remarks:
1. 不再允许在socket上发送或接收数据 2. shutdown不会关闭socket. 在closesocket之前,所有与该socket相关的资源都不会被释放. 3. 断开与socket连接的方式: (1)Graceful Disconnect: 先shutdown禁用socket, 再closesocket关闭连接. (2)Abortive Disconnect: 系统会将没有发送的数据丢弃, 直接closetsocket.
int closesocket( __in SOCKET s );	SOCKET s	指定要关闭的socket.	SUCCEED: 0 FAIL: SOCKET_ERROR
Remarks: N/A
int connect( __in SOCKET s, __in const struct sockaddr* name, __in int namelen );	SOCKET s	指定一个未连接的socket	SUCCEED: 0 FAIL: SOCKET_ERROR
const struct sockaddr* name	指定要建立连接的socket name.
int namelen	指定name length.
Remarks: N/A
C/S模式通信过程
Server	Client
1.初始化winsocket	WSAStartup	1.初始化winsocket	WSAStartup
2.建立socket	socket	2.建立socket	socket
3.与本机进行邦定	bind	N/A
4.开始监听	listen	N/A
5.接受客户端的连接请求	accept	3.与服务器进行连接	connect
6.与客户端进行通信	recv/send	4.与服务器进行通信	send/recv
7.通信完成, 关闭连接	shutdown, closesocket	5.通信完成, 关闭连接	closesocket
8.释放winsocket有关资源	WSACleanup	6.释放winsocket占用的资源	WSACleanup

UDP(面向非连接的socket)
Function	Parameter	Return Value
int sendto( __in SOCKET s, __in const char* buf, __in int len, __in int flags, __in const struct sockaddr* to, __in int tolen );	SOCKET s	已连接的socket	SUCCEED: 返回发送数据的字节数. FAIL: SOCKET_ERROR
const char* buf	要发送数据的缓冲区
int len	buf长度
int flags	指定函数调用方式: 0: 指明该函数无特殊行为. DONTROUTE: 指定传输层不要将数据路由出去. MSG_OOB: 从带外 (Out of Band) 发送数据.
const struct sockaddr* to	指定接收数据的目的地址
in int tolen	to长度
Remarks: N/A
int recvfrom( __in SOCKET s, __out char* buf, __in int len, __in int flags, __out struct sockaddr* from, __in_out int* fromlen );	SOCKET s	已连接的socket	SUCCEED: 返回接收到的数据的字节数. 返回0:连接已经关闭. FAIL: SOCKET_ERROR
char* buf	用于接收数据的缓冲区
int len	buf长度
int flags	指定函数调用方式: 0: 指明该函数无特殊行为. MSG_PEEK: 复制数据到缓冲区buf, 但并不从输入队列中移除这些数据. MSG_OOB:带外处理数据
struct sockaddr* from	指定发送数据的主机地址
int* fromlen	from长度
Remarks: N/A
C/S模式通信过程
Server	Client
1.初始化winsocket	WSAStartup	1.初始化winsocket	WSAStartup
2.建立socket	socket	2.建立socket	socket
3.与本机进行邦定	bind	3.与本机进行邦定	bind
4.与客户端进行通信	recvfrom/sendto	4.与服务器进行通信	sendto
5.通信完成, 关闭连接	closesocket	5.通信完成, 关闭连接	closesocket
6.释放winsocket有关资源	WSACleanup	6.释放winsocket占用的资源	WSACleanup

SOCKET选项操作
Function	Parameter	Return Value
int setsockopt( __in SOCKET s, __in int level, __in int optname, __in const char* optval, __in int optlen );	SOCKET s	socket	SUCCEED: 0. FAIL: SOCKET_ERROR
int level	选项级别: SOL_SOCKET IPPROTO_TCP
int optname	socket选项名称
const char* optval	设置socket选项名称的值数据的缓冲区
int optlen	optval长度
Remarks: N/A
int getsockopt( __in SOCKET s, __in int level, __in int optname, __out char* optval, __in_out int* optlen );	SOCKET s	socket	SUCCEED: 0. FAIL: SOCKET_ERROR
int level	选项级别: SOL_SOCKET IPPROTO_TCP
int optname	socket选项名称
char* optval	接收socket选项名称的值数据的缓冲区
int* optlen	optval长度
Remarks: N/A

getaddrinfo

provides protocol-independent translation from an ANSI host name to an address.

*gethostbyname

retrieves host information corresponding to a host name from a host database.

Note The gethostbyname function has been deprecated by the introduction of the getaddrinfo function. Developers creating Windows Sockets 2 applications are urged to use the getaddrinfo function instead of gethostbyname.

gethostbyaddr

retrieves the host information corresponding to a network address.

Note The gethostbyaddr function has been deprecated by the introduction of the getnameinfo function. Developers creating Windows Sockets 2 applications are urged to use the getnameinfo function instead of gethostbyaddr.