Winsock Initialisation and Termination

In one of my earlier articles I wrote about how to get your computer's name and IP address.

Unfortunately what I didn't fully cover was how to initialise WinSock in the first place. Although the example app I made available for download did call all the relevant functions I didn't explicitly mention them in my article, which has led to some confusion.  Hopefully this will rectify that problem.

Initialisation

To initialise Winsock you need to call the WSAStartup() function. 

Map
 Module('WINSOCK.LIB')
  WSAStartup(Word,Long),Long,Pascal,Name('WSASTARTUP'),DLL(dll_mode)
 End
End
WSADescription_Len  Equate(256)
WSASYS_Status_Len   Equate(128)

WSAData             Group,Type
wVersion            	Short
wHighVersion        	Short
szDescription        CString(WSADESCRIPTION_LEN+1)
szSystemStatus       CString(WSASYS_STATUS_LEN+1)
iMaxSockets          UShort
iMaxUdpDg            UShort
lpVendorInfo         CString(30)
                    End
WSD	               Like(WSAData)                    
Code
If WSAStartup(257,Address(WSD)) = 0
 ! Everything worked OK
End

The first parameter is the highest version of Winsock that you can use, with each byte of the word being the major and minor version number.  The only problem is that the bytes are reversed in order - the high-order byte specifies the minor version (revision) number and the low-order byte specifies the major version number.

So, to initialise an application to support Winsock 1.1 you'd use a value of 257 ( 0000000100000001 binary).  For Winsock 2.2 you'd use 514 ( 0000001000000010 binary).

The second parameter is a pointer to a WSAData structure.  The WSAData structure, defined above, returns information about the Winsock implementation. If you're concerned about whose WINSOCK.DLL you're using then you can look at the fields in the WSAData structure to identify the provider.

The return value indicates whether it worked ( a value of 0 ) or it didn't.  If Winsock failed to initialise you can call WSAGetLastError to work out why.

Termination

Once you've completed your Winsock API calls and your program is ready to exit you need to shut down the Winsock library.  You do this by calling the WSACleanup() function. It doesn't take any parameters and the return value indicates whether it succeeded (0) or not (not 0). As before, if it failed to terminate properly you can call WSAGetLastError to work out why.

Map
 Module('WINSOCK.LIB')
  WSACleanup(),Long,Pascal,Name('WSACLEANUP'),DLL(dll_mode)
 End
End 

Linking

In order for your application to link correctly you need to add WINSOCK.LIB or WS2_32.LIB to your project file, depending on whether you're using Winsock 1.x or Winsock 2.x.  You'll probably need to run the Clarion LIBMAKER utility to make a Clarion-supported .LIB file to link against.

Back to the home page