Winsock API: WSAStartup

参考MSDN：http://msdn.microsoft.com/en-us/library/windows/desktop/ms742213%28v=vs.85%29.aspx

The WSAStartup function initiates use of the Winsock DLL by a process.

Syntax

int WSAStartup(
  _In_   WORD wVersionRequested,
  _Out_  LPWSADATA lpWSAData
);

Parameters

wVersionRequested [in]

The highest version of Windows Sockets specification that the caller can use. The high-order byte specifies the minor version number; the low-order byte specifies the major version number.

lpWSAData [out]

A pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.

 

Return value

If successful, the WSAStartup function returns zero. Otherwise, it returns one of the error codes listed below.

The WSAStartup function directly returns the extended error code in the return value for this function. A call to the WSAGetLastError function is not needed and should  not be used.

Remarks

The WSAStartup function must be the first Windows Sockets function called by an application or DLL. It allows an application or DLL to specify the version of Windows Sockets required and retrieve details of the specific Windows Sockets implementation. The application or DLL can only issue further Windows Sockets functions after successfully calling WSAStartup.

 

Examples

The following code fragment demonstrates how an application that supports only version 2.2 of Windows Sockets makes a WSAStartup call:

#define WIN32_LEAN_AND_MEAN

#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")


int __cdecl main()
{

    WORD wVersionRequested;
    WSADATA wsaData;
    int err;

/* Use the MAKEWORD(lowbyte, highbyte) macro declared in Windef.h */
    wVersionRequested = MAKEWORD(2, 2);

    err = WSAStartup(wVersionRequested, &wsaData);
    if (err != 0) {
        /* Tell the user that we could not find a usable */
        /* Winsock DLL.                                  */
        printf("WSAStartup failed with error: %d\n", err);
        return 1;
    }

/* Confirm that the WinSock DLL supports 2.2.*/
/* Note that if the DLL supports versions greater    */
/* than 2.2 in addition to 2.2, it will still return */
/* 2.2 in wVersion since that is the version we      */
/* requested.                                        */

    if (LOBYTE(wsaData.wVersion) != 2 || HIBYTE(wsaData.wVersion) != 2) {
        /* Tell the user that we could not find a usable */
        /* WinSock DLL.                                  */
        printf("Could not find a usable version of Winsock.dll\n");
        WSACleanup();
        return 1;
    }
    else
        printf("The Winsock 2.2 dll was found okay\n");
        

/* The Winsock DLL is acceptable. Proceed to use it. */

/* Add network programming using Winsock here */

/* then call WSACleanup when done using the Winsock dll */
    
    WSACleanup();

}

 

Requirements：

Header	Winsock2.h
Library	Ws2_32.lib
DLL	Ws2_32.dll

If you want to use WSAStartup, remember to ..

use the following libraries in the EXACT order:

#include "stdafx.h" // needs to be the first of all if you use pre-compiled headers
#include "winsock2.h" // library for WSAStartup
#include "windows.h" // .. and then all the rest

 

生词注释：

 

  initiate   －  简明英汉词典

D.J.[iˈniʃieit]
vt.
1．  开始, 着手
2．  传授; 使初步了解
3．  接纳新成员, 让…加入

 

 

 

 

 

  the rest   －  简明英汉词典

n. 其余者

 

 

中文说明：

每个Winsock应用都必须加载Winsock DLL的相应版本。如果调用Winsock之前，没有加载
Winsock库，这个函数就会返回一个SOCKET_ERROR，错误信息是WSANOTINITIALISED。
加载Winsock库是通过调用WSAStartup函数实现的。这个函数的定义如下：
int WSAStartup ( WORD wVersionRequested, LPWSADATA lpWSAData )；
wVersionRequested：用于指定准备加载的Winsock库的版本。
  高位字节指定所需要的Winsock库的副版本，而低位字节则是主版本。
  可用宏MAKEWORD ( X , Y )（其中，x是高位字节，y是低位字节）方便地获得wVersionRequested的正确值。
lpWSAData：指向WSADATA数据结构的指针，用来接受Windows Sockets实现的细节。
            typedef struct WSAData {
                    WORD                    wVersion;     //打算使用的Winsock版本
                    WORD                    wHighVersion; //现有的Winsock库的最高版本
                    char                    szDescription[WSADESCRIPTION_LEN+1]; //没有用
                    char                    szSystemStatus[WSASYS_STATUS_LEN+1]; //没有用
                    unsigned short          iMaxSockets;  //没有用
                    unsigned short          iMaxUdpDg;    //没有用
                    char FAR *              lpVendorInfo; //没有用
            } WSADATA, FAR * LPWSADATA;
返回值
0：成功

注：各windows平台支持的Winsock版本
        平 台   Winsock版本
        Windows 95 1 . 1（2 . 2）
        Windows 98 2 . 2
        Windows NT 4.0 2 . 2
        Windows 2000 2 . 2
        Windows CE 1 . 1