The Pascal compiler company

• Pascal Compiler
• Web Programming
• About Irie Tools

The WSAStartUp Function

Description

The WSAStartUp function initializes the WinSock2 library for use by your program, and must be the first WinSock2 library function called by your program. Calling the WSAStartUp function serves two major purposes:

• The first purpose is to load the DLL that implements the WinSock2 library (i.e. Ws2_32.dll). NOTE: The other WinSock2 library functions expect the WinSock2 library DLL to be loaded before they are called.
• The second purpose for calling the WSAStartUp function is to establish what version of the Windows Sockets API your program should use.

Declaration

The system include file WinSock2.inc contains the following declaration for the WSAStartUp function:

function WSAStartup(wVersionRequested : shortword; var lpWSAData : WSADATA) : integer;
  external dll='ws2_32.dll';

Arguments

The First Argument

The first argument passed to the WSAStartUp function is an expression of shortword type. This argument indicates the highest version of the Windows Sockets API that your program can support. Bits 0 through 7 (i.e. the least significant byte) specify the major version number of the API. Bits 8 through 15 (i.e. the most significant byte) specify the minor version number of the API. So to specify that the highest Windows Socket API version, that your program can support, is 2.1, you could use 2+1*256, or $0102, or just 258 as the value of this argument.

The Second Argument

The second argument passed to the WSAStartUp function, is a reference to a variable of type WSADATA. This argument is used by the WSAStartUp function to pass information back to your program. NOTE: The WSADATA type is declared in the system include file WinSock2.inc, as a record type, with the following important fields:

1. wVersion, contains the version of the Windows Sockets API that your program should use (the least significant byte contains the major version number, and the most significant byte contains the minor version number).
2. wHighVersion, contains the highest version of the Windows Sockets API that can be supported by the WinSock2 library DLL (the layout of this field is the same as the layout of the first field).
3. szDescription, contains a description of the Windows Sockets API implementation.
4. szSystemStatus, contains status or configuration information that might be useful to the user or the support staff (this field may be empty).

Return Values

The WSAStartUp function returns a value of integer type that indicates whether the call was successful. A value of zero means that the call succeeded. A non-zero value is an error code that indicates the reason why the call failed.

Sample Program

The sample program below illustrates how to call the WSAStartUp and WSACleanUp functions.

(*$I winsock2.inc *)
program start(output);
var
 data : WSADATA;
 iRet : integer;
begin
 iRet := WSAStartUp($0202, data);
 if iRet <> 0 then
  begin
   writeln('WSAStartUp call failed. Return Code=', iRet);
   halt;
  end;
 writeln('WSAStartUp call succeeded.');
 writeln('Version: $', hex(data.wVersion));
 writeln('High Version: $', hex(data.wHighVersion));
 writeln('Description: ', data.szDescription);
 writeln('System Status: ', data.szSystemStatus);
 iRet := WSACleanUp
end.

Reference Information

The authoritative source of information about the WinSock2 library is the Microsoft Developers Network (MSDN). You can access the MSDN on the Microsoft website at msdn.microsoft.com.