Winsock Interface Library for C/C++ (WIL4C) USERS MANUAL Version 1.0 July 28, 1997 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1997 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 205-881-4630 FAX : 205|880|0925 BBS : 205-880-9748 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER WIL4C Users Manual Page 1 C O N T E N T S Chapter Page 1.0 Introduction................................................3 1.1 User Support............................................4 1.2 ASP Ombudsman...........................................4 1.3 Installation............................................5 1.4 Consulting Services.....................................5 2.0 Library Organization........................................6 2.1 Dynamic Link Libraries..................................6 2.2 Using the Library.......................................6 2.3 Compiling Programs......................................6 2.4 Using a MAKEFILE........................................6 2.5 Using an IDE............................................7 2.6 Compiling WIL4C.........................................9 2.7 Compiling Example Programs..............................9 3.0 Internet Programming.......................................10 3.1 Internet RFCs..........................................10 3.2 Protocol Layers........................................11 3.3 The Internet Protocol (IP).............................11 3.4 Socket Concepts........................................12 3.5 Client and Server Programming..........................14 3.6 Stream (TCP) Programming...............................14 3.7 Windows Winsock Programming............................14 3.8 Synchronous VS Asynchronous Programming................15 3.9 The ASYNC Functions....................................16 4.0 Internet Protocols.........................................20 4.1 Finger Protocol........................................20 4.2 SMTP Protocol..........................................21 4.3 POP3 Protocol..........................................23 4.4 NNTP Protocol..........................................25 4.5 FTP Protocol...........................................28 4.6 HTTP Protocol..........................................31 5.0 Problems...................................................33 6.0 Example Programs...........................................34 6.1 HOST...................................................34 6.2 SFINGR, AFINGER, and FINGER............................34 6.3 FROM...................................................34 6.4 MAIL...................................................35 6.5 FTP....................................................35 6.6 NEWS...................................................36 6.7 VIEW...................................................36 6.8 WHO_C and WHO_S........................................37 6.9 BCAST..................................................37 7.0 Legal Issues...............................................38 7.1 Registration...........................................38 7.2 License................................................39 7.3 Warranty...............................................39 8.0 Summary....................................................40 8.1 Revision History.......................................40 8.2 WIL Function Summary...................................40 9.0 Other MarshallSoft Computing Products......................42 WIL4C Users Manual Page 2 1.0 Introduction The Winsock Interface Library for C/C++ (WIL4C) is a function library that simplifies Winsock programming and provides support for the most common Internet protocols such as DNS (Domain Name System), Finger, SMTP (Simple Mail Transport Protocol), POP3 (Post Office Protocol Version 3), FTP (File Transfer Protocol), NNTP (Network News Transport Protocol), and HTTP (Hypertext Transfer Protocol). Winsock network programming is not easy. Because of this, the primary purpose in designing WIL was to simplify Winsock programming. Winsock simplification is accomplished by: (1) Handling details like converting from host byte order to network byte order (and vice versa) as necessary automatically. (2) Handling the creation and manipulation of winsock data structures automatically. (3) Proving a straight forward interface, using only necessary arguments. (4) Providing more powerful functions, which may perform multiple Winsock functions. The WIL can be called from any program capable of calling Windows API functions, such as Delphi and Visual Basic. Support for the most common Internet protocols is provided by the ASYNC.C functions, which can transmit commands and receive responses formatted as used by these protocols. Lastly, a good selection of example programs are provided, covering the major Internet protocols. The example programs are designed to demonstrate how to use the WIL library functions. One of the best ways to learn Winsock programming is to study these examples. The shareware and registered versions are identical except for two differences: (1) the shareware version displays the "shareware" screen, and (2) the shareware version will "time out" after 20 minutes, limiting execution to a maximum of twenty minutes EACH time a program is run. Of course, the registered version does not display the shareware screen nor time out after twenty minutes. We apologize for the inconvenience of the twenty minute timeout. Please contact us if more time is needed in order to evaluate WIL4C. WIL4C Users Manual Page 3 1.1 User Support We want you to be successful in developing your applications using WIL4C! We depend upon our customers to let us know what they need in a winsock communications library. This means we are committed to providing the best library that we can. If you have any suggestions or comments, please let us know. If you are having a problem using WIL4C, call us at 205-881-4630 between 1:30 PM and 9:30 PM CST Monday through Friday. You can also call at other times and leave a message, and call back later for a reply. However, we can only answer questions with respect to using the WIL4C library or our example programs. We cannot help you program your application. See section 1.4 "Consulting Services". If you are on the Internet, email us at info@marshallsoft.com. You can also get the latest versions of our products from our anonymous ftp site: FTP: ftp.marshallsoft.com PATH: marshallsoft The MarshallSoft Computing, Inc. newsletter "Comm Talk" is published quarterly. It discusses various communications problems and solutions using WIL4C as well as related information. The latest copy of our newsletter can be found on our anonymous ftp site (directory /marshallsoft/other) as well as our web site. Web site: www.marshallsoft.com Our FTP site can also be accessed from our Web site. 1.2 ASP Ombudsman MarshallSoft Computing, Inc. is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI USA 49442-9427, Fax 616-788-2765, or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536. WIL4C Users Manual Page 4 1.3 Installation (1) Before installation of WIL4C, your Windows C/C++ compiler should already be installed on your system and tested. In particular, include command line tools when installing your compiler. (2) Make a backup copy of your distribution disk. Put your original distribution disk in a safe place. (3) Exit Windows into DOS, or start a DOS window: (4) Create your WIL project directory, copy the WIL archive, then unzip the archive. For example: MKDIR WIL PKUNZIP WIL4C10.ZIP WIL (5) Use the provided install batch file (INSTALL) to install the library. The format is: INSTALL where must be "MS" for Microsoft, "BC" for Borland, or "WC" for Watcom. INSTALL performs the following copy operations: Microsoft: COPY WIL32M.LIB WIL32.LIB COPY WIL32M.DLL WIL32.DLL Borland: COPY WIL32B.LIB WIL32.LIB COPY WIL32B.DLL WIL32.DLL Watcom: COPY WIL32W.LIB WIL32.LIB COPY WIL32W.DLL WIL32.DLL WIL16.DLL is common for all of the supported compilers. 1.4 Consulting Services We offer consulting services at $75 per hour, billed to your credit card in 10 minute increments. A work authorization letter must be signed and mailed or FAXed to us before we can start. Questions dealing with the use of our library or our example programs are covered as "support", for which there is no charge. Any other questions are considered consulting. WIL4C Users Manual Page 5 2.0 Library Overview 2.1 Dynamic Link Libraries WIL4C includes both Win16 [WIL16] and a Win32 [WIL32] dynamic link library (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library which is bound to each and every application that uses it at link time. Since WIL4C is a DLL, only one copy of the WIL4C code and data is loaded into memory regardless of the number of applications programs that use it. For example, more than one instance of the test program FINGER can be started. All copies of FINGER can run concurrently. 2.2 Using the Library The WIL4C has been tested on a Gateway 2000 (25 MHz 80386-DX, Windows 3.1), a Gateway 2000 (66 MHz 80486-DX2, Windows 3.1), a Mid-West Micro (150 MHz Pentium, Windows 95), and a Toshiba Satellite (100 MHz Pentium, Windows 95). WIL4C has also been tested with Microsoft Visual C/C++, Borland C/C++ (including C Builder), Turbo C/C++, and Watcom C/C++. 2.3 Compiling Programs The example programs can be compiled by using either the provided makefiles or creating a project file for the IDE. Separate makefiles are provide for Win16 and Win32. 16-bit makefile end with "16" while 32-bit makefiles end with "32". 2.4 Using a MAKEFILE Makefiles originated on UNIX systems. They are the standard way that C/C++ programs are constructed in command line environments. Windows programs can be constructed with makefiles running DOS using command line Windows compilers. Makefiles are provided for Microsoft, Borland, and WATCOM command line compilers. Makefiles have file extensions of "_M_" for Microsoft, "_B_" for Borland, and "_W_" for WATCOM. Thus, FINGER16._W_ is the Watcom Win16 makefile for FINGER and FINGER32._M_ is the Microsoft Win32 makefile. Turbo C/C++ for Windows and Borland C Builder do not support command line makefiles. Refer to MAKEFILE.TXT for more information on makefiles. WIL4C Users Manual Page 6 2.5 Using an IDE All current windows compilers have an Integrated Development Environment (IDE) for building application programs in the Windows environment. Since there is no standard format for IDE project files, file names must be entered into the IDE from the keyboard. Each example program has a project text file (e.g. FINGER.PRJ) which contains the list of filenames that must be entered into the IDE. We do not distribute IDE files in our package because (1) they are very large, (2) they are not always upwardly compatible with previous versions of a particular IDE, (3) there is no standard project file format between compiler manufactures, and (4) they often must be modified to provide the correct path names. However, creating a project file within the IDE is very easy. Each application has a project file . Each project file contains the filenames that must be entered into the IDE. For each IDE, you will have to enter these filenames into the IDE. This is usually done with the INS key except for the Microsoft Developer, which uses menu commands. Be careful to enter all filenames as listed in the ".PRJ" file. All of the example application programs have been built using IDEs from Microsoft, Borland, and Watcom. However, there are differences between IDE versions from the same compiler manufacturer. All of the IDEs use the concept of a file hierarchy. For example, the Finger file hierarchy in the IDE (for 32-bit) should look like: FINGER.EXE |-- ABOUT.C |-- ASYNC.C |-- FINGER.C |-- FINGER.DEF |-- FINGER.RC |-- PAINT.C |-- STR.C |-- WIL32.LIB Replace WIL32.LIB above with WIL16.LIB for 16-bit applications. The order of the files is not significant. 2.5.1 Microsoft IDE Choose "Project", then "New". Select Win16 [Win32] as the target. A dialog box will then pop up into which the project file names are entered. WIL4C Users Manual Page 7 2.5.2 Microsoft Developer Choose "File", then "New", then "Project Workspace". Select "Application" for "Type:" and your project name for "Name:". Choose Win16 or Win32 for platform. Then select "Create". Select "Insert", then "Files into Project". Add all filenames as listed in the ".PRJ" file corresponding to the project you are building. Lastly, select "Rebuild All". 2.5.3 Borland IDE Turn off LINKER case sensitivities: Choose "Options", "Projects", "Linker", "General". Turn off the "case sensitive link" and "case sensitive exports and imports" boxes. Next, choose "Project", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Select "GUI" for the "Target Model:" Only "Runtime" and "Dynamic" should be checked for "Standard Libraries:" NOTE1: If, after linking in the IDE, you get unresolved external references to the communications library functions in which each function name is all upper case, then you have NOT turned off case sensitivity as described above. NOTE2: If you get errors compiling the windows header file "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project", "Compiler", "Source". 2.5.4 Turbo C IDE Follow the same directions as above, except that the "Target Model:" can be any listed. 2.5.5 Borland C Builder Choose "File" / "Open Project" on the menu bar. Load BCB_PRJ.MAK. Then, choose "Build All" from "Project" to create the executable. 2.5.6 Watcom IDE Choose "File", then "New Project". Enter the project name and then choose Win16 [Win32] as the target. Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Select "Options" from the main window, then "C Compiler Switches", then "10". Memory Models and Processor Switches". Check "80386 Stack based calling [-3s]", then check "32-bit Flat model [-mf]". WIL4C Users Manual Page 8 2.6 Compiling WIL4C Precompiled DLL's are provided on disk for all the supported compilers. Registered users can recompile WIL.C in order to create WIL16.DLL and WIL32.DLL. Makefiles are provided for each compiler. For Microsoft C, type: NMAKE -f WIL16._M_ NMAKE -f WIL32._M_ For Borland C, type: MAKE -f WIL16._B_ MAKE -f WIL32._B_ For Watcom C, type: WMAKE -f WIL16._W_ WMAKE -f WIL32._W_ 2.7 Compiling Example Programs There are makefiles provided for each of the example programs. For example, to compile FINGER: For Microsoft C, type: NMAKE -f FINGER16._M_ NMAKE -f FINGER32._M_ For Borland C, type: MAKE -f FINGER16._B_ MAKE -f FINGER32._B_ For Watcom C, type: WMAKE -f FINGER16._W_ WMAKE -f FINGER32._W_ WIL.C can also be recompiled within the IDE. WIL4C Users Manual Page 9 3.0 Internet Network Programming It is assumed that the user of the WIL library is familiar with the Internet and programming, but not necessarily network programming. For more detailed information on the structure of the Internet, refer to one of the many excellent books on the subject. One of the best is Internetworking with TCP/IP, Volume I by Douglas E. Comer (Prentice Hall, ISBN 0-13-216987-8). One of the best ways to learn network programming is to study (and eventually modify) example code. For this reason, a good selection of program examples are provided. 3.1 Internet RFCs The various Internet standards are defined in "Requests for Comments", or RFCs. RFCs are text files, and are available on the Internet at ftp://ds.internic.net. The index of all RFC documents is found in file rfc-index.txt. Some important RFCs include: RFC 791 : The Internet Protocol (IP) RFC 821 : Simple Mail Transport Protocol (SMTP). RFC 822 : SMTP Message Format. RFC 959 : File Transfer Protocol (FTP). RFC 1036 : Network News Transport Protocol (NNTP). RFC 1288 : The Finger protocol. RFC 1460 : Post Office Protocol, Version 3 (POP3). RFC 1521 : Multipurpose Extensions Mail Extensions (MIME). RFC 2068 : Hypertext Transfer Protocol 1.1 (HTTP). The above is just a sampling of the thousands of RFCs. Anyone wanting to implement a particular protocol should download a copy of the appropriate RFCs from the Internic. In addition to RFCs, the Internic also publishes additional classes of documents: (1) Internet Drafts (ID). (2) For Your Information (FYI). (3) Standard RFCs (STD). These documents are also found at ftp://ds.internic.net. WIL4C Users Manual Page 10 3.2 Protocol Layers The internet protocol layers look like: +---------------------+ | Application Program | FINGER.C, MAIL.C, FTP.C, ... +-+-----+-------------+ | | | +-+-----------+ | | WIL Library | WIL16.DLL and WIL32.DLL | +-+-----------+ | | +-+-----+-----+ | WINSOCK DLL | WINSOCK.DLL and WSOCK32.DLL +-------+-----+ | +---------+ | | +-------+--+ +---+------+ | TCP code | | UDP code | (vendor specific) +--------+-+ ++---------+ | | +-+-----+-+ | IP code | +----+----+ | +-------+--------+ | Network Driver | +-------+--------+ | +-------+--------+ | LAN or PPP | +----------------+ Each of the example programs uses the WIL (Winsock Interface Library) to simplify access to the WINSOCK. 3.3 The Internet Protocol (IP) The Internet Protocol (IP) is the basis upon everthing else is built. It is documented in RFC 791. 3.3.1 Best Effort Delivery Internet Protocol (IP) provides a "best effort" in delivering IP packets. Packets may arrive out of order, or may not arrive at all. The TCP (Transport Control Protocol) and UDP (User Datagram Protocol) are built on top of IP and perform additional error detection and correction. WIL4C Users Manual Page 11 3.3.2 IP Addresses Each host computer is assigned an unique 32-bit internet address that is used for all internet communications. Thus, if you dial up your Internet Service Provider (ISP), you are assigned an IP address owned by the ISP which is used to uniquely identify you while you are connected. The IP address is often written as four 8-bit decimal octets (bytes) separated by decimal points. For example, the 32-bit hexidecimal number 12AF7B02 can be written as 18.175.123.2 The internet standard for byte ordering within an integer is "Big Endian" (most significant byte first) and is denoted as the "network byte order". The host byte order depends on the particular computer architecture. For Intel based PCs, the host byte ordering is "Little Endian" (least significant byte first). The WINSOCK provides functions to convert between them. The Winsock Inteface Library (WIL) library always deals with addresses in host order, converting as necessary when communicating with the WINSOCK. 3.4 Socket Concepts A socket is a small integer number used to identify the endpoint for TCP/IP communications. It is the fundamental Internet network programming interface. 3.4.1 Socket Ports Internet communications occurs between two end-points each of which is defined by an IP address and a "port number", a 16-bit integer number. In this way, multiple sessions between the same two computers can occur simultaneously, each using a different port number. Established Internet Protocols have a port number called the "well known port" assigned to them. For example, FTP always uses port number 21. Application server programs should use a port number of at least 5000. See the WHO_S program for an example server. Sockets are further differentiated as to whether they are TCP sockets or UDP sockets. WIL supports TCP sockets only. WIL4C Users Manual Page 12 3.4.2 Socket Address Structure The socket requires a socket address structure which contains additional information neccessary (port number, remote IP address, etc.) for communications to a remote endpoint. The WIL library handles all details of socket address structures. 3.4.3 TCP and UDP Sockets There are two types of sockets: datagrams (UDP sockets) and streams (TCP sockets). UDP sockets are rarely used in network application programming, and are thus not implemented in WIL. TCP sockets implement bi-directional data streams, guaranteed to be error free. TCP is used for most application level net programming, including all of the example programs. 3.5 Client and Server Side There are two distinct classes of internet programming: Client side and Server side. 3.5.1 Server Programs A server is a program that provides some service. It runs continuously, waiting for a client to connect to it. Server programs listen for incoming connections. When an incoming connection is detected, the server program can accept the connection, after which the socket I/O can occur. +------+ | BIND | +--+---+ | +---+----+ +--------+ | LISTEN +------------+ ACCEPT | +--------+ +--------+ The program WHO_S is an example of a simple server program. It provides a simple "whois" service for its client WHO_C. Also see WHO_C, which is an example of a client for the WHO_S server. WIL4C Users Manual Page 13 3.5.2 Client Programs Most user application progams are "client side" programs. A client program is a program that connects to a server program to perform some service. A client program is run only when the service is needed. FINGER, VIEW, MAIL, FROM, FTP, NEWS, and WHO_C are all examples of client programs. 3.6 Stream (TCP) Programming TCP (Transmission Control Protocol) is the basic protocol upon which all of the example programs are written. Some important characteristics of a TCP connection are: (1) The TCP connection as a bi-direction pipe, or stream. There is no concept of packets at the TCP level. What goes in one end comes out the other. (2) TCP provides for a reliable connection. Addition checksums are not required. (3) TCP uses a 16-bit port number to identify the connection endpoint. Thus, an "endpoint" is the pair (host, port). This allows a given host to be running multiple concurrent sessions, each with a unique endpoint. 3.7 Windows Winsock Sockets There are really two classes of Winsock API calls: blocking and non-blocking (asynchronous). Sockets were originally designed for the UNIX operating system, and block until a requested operation completes. This works well in a true multi-tasked operating system like UNIX. When the Windows Winsock API was designed for Windows 3.X, several additional asynchronous winsock commands were added in addition to the traditional blocking commands. 3.8 Synchronous Versus Asynchronous Programming There are two different styles of Winsock programming: Synchonous and Asychronous. Each has its advantages and disadvantages. WIL4C supports both styles of programming. Examples of the synchronous style include HOST, SFINGR, VIEW, WHO_S, and WHO_C. Example of the asynchronous style include AFINGR, FINGER, NNTP, MAIL, and FROM. FTP is an example employing both synchronous and asynchronous styles. WIL4C Users Manual Page 14 3.8.1 Synchronous Programming The synchronous style of Winsock programming is characterized by sending a command, then waiting for the response in a polling loop. Typically, the hour glass cursor is displayed during this waiting period. This style is typical of UNIX programs, but does not mesh well with the Windows message event loop, except for perhaps program threads running under Win32. On the positive side, synchronous programs are easier to follow and require less code. 3.8.2 Asynchronous Programming The asynchronous style of Winsock programming is characterized by sending a command, then continuing on with other work until a message arrives signifying the completion of the command request. This style of Winsock programming uses the Windows message loop mechanism, and is considered the "Windows friendly" approach. Compare the three Finger programs SFINGR, AFINGR, and FINGER. SFINGR uses the synchronous style, AFINGR uses the asynchronous style, and FINGER uses the asynchronous style as implemented with the ASYNC.C module functions. Studying the three Finger programs (SFINGR, SFINGR, and FINGER) is a good way to compare the synchronous versus the two asynchronous styles of Winsock programming. Refer to the following section "The ASYNC Functions" for details on how the ASYNC functions operate. In particular, compare AFINGR (which does not use the ASYNC functions) to FINGER (which does). WIL4C Users Manual Page 15 3.9 The ASYNC Functions The ASYNC functions operate using the wilAwaitEvent function to post winsock event messages to WM_USER, which are passed to the ASYNC code for processing. Messages may also be posted to WM_USER+1 to notify the application of the completion of a sequence of requested events. In practice, this is simpler than it sounds. Examine FINGER.C to see an example. The ASYNC functions are contained in the file ASYNC.C. 3.9.1 AsyncConnect The purpose of the AsyncConnect function is to connect to a remote host. SOCKET AsyncConnect( HWND hWnd, /* window to post messages */ LPSTR ServerType, /* server type (eg: POP3) */ LPSTR ServerName, /* server name (eg: mail.iquest.com) */ int Port, /* sever port */ int SuccessMsg, /* wParam for WM_MSG if successful */ int FailureMsg) /* wParam for WM_MSG if failure */ In the following call to AsyncConnect, the caller is requesting a connection to a POP3 server with name "mail.iquest.com", using the well known POP3 port 110. If the connection is successful, message SUCCESS_MSG should be posted for event WM_USER+1 in window hWnd. If unsuccessful, FAILURE_MSG should be posted for event WM_USER+1. Socket = AsyncConnect(hMainWnd, "POP3", "mail.iquest.com", 110, SUCCESS_MSG, FAILURE_MSG); Upon success, the returned socket may be used for socket I/O. WIL4C Users Manual Page 16 3.9.2 AsyncRead The purpose of the AsyncRead function is to wait for any incoming data on the port specified in the call to AsyncConnect. int AsyncRead( int SuccessMsg, /* wParam for WM_MSG if successful */ int FailureMsg, /* wParam for WM_MSG if failure */ int ReadType) /* async read type */ The ReadType can be any of the following: ReadType Symbol Response Expected ASYNC_NONE No server response is expected. ASYNC_SINGLE_LINE Single Line of Text (LOT). ASYNC_MULTIPLE_LINES Multiple LOTs. ASYNC_SINGLE_CODED Single line: decimal response plus LOT. ASYNC_MULTIPLE_CODED Multiple lines: decimal response plus LOT. ASYNC_PLUS_MINUS Single line: "+OK" or "-ERR" plus LOT. The "Line of Text" (LOT) above consists of 7-bit ASCII characters followed by a carriage return (CR) and line feed (LF). The "decimal response" code consists of 3 decimal ASCII digits (eg: "125"). In the following call to AsyncRead, the caller is awaiting a single line of test. Once the incoming text line is read and optionally echoed to the display (see AsyncSetEcho), message SUCCESS_MSG should be posted for event WM_USER+1. If unsuccessful, FAILURE_MSG should be posted for event WM_USER+1. AsyncRead = AsyncRead(SUCCESS_MSG, FAILURE_MSG, ASYNC_SINGLE_LINE); 3.9.3 AsyncWrite The purpose of the AsyncWrite command is to write the specified command on the port specified in the call to AsyncConnect. int AsyncWrite( LPSTR Command, /* command to send to server */ int SuccessMsg, /* wParam for WM_MSG if successful */ int FailureMsg) /* wParam for WM_MSG if failure */ In the following call to AsyncWrite, the caller wants to write the text line in 'Command'. Once the text line is written and optionally echoed to the display (see AsyncSetEcho), message SUCCESS_MSG should be posted for event WM_USER+1. If unsuccessful, FAILURE_MSG should be posted for event WM_USER+1. AsyncRead = AsyncWrite("LIST", SUCCESS_MSG, FAILURE_MSG); WIL4C Users Manual Page 17 3.9.4 AsyncCommand The purpose of the AsyncCommand command is to combine the functions of AsyncWrite and AsyncRead into a single command. See AsyncWrite and AsyncRead above. Also refer to ther example programs which use AsyncCommand. int AsyncCommand( LPSTR Command, /* command to send to server */ int SuccessMsg, /* wParam for WM_MSG if successful */ int FailureMsg, /* wParam for WM_MSG if failure */ int ReadType) /* async read type */ 3.9.5 AsyncGetBufPtr The purpose of the AsyncGetBufPtr is to return a pointer to the text line buffer used by AsyncRead, AsyncWrite, and AsyncCommand. LPSTR AsyncGetBufPtr(void); 3.9.6 AsyncProcessMsg The purpose of the AsyncProcessMsg command is to process WM_USER messages. The main window (as specified by hWnd in the call to AsyncConnect) should contain the following line in the main event loop: case WM_USER: AsyncProcessMsg(wParam) break; The application should NOT post WM_USER messages when using the ASYNC functions. 3.9.7 AsyncSetEcho The purpose of the AsyncSetEcho function is to set the echo flag for all subsequent ASYNC processing. int AsyncSetEcho(int EchoFlag); If the EchoFlag is TRUE, all text strings sent to (and received from) the server are echoed to the display. The AsyncSetEcho function returns the previous value of the echo flag. WIL4C Users Manual Page 18 3.9.8 AsyncSetDebug The purpose of the AsyncSetDebug function is to set the debug flag. The DebugFlag is used by the ASYNC code to display additional information. The AsyncSetDebug flag is meant for debugging ASYNC calls. int AsyncSetDebug(int DebugFlag); The programmer should rarely have need to use this function. 3.9.9 POST Macros Posting to WM_USER is reserved for ASYNC functions. Posting to WM_USER+1 may be done by both ASYNC finctions and application functions. Two macros are defined for posting messages to WM_USER+1. The POST_MSG macro posts message (m) with parameter value 0. The POST_PARM macro posts message (m) with parameter (p). The POST_PARM macro is used pass back the numeric 3-digit response codes from SMTP, FTP, etc., or the "+OK" (100) or "-ERR" (500) POP3 codes. The macros are defined in ASYNC.H as #define POST_MSG(m) PostMessage(hMainWnd,WM_USER+1,(m),0) #define POST_PARM(m,p) PostMessage(hMainWnd,WM_USER+1,(m),(p)) The POST macros are used by both the ASYNC functions and the example code. WIL4C Users Manual Page 19 4.0 Internet Protocols The Internet protocols to follow all communicate using ASCII text lines. Each line ends with a carriage return, line feed (CR, LF) pair. The client program initiates the protocol by connecting to the server. What happens next is dependent on the particular protocol. The following discussions are for overview only. Refer to the proper RFCs for details on the protocols. 4.1 Finger The Finger protocol is one of the simplest Internet protocols. For this reason, it is an excellent protocol to study for those without any Winsock programming experience. Finger allows one to retrieve information about a remote user on a remote host machine. If the remote user has a "plan file", then this information is returned in addition to the normal Finger data. Finger uses TCP with well known port number 79. The client side of the Finger protocol works as follows: (1) The client connects to the Finger sever on the remote host using TCP and port 79. The server does NOT send a greeting. (2) Once connected, the client sends a single line of text containing the login name of the user for which information is wanted. (3) The Finger server will send a series of text lines back. After the last line, the Finger server closes the connection. The Finger protocol is a very simple protocol. Three example Finger programs are included: (1) SFINGR: Synchronous version of Finger. (2) AFINGR: Asynchronous version of Finger. (3) FINGER: Asynchronous version of Finger using the ASYNC functions. Also see RFC 1288 for a detailed description of Finger. Note that not all Internet hosts provide Finger servers, although many do. WIL4C Users Manual Page 20 4.2 SMTP The SMTP (Simple Mail Transport Protocol) protocol allows the user to send mail to a remote user. SMTP uses TCP with well known port number 25. All mail messages must consist of one or more lines of 7-bit ASCII characters, each line terminating with a carriage return, line feed pair. All server responses begin with a 3 digit decimal response code. Values of 500 and above indicate an error condition. 4.2.1 SMTP Protocol The client side of the SMTP protocol works as follows: (1) The client connects to the SMTP server on the remote host using well known port 25. Once connected, the server responds with a greeting message, which may be one or more lines. (2) The client sends the "HELO myhost.com" command to the server where myhost.com is the local host name. The server responds with a greeting message. (3) The client sends the "MAIL FROM" command as shown in the example below. The server should respond with "250 OK". (4) The client sends the "RCPT TO" command to identify the recipient of the mail. The server responds with "250 OK". Additional recipients are sent by the client as required by sending additional "RCPT TO" commands. (5) The client sends the "DATA" command as shown below. The server responds with "250 OK". (6) The client sends the mail message as a series of text lines, each terminated by a carriage return, line feed pair. A text line consisting of just a period is "quoted" by adding a second period, since a line with a lone period indicates the end of the message. After all message lines have been sent, a line with a lone period (".\r\n") is sent to end the transmission. The server responds with "250 OK". (7) If another email is to be send, go back to step (4) above, otherwise sign off by sending the "QUIT" command. WIL4C Users Manual Page 21 4.2.2 SMTP Example In the following example, the caller mike@marshallsoft.com sends a 3 line email message to Pierre at pierre@louve.com. Each line sent and received terminates with a carriage return, line feed pair. The "C:" (for client) and "S:" (for server) are not part of the protocol, but are shown to identify the client (C:) and server (S:) originated messages. C: (Connects to remote SMTP server). S: 220 LOUVE.COM SMTP server version 1.2.1 C: HELO marshallsoft.com S: 250 Nice to meet you marshallsoft.com C: MAIL FROM: S: 250 OK C: RCPT TO: S: 250 OK C: DATA S: 250 OK C: first line of email C: second line of email C: third line of email C: . S: 250 OK C: QUIT S: 221 au revoir. Refer to the MAIL and BCAST programs for examples of a SMTP client. Also see RFC 821 for a complete description of SMTP. WIL4C Users Manual Page 22 4.3 POP3 The POP3 (Post Office Protocol version 3) protocol allows the user to retrieve mail from his POP3 server. POP3 uses TCP with well known port number 110. All server responses consists of a single line of text ending with a carriage return, line feed pair and beginning with either a "+OK" or "-ERR". 4.3.1 POP3 Protocol The client side of the POP3 protocol works as follows: (1) The client connects to the POP3 sever on the remote host using TCP and port 110. The server responds with its greeting. (2) The client sends the USER command to identify the account. The server responds with "+OK". (3) The client sends the password for the USER account using the PASS command. The server responds with a "+OK". (4) The client is now "logged onto" the POP3 server. Several commands can now be sent including: (a) The STAT command request the # of messages (and total bytes) waiting. (b) The RETR command retrieves a particular message number. (c) The DELE command deletes a particular message number Refer to the following example for the usage of these commands. (5) After all processing is done, the QUIT command is sent to log off of the POP3 server. The server responds with "+OK". Note that you must have a POP3 account set up by the host computer's system administrator. Mail sent to you is queued on your POP3 account for retrieval by you. WIL4C Users Manual Page 23 4.3.2 POP3 Example In the following example, Pierre has a POP3 account set up with user name "Pierre" and password "francaise". The client program connects to the POP3 server, gets the message status, receives the first message, and then deletes it. C: (Connects to remote POP3 server). S: +OK server SuperPOP ready. C: USER Pierre S: +OK user is Pierre C: PASS francaise S: +OK Pierre's maildrop has 2 messages. C: STAT S: +OK 2 1950 C: RETR 1 S: +OK 1050 bytes S: (1st line of email message 1) S: (2nd line of email message 1) : S: (last line of email message 1) S: . C: DELE 1 S: +OK message 1 deleted C: QUIT S: +OK goodbye. Refer to the FROM and MAIL programs for examples of a POP3 client. Also see RFC 1460 for a complete description of SMTP. WIL4C Users Manual Page 24 4.4 NNTP The NNTP (Network News Transport Protocol) protocol allows the client to download (and upload) network news articles from his NNTP server. NNTP uses TCP with well known port number 119. The client sends text command lines to the server, and the server responds with a 3 digit numeric coded response line plus the requested text information. If text information is sent by the server, the last line will consist of (a text line with) a single period. Server response codes of 500 and above indicate an error condition. The NTTP news server maintains a list of news articles grouped into sets called "newsgroups", each of which has a name. The LIST command can be used to read all newsgroups. A particular newgroup must be selected by the GROUP command before any news articles can be read. Each newsgroup consists of zero or more articles. Individual articles are numbered and are deleted by the server after some period of time after first receiving the article, depending on the individual server. The article number of deleted articles are not reused. Each article consists of two parts: the article header and the article body. The article header consists of a short summary of the article body itself. The server maintains a "current pointer" to the current article, initialized to the first article in the newsgroup. Once a newsgroup has been selected, news headers and/or articles can be read. Commands include: HEAD : read the current article header. HEAD ddd : read article header number ddd (eg: READ 1286). ARTICLE : read the current article. ARTICLE ddd : read article number ddd. NEXT : advance to next article in the newsgroup. LAST : advance to last article in the newsgroup. Articles can also be posted by the NTTP client by using the POST command, if allowed for the particular newsgroup. WIL4C Users Manual Page 25 4.4.1 NNTP Protocol The client side of the NNTP protocol works as follows: (1) The client connects to the NNTP sever on the host (typically your ISP) using TCP and port 119. The server responds with its greeting message. (2) The client may send a LIST command to request a list of newsgroups. The server responds with a (usually very long) list of newsgroups. (3) The client selects a newsgroup using the GROUP command. The server responds with a response line consisting of the response code, the number of articles, the first article number, the last article number, and the group selected. For example 211 1982 18726 21918 comp.lang.c (4) The client requests article headers by using the HEADER command and the article body itself by using the ARTICLE command. The client may also advance the current article pointer by using the NEXT or LAST command. Note that the NEXT and LAST command do not retrieve a article header or the article body itself, but rather just move the current article pointer so that subsequent HEADER or ARTICLE commands (without a specified article number argument) will retrieve the current article header or article body. (5) The client can post articles, if allowed, by using the POST command. After sending the POST command (without any arguments), the server will prompt you to send the body of the article to be posted, which consists of multiple text lines, followed by a line with just a period. Refer to RFC 1036 for details on article formats. WIL4C Users Manual Page 26 4.4.2 NNTP Example In the following NNTP session, the client connects to the NTTP server, request a list of all newsgroups, selects newsgroup comp.lang.c, request the current (first) article, request the last article, then quits. C: (Connects to NTTP server using TCP on port 119). S: SuperNTTP ready. Posting OK. C: LIST S: comp.protocols.tcp-ip 514 819 Y S: comp.lang.c 1182 1271 : S: . C: GROUP comp.lang.c S: 211 1982 18726 21918 comp.lang.c C: ARTICLE S: 1st line of current article (#18726) S: 2nd line of current article (#18726) : S: last line of current article (#18726) S: . C: LAST S: Article 21918 selected. Use ARTICLE to retrieve article. C: ARTICLE S: 1st line of current article (#21918) S: 2nd line of current article (#21918) : S: last line of current article (#21918) S: . C: QUIT Refer to the NEWS program for an example of a NNTP client. Note that the example program NEWS does not support article posting. Refer to RFC 1036 for a complete description of NNTP. WIL4C Users Manual Page 27 4.5 FTP The FTP (File Transfer Protocol) protocol allows the user to upload and download text and binary files. FTP uses TCP with well known port number 21. Two types of FTP service exists. The first is where the client connects to a remote host for which he knows the password, allowing him both read and write access. The second type of FTP service is called "anonymous FTP" in which the USER name is "anonymous" ("ftp" is sometimers acceptable instead of "anonymous") with the password set to the clients' email address. This type of FTP service is very common on the Internet. Examples include the MarshallSoft Computing anonymous FTP site at "ftp.marshallsoft.com". The FTP server responds to client commands with a 3 digit number response code followed by the text of the repsonse message, and ending with a carriage return, line feed pair. Response codes of 500 and above indicate a fatal error condition, 400 to 499 indicate a recoverable error condition (try the command again), while codes of 100 through 399 indicate that all went OK. Refer to RFC 959 for more details on FTP response codes. The FTP server may respond with a multi-line response. A dash after the response code indicates that this is not the last response line. 100-1st line of response. 100-2nd line of response. 100 last line of response. Occassionally, other response codes are sent before the last response line, which must always have the same response code as the first response line. For example, 100-1st line of response for code 100. 101 1st line ine of response for code 101. 100 last line of response. FTP does not use the port on which it connects (the control port) to transfer data. Rather, the FTP specifies (using the control port) which port to establish a data connection on using the PORT command (see below). The FTP client then listens on this port for a connection, after which data can be transferred. After all data is transferred, the data port is closed. WIL4C Users Manual Page 28 4.5.1 FTP Protocol The FTP protocol works as follows: (1) The client connects to the FTP sever on the remote host using TCP and port 21. The server responds with its greeting. (2) The client sends the USER command to identify the account. The server responds with response code 331. (3) The client sends the password for the USER account using the PASS command. The server responds with response code 230. (4) The client is now "logged onto" the FTP server. Several commands can now be sent including: (a) The CWD command changes the working directory on the remote machine. If you connect to ftp.marshallsoft.com, you should use the CWD command to change the working directory to "marshallsoft". (b) The LIST command lists all the files in the directory on the remote computer. The LIST command does a formatted list, while the NLST command just lists the filenames. The LIST (and NLST) command requires that the PORT command (see below) be issued first to establish the data port. (c) The TYPE command is used to set either ASCII (TYPE A) or binary mode (TYPE I) to be used for subsequent file transfers. The default is ASCII. The ASCII and BINARY menu commands in the example program FTP.C issue the FTP TYPE command. The TYPE command should be used to set binary mode (see the example program FTP.C) before transfering binary files. (f) The PORT command is used to specify the port over which data will be transferred. The PORT command must be used before using the LIST, NLST, RETR or STOR command. For example, to specify data port 6146 (256*24 + 2) using our (not the remote machines) IP address of 165.113.131.70, we use PORT 165,113,131,70,24,2 (e) The RETR command is used to download a file from the remote computer, using the type as set by the TYPE command, and the data port specified by the PORT command. The data port is closed immediately after all data is tranferred. (f) The STOR command is used to upload a file to the remote computer, using the type as set by the TYPE command, and the data port specified by the PORT command. The data port is closed immediately after all data is tranferred. Note that most anonymous FTP sites do not allow uploading. (g) The QUIT command logs off of the FTP server. WIL4C Users Manual Page 29 4.5.2 FTP Example In the following FTP session, Pierre connects to a FTP server as anonymous, lists all files, changes current directory to "marshallsoft/other", sets binary file type, downloads file DISKBK11.ZIP, then logs off. C: (Connects to remote FTP server). S: 220 SuperFTP server is ready. C: USER anonymous S: 331 Use email address for password. C: PASS pierre@louve.com S: 230-User Pierre logged on. S: 230 This site allows read access only! C: LIST S: (1st line of directory listing) S: (2nd line of directory listing) : S: (last line of directory listing) S: . C: CWD marshallsoft/other S: 250 CWD command successful. C: TYPE I S: 200 Type is set to I. C: PORT 11,231,11,14,20,15 S: 200 Port command successful. C: GET diskbk11.zip S: 150 Opening BINARY mode data connection for diskbk11.zip (file comes in on data port, after which is is closed). S: 226 Transfer complete. C: QUIT S: Au revoir Pierre! Refer to the FTP program for an example of a FTP client. Refer to RFC 959 for a complete description of FTP. WIL4C Users Manual Page 30 4.6 HTTP The HTTP (Hyper Text Transfer Protocol) protocol defines the interation between World-Wide-Web (WWW) servers and WWW clients, popularly known as "Web Browsers". HTTP uses TCP with well known port number 80, and is documented in RFC 2068. HTTP is a complicated protocol. RFC 2068 describing HTTP/1.1 is 162 pages in length. If you want to develop a web browser, you must get a copy of RFC 2068 from the Internic. You will also need to have a knowledge of HTML (Hypertext Markup Language) in order to interprete the data sent by the HTTP server. Fortunately, there are several very good books on HTML such as "Teach Yourself Web Publishing with HTML in 14 Days" by Laura LeMay (Sams Net). A very good way to get comfortable with HTML is to build your own WEB site. Most ISPs (Intenet Service Providers) make provisions for their customers to build "personal" web sites. With some practical experience "surfing the web", a knowledge of HTML, RFC2068, and the example program VIEW.C, you are ready to write a HTTP application. 4.6.1 HTTP Protocol HTTP commands are termed "Methods". These commands are case-sensitive and include only two required (for all HTTP servers) commands: GET and HEAD. The GET command is the fundamental command which retrieves HTML pages. For example, GET /index.html HTTP/1.0 requests page INDEX.HTML. The HEAD method is identical to GET except that only "meta" information is returned for the page. The HTTP client connects to the HTTP server on the remote host, sends a command, receives a response, then terminates the connection. This is repeated for each HTTP command. The server response consists of header text, followed by a blank line, followed by the actual HTML page requested. The first line of the header text consists of the status return, such as: HTTP/1.0 200 OK Return value of 500 & above are server errors, and 400 to 499 are client errors. WIL4C Users Manual Page 31 4.6.2 HTTP Example Suppose that the following Web page HELLO.HTM is on the MarshallSoft Web site (www.marshallsoft.com). MarshallSoft Computing, Inc.

Hello

Hello, world! The following exchange with the HTTP server on the host requests the page HELLO.HTM. C: (Connects to remote FTP server). C: GET /index.html HTTP/1.0 S: HTTP/1.0 200 OK S: Date: Wed, 09 Jul 1997 20:43:59 GMT S: Server: Apache/1.1.3 S: Content-type: text/html S: Content-length: 183 S: Last modified: Wed, 09 Jul 1997 20:00:01 GMT S: S: S: MarshallSoft Computing, Inc. S: S:

Hello

S: Hello, world! S: C: (Disconnects) It is up to the HTTP client to interpret the HTML lines, for which knowledege of the HTML specification is necessary. Note that the client disconnects after receiving each page. WIL4C Users Manual Page 32 5.0 Problems Before attempting to run any of the example programs, you should already be able to connect to the Internet and run your email client program, such as Eudora or Pegasus Mail. You should also be comfortable as a user of the Internet before attempting to program Internet applications. If you cannot get your application to run properly, first compile and run the example programs. If you call us to report a possible bug in the library, the first thing we will ask is if the example programs run correctly. If you are having trouble with a particular protocol, download the RFCs from the Internic for detailed protocol information. Also experiment with the appropriate example program. Unfortunately, there is no substitute for trail and error! Another good resource are the many books and magazines articles around dealing with the various Internet protocols. Although we will be happy to talk to you, we are not experts on the Internet protocols. Our support is limited to the use of our library, not the operation of the Internet protocols. If your application does not run but the example applications run correctly, then you have most likely made a programming mistake in your application. MarshallSoft Computing cannot debug your application, especially over the telephone! We recommend the following steps if you believe that you have discovered a bug in the library: (1) Create the smallest, simplest test program possible that demonstrates the problem. (2) Document your exact machine configuration and what error the test program demonstrates. (3) Email your program to us at bugs@marshallsoft.com. If the problem can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge. WIL4C Users Manual Page 33 6.0 Example Programs There are 12 example programs, covering DNS, Finger, SMTP, POP3, NNTP, FTP, and HTTP. 6.1 HOST The HOST program uses the Domain Name System (DNS) to get internet addresses for hosts for which their name is known. HOST can also get port and server information, if available. 6.2 SFINGR, AFINGR, and FINGER The three finger programs demonstrate the 3 methods of using the WIL4C library. The FINGER protocol is presented in the section on protocols. SFINGR make only synchronous function calls. Refer to the section on "Synchronous WIL" for information on synchronous calls. AFINGR make asynchronous function calls. Refer to the section on "Asynchronous WIL" for information on aynchronous calls. FINGER make asynchronous function calls using the ASYNC commands. Refer to "Using ASYNC Functions" for more information. The Finger client program contact your Finger Server and requests information for a particular user. Many hosts do not have finger servers. You can finger MarshallSoft Computing by specifying (at the prompt) "msc@advicom.com". 6.3 FROM The FROM client program logs onto your POP3 account and checks if you having any waiting mail. If you do, it list the messages by number along with the "From:" and "Subject:" fields, if any. In order to use FROM, you must edit the file FROM.INI which contains POP3 server addresses, and login name & password. For example, suppose your ISP (Internet Service Provider) has host address SUPERSERVE.COM, and your login name is billy. Then FROM.INI may contain: +---------------------------+ | POP3=mail.superserve.com | | USER=billy | | PASS=my_password | +---------------------------+ WIL4C Users Manual Page 34 6.4 MAIL The mail client program is similiar to FROM, except that it can also send, receive, and delete mail. In order to use MAIL, you must edit the file MAIL.INI which contains SMTP & POP3 server addresses, and login name & password. +---------------------------+ | SMTP=mail.superserve.com | | POP3=mail.superserve.com | | USER=billy | | FROM=billy@superserve.com | | PASS=my_password | +---------------------------+ MAIL.INI is similiar to FROM.INI with the addition of the SMTP server (for sending mail) and your email address (FROM line). In fact, you can also use MAIL.INI for FROM.INI. See section 6.9 (BCAST) for a description of the file format for outgoing email messages. Note that the first line must be the destination email address. 6.5 FTP The FTP (File Transfer Protocol) client program communicats with a FTP server, allowing for the transfer of ASCII and binary files. Refer to the section on protocols for information on the FTP protocol. You must provide the login name and password in FTP.INI. For example, if your email address is billy@superserve.com, FTP.INI would contain the following for anonymous FTP. +---------------------------+ | USER=anonymous | | PASS=billy@superserve.com | +---------------------------+ The FTP client program is capable of the following operations: Command Description CWD Changes the working directory at the host. LIST List the contents of the current working directory. ASCII Set ASCII transfer mode. BINARY Sets binary transfer mode. GET Receives specified file from the host. PUT Sends specified file to the host. QUIT Quits the FTP session. Don't forget to set BINARY mode before downloading or uploading a binary file. WIL4C Users Manual Page 35 6.6 NEWS The NEWS client program communicates with a NNTP (Network News Transport Protocol) and provides the following functions: Command Description Group/ List List all groups. Select Select a group for subsequent processing. Header/ GetByNumber Selects header by number. GetCurrent Selects current header. Next Selects next header. Last Select last header. Article/ GetByNumber Selects article by number. GetCurrent Selects current article. Next Selects next article. Last Select last article. Quit Quits the NEWS server. If the user specifies "Group/List", the incoming list of groups is saved in the file NEWS.LST. If the user requests an article by number "Article/GetByNumber", then the article is saved with file extension ".ART". Refer to the section "NNTP Protocol" for information on NNTP. 6.7 VIEW VIEW is HTTP client program which requests and displays source code for a specified HTTP web page. VIEW is not a browser! VIEW can be used as the basis for several types of HTTP clients. Some ideas are as follows: (1) VIEW can be used as the starting point for a web browser. Most of the effort will be in writing the code necessary to interpret the HTML (Hypertext Markup Language) text. (2) VIEW could also be used as the basis for a "ROBOT" program, that searches for email addresses. This is what some search engines do in order to catalog the web sites on the Internet. (3) VIEW could also be used as the starting point for a program that connects to a search engine, copying search results for subsequent anyalyis. VIEW uses the synchronous style of programming. WIL4C Users Manual Page 36 6.8 WHO_C and WHO_S WHO_S is a server program which provides "WHOIS" service for three individuals as requested by the client WHOIS program WHO_C. After starting the server WHO_S, note the IP address. Next, start the client WHO_C, using the WHO_S server IP address to specify the server. Then, specify one of the three people in the WHOIS database: Mike, Pam, or Lauren. The purpose of the WHOIS programs is to demonstate how to write a simple Internet server and matching client. 6.9 BCAST BCAST is a SMTP client that emails a file to each address specified in a list, such as emailing our newsletter to our customers. Several pieces of information must be in the BCAST.INI file: +-------------------------------+ | SMTP=your_SMTP_server_address | | FROM=your_email_address | | RCPT=file_of_email_addresses | | MAIL=file_to_email | +-------------------------------+ Outgoing email messages should be ASCII text files formatted as: Line 1: Email address of destination (MAIL program only). Line 2: "To: " header line. Line 3: "From: " header line. Line 4: "Subject: " header line. Line 5: Blank line. Line 6 to last_line: ASCII email message. Example outgoing email message: +-----------------------------------------------------+ |mike@marshallsoft.com | |To: mike@marshallsoft | |From: pam@traveller.com | |Subject: Test message | | | |The mail destination address must be the 1st line for| |email being sent with the MAIL example program. The | |"To:", "From:", and "Subject:" fields are optional. | |There should be a blank line before the body of the | |message. [7/25/97]. | +-----------------------------------------------------+ WIL4C Users Manual Page 37 7.0 Legal Issues 7.1 Registration WIL4C may be registered for $95 plus $6 S&H ($12 outside of North America). To order, contact us as shown on the title page of this manual. All prices are guaranteed for one year from the release date. Multiple copy discounts (3 or more) and site licenses are available. Please call for details. We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, purchase orders (POs) from recognized US schools and companies listed in Dun & Bradstreet, and COD (street address and phone number required) within the USA (plus a $5 COD charge). For credit card orders, be sure to include the account number, the expiration date, the exact name on the card, and the complete card billing address (the address to which the credit card bill is mailed). Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. If you wish to update from an older version of WIL4C, send $25 plus $6 S&H ($12 S&H outside of North America). The registered package includes: o Win16 & Win32 WIL4C Libraries w/o shareware screens. o Win16 & Win32 source code for WIL and ASYNC. o Printed Users Manual & Reference Manual. o Telephone and email support for one year. The registered user will receive the latest version of WIL4C shipped by US second day priority mail (packet airmail overseas). A 3.5" HD diskette is provided. WIL4C Users Manual Page 38 7.2 License MarshallSoft Computing, Inc. grants the registered user of WIL4C the right to use one copy of the WIL4C library (in object form) on a single computer in the development of any software product (other more than one computer at the same time. The source code for the library (WIL.C and ASYNC.C) is copyrighted by MarshallSoft Computing and may not be released in whole or in part. Products developed using WIL4C may be distributed without royalty. 7.3 Warranty MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE. Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you. This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts. WIL4C Users Manual Page 39 8.0 Summary 8.1 Revision History Version 1.0: 28 July, 1997. o The initial release of WIL4C. [reserved] 8.2 WIL4C Function Summary Refer to the WIL4C Reference Manual (WIL4C_R.TXT) for detailed information on the communications and support functions. A one line summary of each function follows on the next page. There are 54 functions in the WIL library. Also examine the usage of these functions in the example programs. WIL4C Users Manual Page 40 +-------------------------------------------------------------------+ | wilAccept : Accepts incoming connection. | | wilAttach : Attaches (initializes) winsock. | | wilAskHostByAddr : Request host information from server. | | wilAskHostByName : Request host information from server. | | wilAskProtoByName : Request protocol information. | | wilAskProtoByNumber : Request protocol information. | | wilAskServByName : Request server information. | | wilAskServByPort : Request server information. | | wilAwaitEvent : Set asynchronous event winsock mask. | | wilBind : Bind socket to specified address & port nunber. | | wilCancelBlocking : Cancels blocking call. | | wilCloseSocket : Close socket. | | wilConnect : Initiate connection to remote port. | | wilDataIsReady : Is socket readable (data is ready). | | wilDebug : Returns bebug value. | | wilErrorText : Get text associated with error code. | | wilGetDescription : Get winsock description text. | | wilGetHostAddr : Get host address. | | wilGetHostAlias : Get host name alias. | | wilGetHostDotted : Get host dotted address. | | wilGetHostName : Get host name. | | wilGetMaxSockets : Get maximum number of sockets supported. | | wilGetMaxUDPSize : Get maximum UDP packet size. | | wilGetMyHostAddr : Get local host address. | | wilGetMyHostDotted : Get local host (dotted) address. | | wilGetMyHostName : Get local host name. | | wilGetProtoName : Get protocol name. | | wilGetProtoNumber : Get protocol number. | | wilGetServName : Get server name. | | wilGetServPort : Get server port. | | wilGetSystemInfo : Get winsock system information. | | wilGetVendorInfo : Get winsock vendor information. | | wilIsBlocking : Is winsock currently blocking ? | | wilIsConnected : Is socket connected to remote ? | | wilIsDotted : Is dotted string properly formed ? | | wilListen : Listen for incoming connection attempts. | | wilLocalSockAddr : Get local sock address for connected socket. | | wilLocalSockPort : Get local sock port number for connected sock. | | wilParseDecimal : Parse decimal response code. | | wilPeekSocket : Peek into socket. | | wilReadLine : Read line terminated with linefeed. | | wilReadOOB : Read Out-Of-Bound data. | | wilReadSocket : Read from socket. | | wilReadString : Read string from socket. | | wilRelease : Release (free) winsock. | | wilRemoteSockAddr : Get remote sock address for connected socket. | | wilRemoteSockPort : Get remote port number for connected socket. | | wilSetOOB : Sets Out-Of_Bound data state. | | wilSocketStatus : Get socket read/write status. | | wilTcpSocket : Create TCP socket. | | wilWriteOOB : Write Out-Of_Bounds data to socket. | | wilWriteSocket : Write buffer to socket. | | wilWriteString : Write string to socket. | | wilWriteLine : Write linefeed terminated line to socket. | +-------------------------------------------------------------------+ WIL4C Users Manual Page 41 9.0 Other MarshallSoft Computing Products Several shareware products are available from MarshallSoft Computing. 9.1 The Windows Standard Communications Library for C/C++ The Windows Standard Communications Library for C/C++ (WSC4C) is a Windows based asynchronous serial communications library designed for software developers programming in C/C++. WSC4C uses the Windows communications driver. Both 16-bit amd 32-bit DLLs are included along with 5 example programs. The Windows Standard Communications Library for C/C++ (WSC4C) is available for $75 plus $6 S&H ($12 S&H overseas). 9.2 The Personal Communications Library for Windows (C/C++) The Personal Communications Library for Windows (PCL4W) is a Windows based [Win16] asynchronous communications library designed for software developers programming in C/C++. Unlike WSC4C, PCL4W interfaces to the serial port hardware directly. PCL4W also supports multiport boards such as those made by DigiBoard and BOCA. The Personal Communications Library for Windows (PCL4W) is available for $75 plus $6 S&H ($12 S&H overseas). 9.3 The Personal Communications Library for C/C++ / DOS PCL4C is similar to PCL4W except that it is designed for DOS. Includes support for both 16-bit and 32-bit protected mode. 9.4 Libraries for Other Languages We have communications libraries for C/C++, Turbo Pascal, Visual Basic, and PowerBASIC. Check our BBS or WEB site. PCL4C : C/C++, DOS [include 16-bit & 32-bit protected mode]. PCL4P : Turbo Pascal, DOS [includes 16-bit protected mode]. PCL4VB : Visual Basic, DOS. PCL4PB : Power Basic, DOS. PCL4W : C/C++, Windows 3.1 & Win 95, talks to hardware directly. PCLVBW : Visual Basic, Win 3.1 & Win 95, talks to hardware directly. WSC4C : C/C++, Win 3.1, Win 95, Win NT. Uses Windows API. WSC4VB : Visual Basic, Win 3.1, Win 95, Win NT. Uses Windows API. WSC4D : Borland DELPHI, Win 3.1, Win 95, Win NT. Uses Windows API. WIL4C Users Manual Page 42