WSAStartup
int WSAStartup( WORD wVersionRequested, LPWSADATA lpWSAData);
相關簡介
WSAStartup，即WSA(Windows Sockets Asynchronous，Windows異步套接字)的啟動命令。是Windows下的網路編程接口軟體Winsock1 或 Winsock2 裡面的一個命令（Ps：Winsock 是由Unix下的BSD Socket發展而來,是一個與網路協定無關的編程接口）。
詳細說明
為了在應用程式當中調用任何一個Winsock API函式，首先第一件事情就是必須通過WSAStartup函式完成對Winsock服務的初始化，因此需要調用WSAStartup函式。使用Socket的程式在使用Socket之前必須調用WSAStartup函式。該函式的第一個參數指明程式請求使用的Socket版本，其中高位位元組指明副版本、低位位元組指明主版本；作業系統利用第二個參數返回請求的Socket的版本信息。當一個應用程式調用WSAStartup函式時，作業系統根據請求的Socket版本來搜尋相應的Socket庫，然後綁定找到的Socket庫到該應用程式中。以後應用程式就可以調用所請求的Socket庫中的其它Socket函式了。
函式定義
int WSAStartup ( WORD wVersionRequested, LPWSADATA lpWSAData )；wVersionRequested
⑴ wVersionRequested：一個WORD（雙位元組）型數值，在最高版本的Windows Sockets支持調用者使用，高階位元組指定小版本(修訂本)號,低位位元組指定主版本號。
⑵lpWSAData 指向WSADATA數據結構的指針，用來接收Windows Sockets
實現的細節。
WindowsSockets API提供的調用方可使用的最高版本號。高位位元組指出副版本(修正)號，低位位元組指明主版本號。
注釋
本函式必須是應用程式或DLL調用的第一個Windows Sockets函式。它允許應用程式或DLL指明Windows Sockets API的版本號及獲得特定Windows Sockets實現的細節。應用程式或DLL只能在一次成功的WSAStartup()調用之後才能調用進一步的Windows Sockets API函式。
為支持日後可能和Windows Sockets 1.1有功能上差異的Windows Sockets實現及應用程式，在WSAStartup()中規定了一個協定。WSAStartup()的調用方和Windows Sockets DLL互相通知對方它們可以支持的最高版本，並且互相確認對方的最高版本是可接受的。在WSAStartup()函式的入口，Windows Sockets DLL檢查了應用程式所需的版本。如果所需版本低於DLL支持的最高版本，則調用成功並且DLL在wHighVersion中返回它所支持的最高版本，在
wVersion中返回它的高版本和wVersionRequested中的較小者。然後Windows Sockets DLL就會假設應用程式將使用wVersion.如果WSDATA結構中的wVersion域對調用方來說不可接收，它就應調用WSACleanup()函式並且要么去另一個Windows Sockets DLL中搜尋，要么初始化失敗。
本協定允許Windows Sockets DLL和Windows Sockets應用程式共同支持一定範圍的Windows Sockets版本。如果版本範圍有重疊，應用程式就可以成功地使用Windows Sockets DLL。下列的圖表給出了WSAStartup()在不同的應用程式和Windows Sockets DLL版本中是如何工作的：
應用程式版本 DLL版本 wVersionRequested wVersion wHighVersion 最終結果
1.1 1.1 1.1 1.1 1.1 use 1.1
1.0 1.1 1.0 1.1 1.0 1.0 use 1.0
1.0 1.0 1.1 1.0 1.0 1.1 use 1.0
1.1 1.0 1.1 1.1 1.1 1.1 use 1.1
1.1 1.0 1.1 1.0 1.0 失敗
1.0 1.1 1.0 －- －- WSAVERNOTSUPPORTED
1.0 1.1 1.0 1.1 1.1 1.1 1.1 use 1.1
1.1 2.0 1.1 2.0 1.1 1.1 use 1.1
2.0 1.1 2.0 1.1 1.1 失敗
下列代碼段給出了只支持Windows Sockets 1.1版本的應用程式是如何進行WSAStartup()調用的：
WORD wVersionRequested;
WSADATA wsaData;
int err;
wVersionRequested =MAKEWORD( 1, 1 );
err = WSAStartup( wVersionRequested, &wsaData );
if ( err != 0 ) {
/* Tell the user that we couldn't find a useable */
/* winsock.dll. */
return;
}
/* Confirm that the Windows Sockets DLL supports 1.1.*/
/* Note that if the DLL supports versions greater */
/* than 1.1 in addition to 1.1, it will still return */
/* 1.1 in wVersion since that is the version we */
/* requested. */
if ( LOBYTE( wsaData.wVersion ) != 1 ||
HIBYTE( wsaData.wVersion ) != 1 ) {
/* Tell the user that we couldn't find a useable */
/* winsock.dll. */
WSACleanup( );
return;
}
/* The Windows Sockets DLL is acceptable. Proceed. */
下面的代碼段示例了只支持1.1版的Windows Sockets DLL是如何進行WSAStartup()協商的：
/* Make sure that the version requested is >= 1.1. */
/* The low byte is the major version and the high */
/* byte is the minor version. */
if ( LOBYTE( wVersionRequested ) < 1 ||
( LOBYTE( wVersionRequested ) == 1 &&
HIBYTE( wVersionRequested ) < 1 ) {
return WSAVERNOTSUPPORTED;
}
/* Since we only support 1.1, set both wVersion and */
/* wHighVersion to 1.1. */
lpWsaData->wVersion = MAKEWORD( 1, 1 );
lpWsaData->wHighVersion = MAKEWORD( 1, 1 );
一旦應用程式或DLL進行了一次成功的WSAStartup()調用，它就可以繼續進行其它所需的Windows Sockets API調用。當它完成了使用該Windows Sockets DLL的服務後，應用程式或DLL必須調用WSACleanup()以允許Windows Sockets DLL釋放任何該應用程式的資源。
實際的Windows Sockets實現細節在WSAData結構中描述如下:
struct WSAData {
WORD wVersion;
WORD wHighVersion;
char
szDescription[WSADESCRIPTION_LEN+1];
char szSystemStatus[WSASYSSTATUS_LEN+1];
unsigned short iMaxSockets;
unsigned short iMaxUdpDg;
char FAR * lpVendorInfo;
};
返回值
0 成功。
否則返回下列的錯誤代碼之一。注意通常依靠應用程式調用WSAGetLastError()機制獲得的錯誤代碼是不能使用的，因為Windows Sockets DLL可能沒有建立“上一錯誤”信息儲存的客戶數據區域。
關於Windows Sockets提供者的說明：
每一個Windows Sockets應用程式必須在進行其它Windows Sockets API調用前進行WSAStartup()調用。這樣，本函式就可以用於初始化的目的。
進一步的說明在WSACleanup()的說明中有討論。
錯誤代碼
WSASYSNOTREADY 指出網路通信依賴的網路子系統還沒有準備好。
WSAVERNOTSUPPORTED 所需的Windows Sockets API的版本未由特定的Windows Sockets實現提供。
WSAEINVAL 應用程式指出的Windows Sockets版本不被該DLL支持。
