Winsock 常用API函数

Winsock 常用API函数
2011年04月29日
　　(1) inet_ntoa()：将一网路位址转换成「点格式」字串。
　　格式： char FAR * PASCAL FAR inet_ntoa( struct in_addr in );
　　参数： in 一个代表 Internet 位址的结构
　　传回值： 成功 - 一个代表位址的「点格式」(dotted) 字串
　　失败 - NULL
　　说明： 此函式将一 Internet 位址转换成「a.b.c.d」字串格式。
　　如下所示：
　　#include
　　char FAR* PASCAL FAR inet_ntoa( struct in_addr in);
　　in：一个表示Internet主机地址的结构。
　　注释：
　　本函数将一个用in参数所表示的Internet地址结构转换成以“.” 间隔的诸如“a.b.c.d”的字符串形式。请注意inet_ntoa()返回的字符串存放在WINDOWS套接口实现所分配的内存中。应用程序不应假设该内存是如何分配的。在同一个线程的下一个WINDOWS套接口调用前，数据将保证是有效。
　　返回值：
　　若无错误发生，inet_ntoa()返回一个字符指针。否则的话，返回NULL。其中的数据应在下一个WINDOWS套接口调用前复制出来。
　　参见：
　　inet_addr().
　　测试代码如下
　　include
　　#include
　　#include
　　#include
　　#include
　　int main(int aargc, char* argv[])
　　{
　　struct in_addr addr1,addr2;
　　ulong   l1,l2;
　　l1= inet_addr("192.168.0.74");
　　l2 = inet_addr("211.100.21.179");
　　memcpy(&addr1, &l1, 4);
　　memcpy(&addr2, &l2, 4);
　　printf("%s : %s\n", inet_ntoa(addr1), inet_ntoa(addr2));    //注意这一句的运行结果
　　printf("%s\n", inet_ntoa(addr1));
　　printf("%s\n", inet_ntoa(addr2));
　　return 0;
　　}
　　实际运行结果如下：
　　192.168.0.74 : 192.168.0.74       //从这里可以看出,printf里的inet_ntoa只运行了一次。
　　192.168.0.74
　　211.100.21.179
　　inet_ntoa返回一个char *,而这个char *的空间是在inet_ntoa里面静态分配的，所以inet_ntoa后面的调用会覆盖上一次的调用。第一句printf的结果只能说明在printf里面的可变参数的求值是从右到左的，仅此而已。
　　(2) htons(): 是对两个字节的数进行主机序到网络序的转换
　　转换的过程举例如下：
　　4367的十六进制为0x110F
　　然后将高位和地位互换，就变成了0x0F11，
　　而0x0F11的十进制为3857，
　　所以htons(4367)=3857； 
　　(3) inet_addr(): 将IP地址从点数格式转换成无符号长整型.
　　如下所示:
　　SOCKADDR_IN addrSrv;
　　addrSrv.sin_addr.S_un.S_addr = inet_addr("127.0.0.1");
　　addrSrv.sin_family = AF_INET;
　　addrSrv.sin_port = htons(6000);
　　(4) ioctlsocket()：控制 Socket 的模式。
　　格式： int PASCAL FAR ioctlsocket( SOCKET s, long cmd, u_long FAR *argP );
　　参数： s Socket 的识别码,cmd 指令名称,argP 指向 cmd 参数的指标
　　传回值： 成功 - 0
　　失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
　　说明： 此函式用来获取或设定 Socket 的运作参数。其所提供的指令有：
　　FIONBIO -- 开关 non-blocking 模式
　　FIONREAD -- 自 Socket 一次可读取的资料量
　　SIOCATMARK -- OOB 资料是否已被读取完 (*暂不提供此功能)
　　(5) listen()：设定 Socket 为监听状态，准备被连接。
　　格 式： int PASCAL FAR listen( SOCKET s, int backlog );
　　参 数： s Socket 的识别码,backlog 未真正完成连接前(尚未呼叫 accept() 前)彼端的连接要求的最大个数
　　传回值： 成功 - 0
　　失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
　　说明： 使用者可利用此函式来设定 Socket 进入监听状态，并设定最多可有多少个在未真正完成连接前的彼端的连接要求。(目前最大值限制为 5, 最小值为1)
　　(6) ntohl()：将一 32 位元 u_long 的值由 network 排列方式转换成host 排列方式。
　　格式： u_long PASCAL FAR ntohl( u_long netlong );
　　参数： netlong 一个 32 位元 network 排列方式的数目
　　传回值： 一个 32 位元 host 排列方式的数目
　　说明： 因为 network 的排列方式与 host 的排列方式可能不同，所以我们需要此一函式来做转换。
　　(7) ntohs()：将一 16 位元 u_short 的值由 network 排列方式转换成host 排列方式。
　　格式： u_short PASCAL FAR ntohs( u_short netshort );
　　参数： netshort 一个 16 位元 network 排列方式的数目
　　传回值： 一个 16 位元 host 排列方式的数目
　　说明： 因为 network 的排列方式与 host 的排列方式可能不同，所以我们需要此一函式来做转换。
　　(8) recv()：自 Socket 接收资料。
　　格式： int PASCAL FAR recv( SOCKET s,char FAR *buf,int len,int flags );
　　参数： s Socket 的识别码,buf 存放接收到的资料的暂存区,len buf 的长度,flags 此函式被呼叫的方式
　　传回值： 成功 - 接收到的资料长度 (若对方 Socket 已关闭，则为 0)
　　失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
　　说明： 此函式用来自连接式的 Datagram Socket 或 Stream Socket接收资料。对 Stream Socket 言，我们可以接收到目前有效的 (available)资料，但其数量不超过 len 的大小。若是此 Socket 设定 SO_OOBINLINE，且有 out-of-band 的资料未被读取，那麽只有 out-of-band 的资料被取出。
　　对 Datagram Socket 言，只取出第一个 datagram；若是该 datagram 大於使用者提供的储存空间，那麽只有该空间大小的资料被取出，多馀的资料将遗失，且回覆错误的讯息。 flags 的值可为 MSG_PEEK、MSG_OOB(*暂不提供此功能)的组合.
　　// 本文转自 C++Builder研究 - http://www.ccrun.com/article.asp?i=187&d=12u0hg
　　(9) recvfrom()：读取一个 Datagram，并储存资料来源的位址。
　　格 式： int PASCAL FAR recvfrom( SOCKET s,char FAR *buf,int len,int flags,struct socketaddr FAR *from,int FAR *fromlen );
　　参 数： s Socket 的识别码,buf 存放接收到的资料的暂存区,len buf 的长度,flags 此函式被呼叫的方式,from 资料来源的位址,fromlen from 的大小
　　传回值： 成功 - 接收到的资料长度 (若对方 Socket 已关闭，则为 0)
　　失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
　　说明： 此函式用来读取资料并记录资料来源的位址。对 Stream Socket 言，其作用与 recv() 相同，参数 from 及 fromlen 将不被用到。
　　(10) select()：检查一或多个 Sockets 是否处於可读、可写或错误的状态。
　　格式： int PASCAL FAR select( int nfds,fd_set FAR *readfds,fd_set FAR *writefds,fd_set FAR *exceptfds,const struct timeval FAR *timeout );
　　参数： nfds 此参数在此并无作用,readfds 要被检查是否可读的 Sockets,writefds 要被检查是否可写的 Sockets,exceptfds 要被检查是否有错误的 Sockets,timeout 此函式该等待的时间。若为 NULL 时，表示 blocking，此函式会等到有事件发生。
　　传回值： 成功 - 符合条件的 Sockets 总数 (若 Timeout 发生，则为 0)
　　失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
　　说明： 使用者可利用此函式来检查 Sockets 是否有资料可被读取，或是有空间可以写入，或是有错误发生。
　　(11) send()：使用连接式的 Socket 传送资料。
　　格式： int PASCAL FAR send( SOCKET s,const char FAR *buf,int len,int flags );
　　参数： s Socket 的识别码,buf 存放要传送的资料的暂存区,len buf 的长度,flags 此函式被呼叫的方式
　　传回值： 成功 - 送出的资料长度
　　失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
　　说明： 此函式适用於连接式的 Datagram 或 Stream Socket 来传送资料。对 Datagram Socket 言，若是 datagram 的大小超过限制，则将不会送出任何资料，并会传回错误值。若是传送 (transport) 系统内之储存空间不够存放这些要传送的资料，send() 将会被 block 住，除非该 Socket 被设定为 non-blocking 模式。使用者亦须注意 send()函式执行完成，并不表示资料已经成功地送抵对方了。 flags 的值可设为 MSG_DONTROUTE(*暂不提供此功能)及 MSG_OOB 的组合.
　　(12) sendto()：将资料送到指定的目的地。
　　格式： int PASCAL FAR sendto( SOCKET s,const char FAR *buf,int len,int flags,const struct sockaddr FAR *to,int tolen );
　　参数： s Socket 的识别码,buf 存放要传送的资料的暂存区,len buf 的长度,flags 此函式被呼叫的方式,to 资料要送达的位址,tolen to 的大小
　　传回值： 成功 - 送出的资料长度
　　失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
　　说明： 此函式适用於 Datagram 或 Stream Socket 来传送资料到指定的位址。对 Datagram Socket 言，若是 datagram 的大小超过限制，则将不会送出任何资料，并会传回错误值。对 Stream Socket 言，其作用与 send() 相同；参数 to 及 tolen 在此并无作用。 若是传送 (transport) 系统内之储存空间不够存放这些要传送的资料，sendto() 将会被 block 住，除非该Socket 被设定为 non-blocking 模式。使用者亦须注意 sendto() 函式执行完成，并不表示资料已经成功地送抵对方了。 flags 的值可设为 MSG_DONTROUTE(*暂不提供此功能)及 MSG_OOB 的组合.