Foxtools – WinSockLib _WSOCKSTARTUP()

Version: 1.00.00 - last Update: Tuesday, October 01, 2009, 23:45:00

---

Foxtools WinSock Library Functions

_WSOCKSTARTUP

_WSockStartUp() is the first of three Foxtools functions that were added by Calvin Hsia. _WSockStartUp() initializes the Winsock library.

Call _WSockStartUp() and _WSockCleanUp() to initialize/uninitialize the Winsock library.
The _WSockGetHostByAddr() function finally takes an IP address string like "123.123.123.123" and resolves it into the name of the machine.

_WSockStartUp() wraps the Windows Socket function WSAStartup() <<< go there to find out the details!
The [out] parameters of the Foxtools function are mapping to the corresponding members of the C++ structure called WSData.

The following part is "borrowed” from Microsoft’s msdn Winsock Reference:

typedef struct WSAData {
   WORD wVersion;
   WORD wHighVersion;
   char szDescription[WSADESCRIPTION_LEN+1];
   char szSystemStatus[WSASYS_STATUS_LEN+1];
   unsigned short iMaxSockets;
   unsigned short iMaxUdpDg;
   char FAR * lpVendorInfo;
}WSADATA, *LPWSADATA;

Members

wVersion

The version of the Windows Sockets specification that the Ws2_32.dll expects the caller to use. The high-order byte specifies the minor version number; the low-order byte specifies the major version number.

wHighVersion

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

This is the same value as the wVersion member when the version requested in the wVersionRequested parameter passed to the WSAStartup function is the highest version of the Windows Sockets specification that the Ws2_32.dll can support.

szDescription

A NULL-terminated ASCII string into which the Ws2_32.dll copies a description of the Windows Sockets implementation. The text (up to 256 characters in length) can contain any characters except control and formatting characters. The most likely use that an application would have for this member is to display it (possibly truncated) in a status message.

szSystemStatus

A NULL-terminated ASCII string into which the Ws2_32.dll copies relevant status or configuration information. The Ws2_32.dll should use this parameter only if the information might be useful to the user or support staff. This member should not be considered as an extension of the szDescription parameter.

iMaxSockets

The maximum number of sockets that may be opened. This member should be ignored for Windows Sockets version 2 and later.

The iMaxSockets member is retained for compatibility with Windows Sockets specification 1.1, but should not be used when developing new applications. No single value can be appropriate for all underlying service providers. The architecture of Windows Sockets changed in version 2 to support multiple providers, and the WSADATA structure no longer applies to a single vendor's stack.

iMaxUdpDg

The maximum datagram message size. This member is ignored for Windows Sockets version 2 and later.

The iMaxUdpDg member is retained for compatibility with Windows Sockets specification 1.1, but should not be used when developing new applications. The architecture of Windows Sockets changed in version 2 to support multiple providers, and the WSADATA structure no longer applies to a single vendor's stack. For the actual maximum message size specific to a particular Windows Sockets service provider and socket type, applications should use getsockopt to retrieve the value of option SO_MAX_MSG_SIZE after a socket has been created.

I dropped the description of the last member (lpVendorInfo), coz it is not returned by the Foxtools implementation.

VFP Syntax

iSuccess = _WSockStartUp(m.iRequestedVersion, @wVersion, @wHighVersion, @szDescription, @szSystemStatus, @iMaxSockets, @iMaxUdpDg)

Parameters

[in] iRequestedVersion

The requested version number of Winsock compliance in the form of a 16 bit integer. This information is stored in a high byte/low byte order. In his article, Calvin Hsia uses 256 * 1 + 1 (2.1) for this parameter.

[out] wVersion

The level of compliance that is supported. Most often, this will be equal to the value of <iRequestedVersion>. The value returned is in the same format as called.

[out] wHighVersion

This is the highest version of the Winsock specification that the caller can use.

[out] szDescription and [out] szSystemStatus

Theses character strings represent the information returned in the szDescription and szSystemStatus members of the WSADATA structure.
szDescription contains a description of the implementation. szSystemStatus holds the system status which should read “running”.

[out] iMaxSockets and [out] iMaxUdpDg

These parameters represent the maximum number of sockets available and maximum datagram message size. These members are ignored for Windows Sockets version 2 and later. See description above.

Remarks

The current version of the Windows Sockets specification is version 2.2. The current Winsock DLL, Ws2_32.dll, supports applications that request any of the following versions of Windows Sockets specification:

• 1.0
• 1.1
• 2.0
• 2.1
• 2.2

VFP Example(s)

Setting the desired version can be accomplished with the following:

iMajorVersion = 2
iMinorVersion = 2
iRequestedVersion = BITLSHIFT(m.iMajorVersion, 8)
iRequestedVersion = m.iRequestedVersion + m.iMinorVersion
*\\ Where <iMajorVersion> is equal to the major version number, 
*\\ and <iMinorVersion> is equal to the minor version number. 
*\\ Retrieving the available version is a simple reverse process:
iMinorVersion = BITAND(m.iRequestedVersion, 255)
iMajorVersion = BITAND(BITRSHIFT(m.iRequestedVersion, 8), 255) 

Calling the _WSockStartUp() function can be accomplished with the following:

STORE 0 to buff1, buff2, buff3, buff4, buff5, buff6
IF _WSockStartUp(256 + 1, @buff1, @buff2, @buff3, @buff4, @buff5, @buff6) = 0 
   *\\ use your local IP address here
   IF _WSockGetHostByAddr("192.168.100.12", @buff1) = 1 
      ? m.buff1 
   ELSE 
      Error “_WSockGetHostByAddr error”
   ENDIF 
   = _WSockCleanUp()
ENDIF

---