---------------------------------------------------
 WINSOCKX.LIB: WinSock subroutine library (static)
---------------------------------------------------

We describe each routine in this library in Chapter 7, "Sample
Application and Library," of in _Windows Sockets Network 
Programming_  by Bob Quinn and Dave Shute (published by Addison-
Wesley, Reading, MA ISBN: 0-201-63372-8).  Many of the WinSock 
samples use the subroutines in this library. For example, the error 
message box, the routine to retrieve the local host's IP address, 
a simple hostname or IP address string parser, and others.

What it does: The WINSOCKX static library contains a number of
 routines commonly used by WinSock applications. Some are non-network
 functions that perform common mundane application operations--such as
 centering a window, or creating a local file--but most of the
 functions in this library provide high-level WinSock services by
 combining a number of WinSock function calls. For example, you can
 pass either a host name or IP address string to our GetAddr()
 function, and it returns an IP address in network order (it uses
 inet_addr() and gethostbyname() WinSock functions).

What it illustrates: In effect, these reusable functions show how to
 write simpler and more robust WinSock application code by using
 high-level functions.

How to Use it: Here are the function prototypes of the most
 significant and useful routines, along with a short description of
 each:

int CloseConn (SOCKET hSock, LPSTR achInBuf, int len, HWND hWnd);</CODE> 
 This is the standard TCP close routine: shutdown(how=1), recv()
 loop, then closesocket().

u_long GetAddr (LPSTR szHost);
 The GetAddr() function takes either a host name or IP address
 string in standard Internet dot-notation, and returns a network
 addrss in network order.

int GetBuf (SOCKET hSock, int nBigBufSize, int nOptVal);
 This uses SO_RCVBUF or SO_SNDBUF to get largest buffer possible
 up to the upper limit set by nBigBufSize. Returns buffer
 size retreived from getsockopt() upon return on success, or SOCKET_ERROR
 on failure.

LONG GetHostID (void); 
 This uses gethostname(), then gethostbyname() to try to retrieve
 the local IP address, and if this fails it then gets a UDP socket,
 connects it, and uses getsockname() to retrieve the local IP address,
 before closing the socket.

u_short GetPort (LPSTR szService); 
 This function is analogous to our GetAddr(), but takes either
 a service name or port number string, and returns a port number
 in network order.

int WSAErrStr (int WSAErr, LPSTR lpErrBuf);
 WSAErrStr() takes a WinSock error value as an input argument,
 and returns a short error description in the buffer provided.

void WSAperror (int WSAErr, LPSTR szFuncName);
 This function displays a message box that indicates "szFuncName
 failed," displays the macro name for the WSAErr value,
 along with a short description of the error.

Known Problems: No known problems.

File List: 
 WINSOCKX\GLOBALS.C global variables 
 WINSOCKX\WIN_MGR.C (non-network related) windows routines 
 WINSOCKX\WINSOCKX.MAK Makefile for 16-bit winsockx.lib 
 WINSOCKX\WSOCK32X.MAK Makefile for 32-bit wsock32x.lib 
 WINSOCKX\WSA_ERR.C error routines 
 WINSOCKX\WSA_OPTN.C socket option routines 
 WINSOCKX\WSA_ADDR.C address routines

--------
 NOTES:
--------

We used Microsoft Visual C++ enviroments (versions 1.52 for 16-bit,
and version 2.1 for 32-bit) to create most of the makefiles.
Unfortunately, because the paths are hard-coded in the file, you will
have to bring the project files (.mak) into the respective MS C++
environments to readjust things to the new directory, and even then
you will have to manually alter the project to access the library
files (the are in the root of the directory where you install the
samples).

All samples--including the sample DLL and static library--have a
number of other things in common:

  - They all have 32-bit versions, and all 32-bit version names
     end with "32" (16-bit versions don't have a number).
  - They use the WSAperror() function from #WINSOCKX">WINSOCKX.LIB
    to display error values and short descriptions when an unexpected
    error occurs.
  - They display error messages on any suspicious error condition.
     They don't hide errors, but report them whenever they occur. As
     we describe n a_c.htm">Appendix C: WinSock Error Reference,
     these error messages should appear only when a "user fixable
     error" occurs. If you get an error message from a sample
     application for a non user-fixable error, then this may
     indicate an anomoly in the WinSock implementation that your applications
     may need to deal with. We show you the errors on purpose, to make
     you aware of unexpected conditions.
  - They have a minimal user interface, and do not have help (.HLP)
     files available.
  - They are meant to be played with. They are for exploration
     and experimentation as well as to illustrate how to write WinSock
     applications.

The icons used for each sample don't mean much, but they meet
the following three criteria:

    - They each contain the socket from the official WinSock icon.
    - Each one is colorful in its own unique and wonderful way.
    - Each took under 10 minutes to create.
