Winsock API 函数大全 1

本系统(WinKing)提供之 Windows Sockets API 介面乃是依照 1993年1月20日公布之 WINSOCK 第1.1版(如附录)中所定义之函式 (routine)； 包括了30个Berkeley Software Distribution (BSD) 的函式以及16个符合 Windows Message-driven 特性的函式。

BSD 函式包括:
accept() bind() closesocket() connect()
getpeername() getsockname() getsockopt() htonl()
htons() inet_addr() inet_ntoa() ioctlsocket()
listen() ntohl() ntohs() recv()
recvfrom() select() send() sendto()
setsockopt() shutdown() socket() gethostname()
gethostbyaddr() gethostbyname()
getprotobyname() getprotobynumber()
getservbyname() getservbyport()

Microsoft Windows-specific Extensions 函式包括:
WSAAsyncGetHostByAddr() WSAAsyncGetHostByName()
WSAAsyncGetProtoByName() WSAAsyncGetProtoByNumber()
WSAAsyncGetServByName() WSAAsyncGetServByPort()
WSAAsyncSelect() WSACancelAsyncRequest()
WSACancelBlockingCall() WSACleanup()
WSAGetLastError() WSAIsBlocking()
WSASetBlockingHook() WSASetLastError()
WSAStartup() WSAUnhookBlockingHook()

这些 API 介面适用於 Internet Protocol Suite (IPS，通常称之为 TCP/IP)，
支援 Stream (TCP) 及 Datagram (UDP) Socket。

Stream (TCP) Socket 提供「双向」、「可靠」、「有次序」、「不重覆」之资料传送。
Datagram (UDP) Socket 则提供「双向」之沟通，但没有「可靠」、「有次序」、「不重覆」等之保证； 所以使用者可能会收到无次序、重覆之资料，甚至资料在传输过程中也可能会遗漏。

[Blocking 与 Non-blocking 模式]

Blocking 模式：使用者呼叫此一模式之函式时，会进入此函式之内部，直到条件或资料完全符合时再回到呼叫点。

Non-blocking 模式：使用者呼叫此一模式之函式时，进入此函式之内部，依当时之条件或资料做适当之回覆，并不会停留在函式之内部到条件或资料完全符合後才回应。

使用者必需注意的是，WINSOCK 定义之 Blocking 模式与一般 Unix 的不太相同。WINSOCK定义允许应用程式在呼叫 Blocking 函式的同时，依旧能够处理其它讯息 (Messages)，包括Keyboard 及 Mouse 的事件；但是此时应用程式除了能用 WSACancelBlockingCall() 函式来取消原先之 locking 动作或用WSAIsBlocking() 函式来检查目前是否有 Blocking 动作仍在进行外，不可以」在原先呼叫之Blocking 函式完成前再呼叫其它的 Socket 函式，不然後者会失败且产生WSAINPROGRESS 的错误。

使用者呼叫 WSACancelBlockingCall()函式所取消的 Blocking 动作若不是accept() 或者 select()的话，那麽之後唯一可呼叫的 Socket 函式只有closesocket()，因为取消一个 Socket 的Blocking 动作会使其变成未定(Indeterminate) 状态。

[Async (非同步) 模式]

使用者呼叫此一模式的函式时，并不会马上得到要求的资料；而是当要求的动作完成後，系统再透过另一种方式来通知呼叫者。其好处是使用者不需等到答覆後才可以再做其它的动作或要求。
WINSOCK定义的 Async 模式是以「PostMessage」的方式告知使用者其要求已经完成；所以在呼叫此类函式时，必须告知 Windows Sockets DLL一些资讯，包括接受讯息的视窗 handle及讯息编号等。

[函式概说]

[BSD Socket 程式库]

(1) accept()：接受某一Socket的连接要求，以完成 Stream Socket 的连接。

格 式： SOCKET PASCAL FAR accept( SCOKET s,struct sockaddr FAR *addr,int FAR *addrlen );
参 数： s Socket的识别码 addr 存放来连接的彼端的位址 addrlen addr的长度
传回值： 成功 - 新的Socket识别码 失败 - INVALID_SOCKET (呼叫 WSAGetLastError() 可得知原因)
说明： Server 端之应用程式呼叫此一函式来接受 Client 端要求之Socket 连接动作；如果Server 端之 Socket 是为 Blocking 模式，且没有人要求连接动作，那麽此一函式会Block 函式马上回覆错误。accept() 函式的答覆值为一新的 Socket，此 Socket 不可再用来接受其它的连接要求；但是原先之 Socket 仍可接受其他人的连接要求。

(2) bind()：指定 Socket 的 Local 位址 (Address)。
格 式： int PASCAL FAR bind( SOCKET s,const struct sockaddr FAR *name,int namelen );
参 数： s Socket的识别码 name Socket的位址值，其格式为
       struct sockaddr
         {
         u_short sa_family;
         char sa_data[14];
         };
namelen name的长度
传回值： 成功 - 0
         失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)

