Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function WSAStartup Lib "wsock32.dll" (ByVal wVersionRequested As Integer, lpWSAData As WSADATA) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

WSAStartup initializes the use of Windows Sockets (Winsock) for the calling program. This function must be called before any other Winsock functions are called, in order to perform any necessary initialization. The program can specify which version of Winsock it wants to use. When your program no longer needs to call Winsock function, it must call WSACleanup to free resources.

Return Value

If successful, the function returns zero. If an error occured, the function returns one of the following one of the following values specifying the error:

WSAEFAULT: A valid WSADATA structure was not passed for lpWSAData.
WSAEINPROGRESS: A Winsock 1.1 blocking operation is in progress.
WSAEPROCLIM: The limit of the number of tasks supported by the Winsock implementation has been reached.
WSASYSNOTREADY: The network subsystem is not ready for network communication.
WSAVERNOTSUPPORTED: The requested version of Winsock is not provided by the current Winsock implementation

Visual Basic-Specific Issues

None.

Parameters

wVersionRequested: The highest version of Winsock your program can use. If you wish, your program could specify a lower version than 2.2. The low-order byte contains the major version number, and the high-order byte contains the minor version number. In other words, &H202 means Winsock 2.2 and &H2 means Winsock 2.0.
lpWSAData: Receives information about the current Winsock implementation.

Constant Definitions

Const WSAEFAULT = 10014 Const WSAEINPROGRESS = 10036 Const WSAEPROCLIM = 10067 Const WSASYSNOTREADY = 10091 Const WSAVERNOTSUPPORTED = 10092

Example

Print the IP address associated with a domain name specified by the user. Winsock is briefly used to resolve the domain name and format a printable IP address string. The user enters the domain name to resolve in text box txtDomain, and the domain name is resolved when the user clicks button cmdGetIP.

To run this example, place a text box named txtDomain and a command button named cmdGetIP on a form window.

' This code is licensed according to the terms and conditions listed here. ' Declarations and such needed for the example: ' (Copy them to the (declarations) section of a module.) Public Type WSADATA wVersion As Integer wHighVersion As Integer szDescription As String * 257 szSystemStatus As String * 129 iMaxSockets As Long iMaxUdpDg As Long lpVendorInfo As Long End Type Public Declare Function WSAStartup Lib "wsock32.dll" (ByVal wVersionRequested As Integer, lpWSAData _ As WSADATA) As Long Public Declare Function WSACleanup Lib "wsock32.dll" () As Long Public Type HOSTENT h_name As Long h_aliases As Long h_addrtype As Integer h_length As Integer h_addr_list As Long End Type Public Const AF_INET = 2 Public Declare Function gethostbyname Lib "wsock32.dll" (ByVal name As String) As Long Public Declare Function inet_ntoa Lib "wsock32.dll" (ByVal inaddr As Long) As Long Public Declare Sub CopyMemory Lib "kernel32.dll" Alias "RtlMoveMemory" (Destination As Any, Source _ As Any, ByVal length As Long) Public Declare Function lstrlen Lib "kernel32.dll" Alias "lstrlenA" (ByVal lpString As Any) As Long Public Declare Function lstrcpy Lib "kernel32.dll" Alias "lstrcpyA" (ByVal lpString1 As Any, ByVal _ lpString2 As Any) As Long ' Define some useful API macros. Public Function MAKEWORD(ByVal bLow As Byte, ByVal bHigh As Byte) As Integer MAKEWORD = Val("&H" & Right("00" & Hex(bHigh), 2) & Right("00" & Hex(bLow), 2)) End Function Public Function LOBYTE(ByVal wValue As Integer) As Byte LOBYTE = Val("&H" & Right("00" & Hex(wValue), 2)) End Function Public Function HIBYTE(ByVal wValue As Integer) As Byte HIBYTE = Val("&H" & Left(Right("0000" & Hex(wValue), 4), 2)) End Function ' *** Place the following code inside the form window. *** Private Sub cmdGetIP_Click() Dim sockinfo As WSADATA ' information about Winsock Dim hostinfo As HOSTENT ' information about an Internet host Dim pHostinfo As Long ' pointer to a HOSTENT structure Dim pIPAddress As Long ' pointer to an IP address dword Dim ipAddress As Long ' an IP address, packed into a dword Dim pIPString As Long ' pointer to an IP address formatted as a string Dim ipString As String ' holds a human-readable IP address string Dim retval As Long ' generic return value ' Open up a Winsock session, using version 2.2. retval = WSAStartup(MAKEWORD(2, 2), sockinfo) If retval <> 0 Then Debug.Print "ERROR: Attempt to open Winsock failed: error"; retval Exit Sub End If ' Display the version of Winsock being used, and the description ' provided by the implementation (after removing the empty space). Debug.Print "Using Winsock version"; LOBYTE(sockinfo.wVersion); "."; HIBYTE(sockinfo.wVersion) Debug.Print "Description: "; Left(sockinfo.szDescription, _ InStr(sockinfo.szDescription, vbNullChar) - 1) ' Get information about the domain specified in txtDomain. pHostinfo = gethostbyname(txtDomain.Text) If pHostinfo = 0 Then Debug.Print "Unable to resolve domain name." Else ' Copy the data into a HOSTENT structure. CopyMemory hostinfo, ByVal pHostinfo, Len(hostinfo) If hostinfo.h_addrtype <> AF_INET Then Debug.Print "A non-IP address was returned." Else ' Copy the pointer to the first (and probably only) IP address in the structure. CopyMemory pIPAddress, ByVal hostinfo.h_addr_list, 4 ' Copy the actual IP address. CopyMemory ipAddress, ByVal pIPAddress, 4 ' Convert the IP address into a human-readable string. pIPString = inet_ntoa(ipAddress) ' Copy the result into a string variable. ipString = Space(lstrlen(pIPString)) retval = lstrcpy(ipString, pIPString) ' Print the result: a human-readable IP address. Debug.Print ipString End If End If ' Close the Winsock session. retval = WSACleanup() End Sub