windowssocketsapi.txt

windowsocketapi的一些函数

Windows Sockets API 介面
本系统(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 动作会使其变成未定
Windows Sockets API 介面页码，1/11
http://www.gezehua.com/txt/go.asp?id=349 2004-10-21
(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 的识别码
Windows Sockets API 介面页码，2/11
http://www.gezehua.com/txt/go.asp?id=349 2004-10-21
传回值： 成功 - 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，则需等真正建立连接成功後才会传回
正确的位址。
Windows Sockets API 介面页码，3/11
http://www.gezehua.com/txt/go.asp?id=349 2004-10-21
(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 的排列方式可能不同，
所以我们需要此一函式来做转换。
Windows Sockets API 介面页码，4/11
http://www.gezehua.com/txt/go.asp?id=349 2004-10-21
(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
(11) inet_ntoa()：将一网路位址转换成「点格式」字串。
格 式： char FAR * PASCAL FAR inet_ntoa( struct in_addr in );
参 数： in 一个代表 Internet 位址的结构
传回值： 成功 - 一个代表位址的「点格式」(dotted) 字串
失败 - NULL
说明： 此函式将一 Internet 位址转换成「a.b.c.d」字串格式。
(12) ioctlsocket()：控制 Socket 的模式。
格 式： int PASCAL FAR ioctlsocket( SOCKET s,
long cmd,
u_long FAR *argP );
参 数： s Socket 的识别码
cmd 指令名称
argP 指向 cmd 参数的指标
传回值： 成功 - 0
失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
说明： 此函式用来获取或设定 Socket 的运作参数。其所提供的指令有：
(参见 WINSOCK 第 1.1 版 35、36 页)
FIONBIO -- 开关 non-blocking 模式
FIONREAD -- 自 Socket 一次可读取的资料量
SIOCATMARK -- OOB 资料是否已被读取完 (*暂不提供此功能)
(13) listen()：设定 Socket 为监听状态，准备被连接。
格 式： int PASCAL FAR listen( SOCKET s, int backlog );
参 数： s Socket 的识别码
backlog 未真正完成连接前(尚未呼叫 accept() 前)
彼端的连接要求的最大个数
传回值： 成功 - 0
失败 - SOCKET_ERROR (呼叫 WSAGetLastError() 可得知原因)
说明： 使用者可利用此函式来设定 Socket 进入监听状态，并设定最多
可有多少个在未真正完成连接前的彼端的连接要求。(目前最大值限制为 5, 最
小值为1)
(14) ntohl()：将一 32 位元 u_long 的值由 network 排列方式转换成
Windows Sockets API 介面页码，5/11
http://www.gezehua.com/txt/go.asp?id=349 2004-10-21
host 排列方式。
格 式： u_long PASCAL FAR ntohl( u_long netlong );
参 数： netlong 一个 32 位元 network 排列方式的数目
传回值： 一个 32 位元 host 排列方式的数目
说明： 因为 network 的排列方式与 host 的排列方式可能不同，
所以我们需要此一函式来做转换。
(15) ntohs()：将一 16 位元 u_short 的值由 network 排列方式转换成
host 排列方式。
格 式： u_short PASCAL FAR ntohs( u_short netshort );
参 数： netshort 一个 16 位元 network 排列方式的数目
传回值： 一个 16 位元 host 排列方式的数目
说明： 因为 network 的排列方式与 host 的排列方式可能不同，
所以我们需要此一函式来做转换。
(16) recv()：自 Socket 接收资料。
格 式： int PASCAL FAR recv( SOCKET s,
char FAR *buf,
int len,