说明： 此一函式是指定 Local 位址及 Port 给某一未定名之 Socket。 使用者若不在意位址或 Port 的值，那麽他可以设定位址为 INADDR_ANY，及Port 为 0；那麽Windows Sockets 会自动将其设定适当之位址及 Port(1024 到 5000之间的值)，使用者可以在此 Socket 真正连接完成後，呼叫 getsockname() 来获知其被设定的值。

(3) closesocket()：关闭某一Socket。
格 式： int PASCAL FAR closesocket( SOCKET s );
参 数： s Socket 的识别码
传回值： 成功 - 0
失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
说明： 此一函式是用来关闭某一 Socket。
若是使用者原先对要关闭之 Socket 设定 SO_DONTLINGER，则在呼叫此一函式後，会马上回覆，但是此一 Sokcet 尚未传送完毕的资料会继续送完後才关闭。
若是使用者原先设定此 Socket 为 SO_LINGER，则有两种情况：
   (a) Timeout 设为 0 的话，此一 Socket 马上重新设定 (reset)，未传完或未收到的资料全部遗失。
   (b) Timeout 不为 0 的话，则会将资料送完，或是等到 Timeout 发生後才关闭。

(4) connect()：要求连接某一Socket到指定的对方。
格 式： int PASCAL FAR connect( SOCKET s,const struct sockaddr FAR *name,int namelen );
参 数： s Socket 的识别码
        name 此 Socket 想要连接的对方位址
        namelen name的长度
传回值：成功 - 0
        失败 - SOCKET_ERROR (呼叫WSAGetLastError()可得知原因)
说明： 此函式用来向对方要求建立连接。若是指定的对方位址为 0 的话，会传回错误值。当连接建立完成後，使用者即可利用此一 Socket 来做传送或接收资料之用了。

(5) getpeername()：获取已连接成功之 Socket 的对方位址。
格 式： int PASCAL FAR getpeername( SOCKET s,struct sockaddr FAR *name,int FAR *namelen );
参 数： s Socket 的识别码
name 此 Socket 连接的对方位址
namelen name 的长度
传回值： 成功 - 0
失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
说明： 此函式可用来取得已连接成功的 Socket 的彼端之位址资料。

(6) getsockname()：获取 Socket 的 Local 位址资料。
格式： int PASCAL FAR getsockname( SOCKET s,struct sockaddr FAR *name,int FAR *namelen );
参数： s Socket 的识别码
name 此 Socket 的 Local 位址
namelen name 的长度
传回值： 成功 - 0
失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
说明： 此函式是用来取得已设定位址或已连接之 Socket 的本端位址资料。若是此 Socket 被设定为 INADDR_ANY，则需等真正建立连接成功後才会传回正确的位址。

(7) getsockopt()：要求某一 Socket 目前状态设定的资料。
格式： int PASCAL FAR getsockopt( SOCKET s,int level,int optname,char FAR *optval,int FAR *optlen );
参数： s= Socket的识别码,level=选项设定的,level=optname 选项名称,optval=选项的设定值,optlen=选项设定值的长度
传回值： 成功 - 0
失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
说明： 此函式用来获取目前 Socket的某些状态设定值。 WINSOCK 提供之 level 只有 SOL_SOCKET 及 IPPROTO_TCP optname则有以下 之选择：(参见WINSOCK 第 29、30 页之定义)
Value Type
-----------------------------------------------
SO_ACCEPTCONN BOOL
SO_BROADCAST BOOL
*SO_DEBUG BOOL
SO_DONTLINGER BOOL
*SO_DONTROUTE BOOL
*SO_ERROR int
*SO_KEEPALIVE BOOL
SO_LINGER struct linger FAR*
SO_OOBINLINE BOOL
*SO_RCVBUF int
SO_REUSEADDR BOOL
*SO_SNDBUF int
SO_TYPE int
TCP_NODELAY BOOL
(* 表示暂不提供此功能选项)

(8) htonl()：将一 32 位元 u_long 的值由 host 的排列方式转换成network 的排列方式。
格式： u_long PASCAL FAR htonl( u_long hostlong );
参数： hostlong 一个 32 位元 host 排列方式的数目
传回值： 一个 32 位元 network 排列方式的数目
说明： 因为 network 的排列方式与 host 的排列方式可能不同，所以我们需要此一函式来做转换。

(9) htons()：将一 16 位元u_short 的值由 host 的排列方式转换成network 的排列方式。
格 式： u_short PASCAL FAR htons( u_short hostshort );
参 数： hostshort 一个 16 位元 host 排列方式的数目
传回值： 一个 16 位元 network 排列方式的数目
说明： 因为 network 的排列方式与 host 的排列方式可能不同，所以我们需要此一函式来做转换。

(10) inet_addr()：将字串格式的位址转换成 32 位元 unsigned long 的格式。
格式： unsigned long PASCAL FAR inet_addr( const char FAR *cp );
参数： cp 一个代表位址的「点格式」(dotted) 字串
传回值： 成功 - 一个代表 Internet 位址的 unsigned long
失败 - INADDR_NONE
说明： 此函式将一「点格式」的位址字串转换成适用之Intenet位址。
「点格式」字串可为以下四种方式之任一：
(i) a.b.c.d (ii) a.b.c (iii) a.b (iv) a