winsock库函数参考.docx
- 文档编号:20652428
- 上传时间:2023-04-25
- 格式:DOCX
- 页数:95
- 大小:56.08KB
winsock库函数参考.docx
《winsock库函数参考.docx》由会员分享,可在线阅读,更多相关《winsock库函数参考.docx(95页珍藏版)》请在冰豆网上搜索。
winsock库函数参考
第五章套接口库函数参考
5.1WindowsSocket1.1库函数参考
本章以字母顺序列出了套接口库函数,并介绍了技术细节。
使用任一库函数时应在程序中包含WINSOCK.H头文件。
在附录A.2中还列出了一些与BERKELEY兼容的头文件。
这些头文件只起到兼容性的作用,它们都包含了WINSOCK.H头文件,WINDOWS.H头文件也是必需的,但WINSOCK.H会视需要包含这一头文件。
5.1.1accept()
简述:
在一个套接口接受一个连接。
#include
SOCKETPASCALFARaccept(SOCKETs,structsockaddrFAR*addr,
intFAR*addrlen);
s:
套接口描述字,该套接口在listen()后监听连接。
addr:
(可选)指针,指向一缓冲区,其中接收为通讯层所知的连接实体的地址。
Addr参数的实际格式由套接口创建时所产生的地址族确定。
addrlen:
(可选)指针,指向存有addr地址长度的整形数。
注释:
本函数从s的等待连接队列中抽取第一个连接,创建一个与s同类的新的套接口并返回句柄。
如果队列中无等待连接,且套接口为非阻塞方式,则accept()阻塞调用进程直至新的连接出现。
如果套接口为非阻塞方式且队列中等待连接,则accept()返回一错误代码。
已接受连接的套接口不能用于接受新的连接,原套接口仍保持开放。
addr参数为一个返回参数,其中填写的是为通讯层所知的连接实体地址。
addr参数的实际格式由通讯时产生的地址族确定。
addrlen参数也是一个返回参数,在调用时初始化为addr所指的地址空间;在调用结束时它包含了实际返回的地址的长度(用字节数表示)。
该函数与SOCK_STREAM类型的面向连接的套接口一起使用。
如果addr与addrlen中有一个为零NULL,将不返回所接受的套接口远程地址的任何信息。
返回值:
如果没有错误产生,则accept()返回一个描述所接受包的SOCKET类型的值。
否则的话,返回INVALID_SOCKET错误,应用程序可通过调用WSAGetLastError()来获得特定的错误代码。
addrlen所指的整形数初始时包含addr所指地址空间的大小,在返回时它包含实际返回地址的字节长度。
错误代码:
WSANOTINITIALISED:
在使用此API之前应首先成功地调用WSAStartup()。
WSAENETDOWN:
WINDOWS套接口实现检测到网络子系统失效。
WSAEFAULT:
addrlen参数太小(小于socket结构的大小)。
WSAEINTR:
通过一个WSACancelBlockingCall()来取消一个(阻塞的)调用。
WSAEINPROGRESS:
一个阻塞的WINDOWS套接口调用正在运行中。
WSAEINVAL:
在accept()前未激活listen()。
WSAEMFILE:
调用accept()时队列为空,无可用的描述字。
WSAENOBUFS:
无可用缓冲区空间。
WSAENOTSOCK:
描述字不是一个套接口。
WSAEOPNOTSUPP:
该套接口类型不支持面向连接服务。
WSAEWOULDBLOCK:
该套接口为非阻塞方式且无连接可供接受。
参见:
bind(),connect(),listen(),select(),socket(),WSAAsyncSelect().
5.1.2bind()
简述:
将一本地地址与一套接口捆绑。
#include
intPASCALFARbind(SOCKETs,conststructsockaddrFAR*name,
intnamelen);
s:
标识一未捆绑套接口的描述字。
name:
赋予套接口的地址。
sockaddr结构定义如下:
structsockaddr{
u_shortsa_family;
charsa_data[14];
};
namelen:
name名字的长度。
注释:
本函数适用于未连接的数据报或流类套接口,在connect()或listen()调用前使用。
当用socket()创建套接口后,它便存在于一个名字空间(地址族)中,但并未赋名。
bind()函数通过给一个未命名套接口分配一个本地名字来为套接口建立本地捆绑(主机地址/断口号)。
在Internet地址族中,一个名字包括几个组成部分,对于SOCK_PGRAM和SOCK_STREAM类套接口,名字由三部分组成:
主机地址,协议号(显式设置为UDP和TCP)和用以区分应用的端口号。
如果一个应用并不关心分配给它的地址,则可将Internet地址设置为INADDR_ANY,或将端口号置为0。
如果Internet地址段为INADDR_ANY,则可使用任意网络接口;在有多种主机环境下可简化编程。
如果端口号置为0,则WINDOWS套接口实现将给应用程序分配一个值在1024到5000之间的唯一的端口。
应用程序可在bind()后用getsockname()来获知所分配的地址,但必需注意的是,getsockname()只有在套接口连接成功后才会填写Internet地址,这是由于在多种主机环境下若干种Internet地址都是有效的。
如果一个应用程序需要把端口捆绑到超过1024-5000范围的特定端口时,比如rsh需要捆绑到任一保留端口,则可如下编程:
SOCKADDR_INsin;
SOCKETs;
u_shortalport=IPPORT_RESERVED;
sin.sin_family=AF_INET;
sin.sin_addr.s_addr=0;
for(;;){
sin.sin_port=htons(alport);
if(bind(s,(LPSOCKADDR)&sin,sizeof(sin))=0){
/*itworked*/
}
if(GetLastError()!
=WSAEADDRINUSE){
/*fail*/
}
alport-;
if(alport=IPPORT_RESERVED/2){
/*fail-allunassignedreservedportsare*/
/*inuse.*/
}
}
返回值:
如无错误发生,则bind()返回0。
否则的话,将返回SOCKET_ERROR,应用程序可通过WSAGetLastError()获取相应错误代码。
错误代码:
WSANOTINITIALISED:
在使用此API之前应首先成功地调用WSAStartup()。
WSAENETDOWN:
WINDOWS套接口实现检测到网络子系统失效。
WSAEADDRINUSE:
所定端口已在使用中(参见setoption()中的SO_REUSEADDR选项)。
WSAEFAULT:
namelen参数太小(小于sockaddr结构的大小)。
WSAEINPROGRESS:
一个阻塞的WINDOWS套接口调用正在运行中。
WSAEAFNOSUPPORT:
本协议不支持所指定的地址族。
WSAEINVAL:
该套接口已与一个地址捆绑。
WSAENOBUFS:
无足够可用缓冲区,连接过多。
WSAENOTSOCK:
描述字不是一个套接口。
参见:
connect(),listen(),getsockname(),setsockopt(),socket(),WSACancelBlockingCall().
5.1.3closesocket()
简述:
关闭一个套接口。
#include
intPASCALFARclosesocket(SOCKETs);
s:
一个套接口的描述字。
注释:
本函数关闭一个套接口。
更确切地说,它释放套接口描述字s,以后对s的访问均以WSAENOTSOCK错误返回。
若本次为对套接口的最后一次访问,则相应的名字信息及数据队列都将被释放。
closesocket()的语义受SO_LINGER与SO_DONTLINGER选项影响,对比如下:
选项间隔关闭方式等待关闭与否
SO_DONTLINGER不关心优雅否
SO_LINGER零强制否
SO_LINGER非零优雅是
若设置了SO_LINGER(亦即linger结构中的l_onoff域设为非零,参见2.4,4.1.7和4.1.21各节),并设置了零超时间隔,则closesocket()不被阻塞立即执行,不论是否有排队数据未发送或未被确认。
这种关闭方式称为“强制”或“失效”关闭,因为套接口的虚电路立即被复位,且丢失了未发送的数据。
在远端的recv()调用将以WSAECONNRESET出错。
若设置了SO_LINGER并确定了非零的超时间隔,则closesocket()调用阻塞进程,直到所剩数据发送完毕或超时。
这种关闭称为“优雅的”关闭。
请注意如果套接口置为非阻塞且SO_LINGER设为非零超时,则closesocket()调用将以WSAEWOULDBLOCK错误返回。
若在一个流类套接口上设置了SO_DONTLINGER(也就是说将linger结构的l_onoff域设为零;参见2.4,4.1.7,4.1.21节),则closesocket()调用立即返回。
但是,如果可能,排队的数据将在套接口关闭前发送。
请注意,在这种情况下WINDOWS套接口实现将在一段不确定的时间内保留套接口以及其他资源,这对于想用所以套接口的应用程序来说有一定影响。
返回值:
如无错误发生,则closesocket()返回0。
否则的话,返回SOCKET_ERROR错误,应用程序可通过WSAGetLastError()获取相应错误代码。
错误代码:
WSANOTINITIALISED:
在使用此API之前应首先成功地调用WSAStartup()。
WSAENETDOWN:
WINDOWS套接口实现检测到网络子系统失效。
WSAENOTSOCK:
描述字不是一个套接口。
WSAEINPROGRESS:
一个阻塞的WINDOWS套接口调用正在运行中。
WSAEINTR:
通过一个WSACancelBlockingCall()来取消一个(阻塞的)调用。
WSAEWOULDBLOCK:
该套接口设置为非阻塞方式且SO_LINGER设置为非零超时间隔。
参见:
accept(),socket(),ioctlsocket(),setsockopt(),WSAAsyncSelect().
5.1.4connect()
简述:
建立与一个端的连接。
#include
intPASCALFARconnect(SOCKETs,conststructsockaddrFAR*name,
intnamelen);
s:
标识一个未连接套接口的描述字。
name:
欲进行连接的端口名。
namelen:
名字长度。
注释:
本函数用于创建与指定外部端口的连接。
s参数指定一个未连接的数据报或流类套接口。
如套接口未被捆绑,则系统赋给本地关联一个唯一的值,且设置套接口为已捆绑。
请注意若名字结构中的地址域为全零的话,则connect()将返回WSAEADDRNOTAVAIL错误。
对于流类套接口(SOCK_STREAM类型),利用名字来与一个远程主机建立连接,一旦套接口调用成功返回,它就能收发数据了。
对于数据报类套接口(SOCK_DGRAM类型),则设置成一个缺省的目的地址,并用它来进行后续的send()与recv()调用。
返回值:
若无错误发生,则connect()返回0。
否则的话,返回SOCKET_ERROR错误,应用程序可通过WSAGetLastError()获取相应错误代码。
对阻塞套接口而言,若返回值为SOCKET_ERROR则应用程序调用WSAGetLsatError()。
如果它指出错误代码为WSAEWOULDBLOCK,则您的应用程序可以:
1.用select(),通过检查套接口是否可写,来确定连接请求是否完成。
或者,
2.如果您的应用程序使用基于消息的WSAAsynSelect()来表示对连接事件的兴趣,则当连接操作完成后,您会收到一个FD_CONNECT消息。
错误代码:
WSAENOTINITIALISED:
在使用此API之前应首先成功地调用WSAStartup()。
WSAENETDOWN:
WINDOWS套接口实现检测到网络子系统失效。
WSAEADDRINUSE:
所指的地址已在使用中。
WSAEINTR:
通过一个WSACancelBlockingCall()来取消一个(阻塞的)调用。
WSAEINPROGRESS:
一个阻塞的WINDOWS套接口调用正在运行中。
WSAEADDRNOTAVAIL:
在本地机器上找不到所指的地址。
WSAENOTSUPPORT:
所指族中地址无法与本套接口一起使用。
WSAECONNREFUSED:
连接尝试被强制拒绝。
WSAEDESTADDREQ:
需要目的地址。
WSAEFAULT:
namelen参数不正确。
WSAEINVAL:
套接口没有准备好与一地址捆绑。
WSAEISCONN:
套接口早已连接。
WSAEMFILE:
无多余文件描述字。
WSAENETUNREACH:
当前无法从本主机访问网络。
WSAENOBUFS:
无可用缓冲区。
套接口未被连接。
WSAENOTSOCK:
描述字不是一个套接口。
WSAETIMEOUT:
超时时间到。
WSAEWOULDBLOCK:
套接口设置为非阻塞方式且连接不能立即建立。
可用select()调用对套接口写,因为select()时会进行连接。
参见:
accept(),bind(),getsockname(),socket(),select(),WSAAsyncSelect().
5.1.5getpeername()
简述:
获取与套接口相连的端地址。
#include
intPASCALFARgetpeername(SOCKETs,structsockaddrFAR*name,
intFAR*namelen);
s:
标识一已连接套接口的描述字。
name:
接收端地址的名字结构。
namelen:
一个指向名字结构的指针。
注释:
getpeername()函数用于从端口s中获取与它捆绑的端口名,并把它存放在sockaddr类型的name结构中。
它适用于数据报或流类套接口。
返回值:
若无错误发生,getpeername()返回0。
否则的话,返回SOCKET_ERROR,应用程序可通过WSAGetLastError()来获取相应的错误代码。
错误代码:
WSANOTINITIALISED:
在使用此API之前应首先成功地调用WSAStartup()。
WSAENETDOWN:
WINDOWS套接口实现检测到网络子系统失效。
WSAEFAULT:
namelen参数不够大。
WSAEINPROGRESS:
一个阻塞的WINDOWS套接口调用正在运行中。
WSAENOTCONN套接口未连接。
WSAENOTSOCK:
描述字不是一个套接口。
参见:
bind(),socket(),getsockname().
5.1.6getsockname()
简述:
获取一个套接口的本地名字。
#include
intPASCALFARgetsockname(SOCKETs,structsockaddrFAR*name,
intFAR*namelen);
s:
标识一个已捆绑套接口的描述字。
name:
接收套接口的地址(名字)。
namelen:
名字缓冲区长度。
注释:
getsockname()函数用于获取一个套接口的名字。
它用于一个已捆绑或已连接套接口s,本地地址将被返回。
本调用特别适用于如下情况:
未调用bind()就调用了connect(),这时唯有getsockname()调用可以获知系统内定的本地地址。
在返回时,namelen参数包含了名字的实际字节数。
若一个套接口与INADDR_ANY捆绑,也就是说该套接口可以用任意主机的地址,此时除非调用connect()或accept()来连接,否则getsockname()将不会返回主机IP地址的任何信息。
除非套接口被连接,WINDOWS套接口应用程序不应假设IP地址会从INADDR_ANY变成其他地址。
这是因为对于多个主机环境下,除非套接口被连接,否则该套接口所用的IP地址是不可知的。
返回值:
若无错误发生,getsockname()返回0。
否则的话,返回SOCKET_ERROR错误,应用程序可通过WSAGetLastError()获取相应错误代码。
错误代码:
WSANOTINITIALISED:
在使用此API之前应首先成功地调用WSAStartup()。
WSAENETDOWN:
WINDOWS套接口实现检测到网络子系统失效。
WSAEFAULT:
namelen参数不够大。
WSAEINPROGRESS:
一个阻塞的WINDOWS套接口调用正在运行中。
WSAENOTSOCK:
描述字不是一个套接口。
WSAEINVAL:
套接口未用bind()捆绑。
参见:
bind(),socket(),getpeername().
5.1.7getsockopt()
简述:
获取一个套接口选项。
#include
intPASCALFARgetsockopt(SOCKETs,intlevel,intoptname,
charFAR*optval,intFAR*optlen);
s:
一个标识套接口的描述字。
level:
选项定义的层次。
支持的层次仅有SOL_SOCKET和IPPROTO_TCP。
optname:
需获取的套接口选项。
optval:
指针,指向存放所获得选项值的缓冲区。
optlen:
指针,指向optval缓冲区的长度值。
注释:
getsockopt()函数用于获取任意类型、任意状态套接口的选项当前值,并把结果存入optval。
在不同协议层上存在选项,但往往是在最高的“套接口”层次上,设置选项影响套接口的操作,诸如操作的阻塞与否、包的选径方式、带外数据的传送等。
被选中选项的值放在optval缓冲区中。
optlen所指向的整形数在初始时包含缓冲区的长度,在调用返回时被置为实际值的长度。
对SO_LINGER选项而言,相当于linger结构的大小,对其他选项来说,是一个整形数的大小。
如果未进行setsockopt()调用,则getsockopt()返回系统缺省值。
getsockopt()支持下列选项。
其中“类型”栏指出了optval所指向的值。
仅有TCP_NODELAY选项使用了IPPROTO_TCP层;其余选项均使用SOL_SOCKET层。
选项类型意义
SO_ACCEPTCONNBOOL套接口正在用listen()监听。
SO_BROADCASTBOOL套接口设置为传送广播信息。
SO_DEBUGBOOL允许调试。
SO_DONTLINERBOOL若为真,则SO_LINGER选项被禁止。
SO_DONTROUTEBOOL禁止选径。
SO_ERRORint获取错误状态并清除。
SO_KEEPALIVEBOOL发送“保持活动”信息。
SO_LINGERstructlingerFAR*返回当前各linger选项。
SO_OOBINLINEBOOL在普通数据流中接收带外数据。
SO_RCVBUFint接收缓冲区大小。
SO_REUSEADDRBOOL套接口能和一个已在使用中的地址捆绑。
SO_SNDBUFint发送缓冲区大小。
SO_TYPEint套接口类型(如SOCK_STREAM)。
TCP_NODELAYBOOL禁止发送合并的Nagle算法。
getsockopt()不支持的BSD选项有:
选项名类型意义
SO_RCVLOWATint接收低级水印。
SO_RCVTIMEOint接收超时。
SO_SNDLOWATint发送低级水印。
SO_SNDTIMEOint发送超时。
IP_OPTIONS获取IP头中选项。
TCP_MAXSEGint获取TCP最大段的长度。
用一个未被支持的选项去调用getsockopt()将会返回一个WSAENOPROTOOPT错误代码(可用WSAGetLastError()获取)。
返回值:
若无错误发生,getsockopt()返回0。
否则的话,返回SOCKET_ERROR错误,应用程序可通过WSAGetLastError()获取相应错误代码。
错误代码:
WSANOTINITIALISED:
在使用此API之前应首先成功地调用WSAStartup()。
WSAENETDOWN:
WINDOWS套接口实现检测到网络子系统失效。
WSAEFAULT:
optlen参数非法。
WSAEINPROGRESS:
一个阻塞的WINDOWS套接口调用正在运行中。
WSAENOPROTOOPT:
未知或不支持选项。
其中,SOCK_STREAM类型的套接口不支持SO_BROADCAST选项,SOCK_DGRAM类型的套接口不支持SO_ACCEPTCONN、SO_DONTLINGER、SO_KEEPALIVE、SO_LINGER和SO_OOBINLINE选项。
WSAENOTSOCK:
描述字不是一个套接口。
参见:
setsockopt(),WSAAsyncSelect(),socket().
5.1.8htonl()
简述:
将主机的无符号长整形数转换成网络字节顺序。
#include
u_longPASCALFARhtonl(u_longhostlong);
hostlong:
主机字节顺序表达的32位数。
注释:
本函数将一个32位数从主机字节顺序转换成网络字节顺序。
返回值:
htonl()返回一个网络字节顺序的值。
参见:
htons(),ntohl(),ntohs().
5.1.9htons()
简述:
将主机的无符号短整形数转换成网络字节顺序。
#include
u_shortPASCALFARhtons(u_shorthostshort);
hostshort:
主机字节顺序表达的16位数。
注释:
本函数将一个16位数从主机字节顺序转换成网络字节顺序。
返回值:
htons()返回一个网络字节顺序的值。
参见:
htonl(),ntohl(),ntohs().
5.1.10inet_addr()
简述:
将
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- winsock 库函数 参考