WSACreateEvent(),WSAEventSelect,WSAWaitForMultipleEvents(),WSAEnumNetworkEvents()

WSACreateEvent()

简述：创建一个新的事件对象。

          #include <winsock2.h>

          WSAEVENT WSAAPI WSACreateEvent( VOID );

返回值：
  如果函数成功，则返回值即是事件对象的句柄。
  如果函数失败，返回WSA_INVALID_EVENT。应用程序可通过调用WSAGetLastError()函数获取进一步的错误信息。
         
错误代码：
WSANOTINITIALISED                在调用本API之前应成功调用WSAStartup()。
WSAENETDOWN                        网络子系统失效。
WSA_NOT_ENOUGH_MEMORY         无足够内存创建事件对象。

WSAEventSelect()

 

简述：确定与所提供的FD_XXX网络事件集合相关的一个事件对象。

          #include <winsock2.h>

          int WSAAPI WSAEventSelect ( SOCKET s, WSAEVENT
          hEventObject, long lNetworkEvents );

         
s：一个标识套接口的描述字。
hEventObject：一个句柄，用于标识与所提供的FD_XXX网络事件集合相关的一个事件对象。
lNetworkEvents：一个屏蔽位，用于指定感兴趣的FD_XXX网络事件组合。

返回值：
  如果应用程序指定的网络事件及其相应的事件对象成功设置，则返回0。否则的话，将返回INVALID_SOCKET错误，应用程序可通过WSAGetLastError()来获取相应的错误代码。
  在使用select()和WSAAsyncSelect()函数时，WSAEventSelect()常用来决定何时进行数据传送操作（如send()或recv()），并期望能立即成功。但是一个稳定的应用程序应该做好这样的准备，即事件对象被设置，并且一个WinSock调用以WSAEWOULDBLOCK立即返回 。举例来说，有可能发生下述操作序列：

(i) 套接口s上到达数据；WinSock设置了WSAEventSelect事件对象。
(ii) 应用程序进行其他操作。
(iii) 在进行操作时，应用程序调用了ioctlsocket(s, FIONREAD...)并发现有数据可读。
(iv) 应用程序调用一个recv(s,...)来读取数据。
(v) 最后应用程序等待WSAEventSelect()所指定的数据对象，该数据对象指出数据可读。
(vi) 应用程序调用recv(s,...)，但以WSAEWOULDBLOCK错误失败。
         
  其他的操作序列也是可能的。
  成功地记录了网络事件的发生（通过设置内部网络事件记录的相应位），并且将相应的事件对象设置了信号后，不会对该网络事件作进一步的操作，直到应用程序调用了相应的函数显式地重新允许该网络事件及相应事件对象的信号。
网络事件                                        重新允许函数
FD_READ                                recv() 或 recvfrom()
FD_WRITE                                send() 或 sendto()
FD_OOB                                        recv()
FD_ACCEPT                                accept() 或WSAAccept()，直到返回的错误代码为 WSATRY_AGAIN，指明条件函数返回CF_DEFER。
FD_CONNECT                        NONE
FD_CLOSE                                NONE
FD_QOS                                        用SIO_GET_QOS 命令调用WSAIoctl()。
FD_GROUP_QOS                        用SIO_GET_GROUP_QOS命令调用WSAIoctl()。

错误代码：
WSANOTINITIALISED                在调用本API之前应成功调用WSAStartup()。
WSAENETDOWN                        网络子系统失效。
WSAEINVAL                                参数中有非法值，或者指定的套接口处于非法状态。
WSAEINPROGRESS                一个阻塞的WinSock调用正在进行中，或者服务提供者仍在处理一个回调函数
WSAENOTSOCK                        描述字不是一个套接口。

 

WSAWaitForMultipleEvents()

简述：只要指定事件对象中的一个或全部处于有信号状态，或者超时间隔到，则返回。

          #include <winsock2.h>

          DWORD WSAAPI WSAWaitForMultipleEvents( DWORD
          cEvents,
          const WSAEVENT FAR * lphEvents, BOOL fWaitAll,
          DWORD dwTimeout,
          BOOL fAlertable );

cEvents：指出lphEvents所指数组中事件对象句柄的数目。事件对象句柄的最大值为WSA_MAXIMUM_WAIT_EVENTS。
lphEvents：指向一个事件对象句柄数组的指针。
fWaitAll：指定等待类型。若为真TRUE，则当lphEvents数组中的所有事件对象同时有信号时，函数返回。若为假FALSE，则当任意一个事件对象有信号时函数即返回。在后一种情况下，返回值指出是哪一个事件对象造成函数返回。
dwTimeout：指定超时时间间隔（以毫秒计）。当超时间隔到，函数即返回，不论fWaitAll参数所指定的条件是否满足。如果dwTimeout为零，则函数测试指定的时间对象的状态，并立即返回。如果dwTimeout是WSA_INFINITE，则函数的超时间隔永远不会到。
fAlertable：指定当系统将一个输入/输出完成例程放入队列以供执行时，函数是否返回。若为真TRUE，则函数返回且执行完成例程。若为假FALSE，函数不返回，不执行完成例程。请注意在Win16中忽略该参数。

返回值：
  如果函数成功，返回值指出造成函数返回的事件对象。
  如果函数失败，返回值为WSA_WAIT_FAILED。可调用WSAGetLastError()来获取进一步的错误信息。

错误代码：
WSANOTINITIALISED                在调用本API之前应成功调用WSAStartup()。
WSAENETDOWN                        网络子系统失效。
WSA_NOT_ENOUGH_MEMORY        无足够内存完成该操作。
WSA_INVALID_HANDLE         lphEvents数组中的一个或多个值不是合法的事件对象句柄。
WSA_INVALID_PARAMETER                cEvents参数未包含合法的句柄数目。

 

WSAEnumNetworkEvents()

简述：检测所指定套接口上网络事件的发生。

          #include <winsock2.h>

          int WSAAPI WSAEnumNetworkEvents ( SOCKET s,
          WSAEVENT hEventObject, LPWSANETWORKEVENTS
          lpNetworkEvents,  LPINT lpiCount);

s：标识套接口的描述字。
hEventObject：（可选）句柄，用于标识需要复位的相应事件对象。
lpNetworkEvents：一个WSANETWORKEVENTS结构的数组，每一个元素记录了一个网络事件和相应的错误代码。
lpiCount：数组中的元素数目。在返回时，本参数表示数组中的实际元素数目；如果返回值是WSAENOBUFS，则表示为获取所有网络事件所需的元素数目。

返回值：
  如果操作成功则返回0。否则的话，将返回INVALID_SOCKET错误，应用程序可通过WSAGetLastError()来获取相应的错误代码。

错误代码：
WSANOTINITIALISED                在调用本API之前应成功调用WSAStartup()。
WSAENETDOWN                        网络子系统失效。
WSAEINVAL                                参数中有非法值。
WSAEINPROGRESS                一个阻塞的WinSock调用正在进行中，或者服务提供者仍在处理一个回调函数WSAENOBUFS                        所提供的缓冲区太小。