1 Introduction

1.1 Documentation Set
1.2 Registration
1.3 License
1.4 Warranty

2 Internet Tutorial

2.1 Networks
2.2 Conceptual Architecture
2.3 Internet Protocol Address
2.4 Example Network
2.5 Dial Up Connections

3 Internet Programming 3.1 Internet RFC's

3.2 Protocol Layers
3.3 The Internet Protocol (IP)
3.4 Socket Concepts
3.5 The Domain Name System (DNS
3.6 Client and Server Programming
3.7 Stream (TCP) Programming
3.8 Windows Winsock Programming
3.9 Synchronous VS Asynchronous Programming
3.10 Win32 Console Mode
3.11 The ASYNC Functions

4 Internet Protocols

4.1 Finger Protocol
4.2 SMTP Protocol
4.3 POP3 Protocol
4.4 NNTP Protocol
4.5 FTP Protocol
4.6 HTTP Protocol
4.7 ECHO Protocol
4.8 TELNET Protocol

5 Problems
6 Summary

6.1 WIL Function Summary

1 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:

• Handling details like converting from host byte order to network byte order (and vice versa) as necessary automatically.
• Handling the creation and manipulation of Winsock data structures automatically.
• Providing a straight forward interface, using only necessary arguments.
• 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 also provided by the ASYNC.C functions, which can transmit commands and receive responses as used by these protocols.

Lastly, a good selection of example programs is 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 that the shareware version displays the "shareware" screen at startup and every 20 minutes thereafter. Of course, the registered version does not display the shareware screen. The registered version also includes source code.

1.1 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the second manual (WIL_USR) in the set.

• WIL4C Programmer's Manual (WIL4C.DOC, WIL4C.TXT, WIL4C.HTM)
• WIL User's Manual (WIL_USR.DOC, WIL_USR.TXT, WIL_USR.HTM)
• WIL Reference Manual (WIL_REF.DOC, WIL_REF.TXT, WIL_REF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).
  
  
  

1.2 Registration

WIL4C may be registered for $105 for email delivery. If printed manuals are to be mailed, there is an additional $20 charge for delivery in the US, Canada, or Mexico, or $25 for delivery elsewhere. However, note that nicely formatted manuals can be printed using Word 97/99/2000 (or Windows WordPad) and the Word version (*.DOC) of each manual.

There are several methods of ordering, as follows:

• Order online using a credit card at http://www.marshallsoft.com
• Fill out the INVOICE.TXT form and email it to us at order@marshallsoft.com
• Fill out the INVOICE.TXT form and FAX it to us at 1-256-880-0925
• Fill out the INVOICE.TXT form and mail it to us at the address on the first page of this manual.

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.

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). Credit card orders can be called in, emailed, faxed or submitted using our secure server at www.marshallsoft.com. Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. Note that all ordering information collected, including email addresses, is kept strictly confidential.

If you wish to update from an older version of WIL4C, send $30 for email delivery.

The registered package includes:

• Win16 and Win32 WIL4C Libraries w/o shareware screens.
• Win16 and Win32 source code for WIL and ASYNC.
• Telephone and email support for one year.
  
  
  

1.3 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 than libraries such as WIL4C). The user may not use the library on 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. The registered DLLs may be distributed (without royalty) in object form only, as part of the user's compiled application. The registered DLL's may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission.

1.4 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.

2 Internet Tutorial

2.1 Networks

One must begin with the idea of physical networks. Although classified as either LANs (Local Area Networks) or WANs (Wide Areas Networks), they all provide the physical connectivity between computers. The dominant network technologies today (1999) are Ethernet, Fiber Distributed Data Interconnect (FDDI), and Asynchronous Transfer Mode (ATF). Ethernet is by far the most common, particularly for small networks.

Computers connected to a network can send and receive data packets to other computers on the same network. TCP/IP is a common protocol suite installed on many networks, although other protocols may also be used. The WIL functions can be used on any TCP/IP network, regardless of whether it is connected to the Internet or not.

2.2 Conceptual Architecture

Think of the Internet as a collection of networks that are interconnected by special computers called "routers" (or gateways). Each host computer on the Internet has one or more network connections, which will either be a physical network such as Ethernet, or a modem connection emulating a network connection. Each host connection must have a unique Internet Protocol (IP) address. Refer to the example below.

2.3 Internet Protocol Address

An Internet Protocol address is a 32-bit number which consists of two parts, a network ID (NETID) and a host ID (HOSTID). The NETID identifies the network and the HOSTID identifies a particular host computer interface on the network. A computer will have an unique IP address for each internet connection. A computer with more than one internet connection, such as a router, is referred to as being "multi-homed".

There are several classes of IP address:

    byte     0        1        2        3      Number of Bits
     bit  01234567 01234567 01234567 01234567  NETID  HOSTID
Class A:  0nnnnnnn hhhhhhhh hhhhhhhh hhhhhhhh    7      24
Class B:  10nnnnnn nnnnnnnn hhhhhhhh hhhhhhhh   14      16
Class C:  110nnnnn nnnnnnnn nnnnnnnn hhhhhhhh   21       8

where n = NETID bits and h = HOSTID bits.

2.4 Example Network

Consider the following example consisting of three local networks. Host 1 on network 1, with address (1,1), can send packets directly to host 2 and host 3 on network 1, since they are on the same physical network. If host 1 wants to send a packet to host 2 on network 3, it must send it to the router, which then forwards it to network 2. The router only uses the destination network ID. Note that the router has 4 IP addresses, one for each network of which it is a member.

In the following example, the router is connected to networks 1, 2, and 3. If a request is received by the router for a network other than 1, 2, or 3, it is forwarded to another router, which in turn must figure out what to do with the packet. The important point is that the router forwards IP packets based solely on the NETID portion of the IP address.

                                     +---------(4)--------> Other router
                                     |                      (Internet)
                                 +---x----+
                  +--------------x Router x-------------+
                  |              +---x----+             |
                 (1)                (2)                (3)
                  |                  |                  |
      +--------+  |      +--------+  |      +--------+  |
      | Host 1 x--o      | Host 1 x--o      | Host 1 x--o
      +--------+  |      +--------+  |      +--------+  |
                  |                  |                  |
      +--------+  |      +--------+  |      +--------+  |
      | Host 2 x--o      | Host 2 x--o      | Host 2 x--o
      +--------+  |      +--------+  |      +--------+
                  |                  |
      +--------+  |      +--------+  |         Net 3
      | Host 3 x--o      | Host 3 x--o         Hosts
      +--------+         +--------+
 
        Net 1              Net 2
        Hosts              Hosts

2.5 Dial Up Connections

3 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. Two good Winsock references are Developing for the Internet with Winsock by Dave Roberts, published by IDG Books (Coriolis Groups Books), ISBN 1-883577-42-X, and Windows Sockets Network Programming by Bob Quin and Save Shute, published by Addison Wesley, ISBN 0-201-63372-8.

3.1 Internet RFC's

The various Internet standards are defined in "Requests for Comments", or RFC's. RFC's are text files, and are available on the Internet at ftp://ds.internic.net. The index of all RFC documents is found in the file rfc-index.txt. Some important RFC's 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 RFC's. Anyone wanting to implement a particular protocol should download a copy of the appropriate RFC's from the Internic.

In addition to RFC's, the Internic also publishes additional classes of documents:

• Internet Drafts (ID).
• For Your Information (FYI).
• Standard RFC's (STD).
  
  
  

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 |

3.3 The Internet Protocol (IP)

3.3.1 Best Effort Delivery

3.3.2 IP Addresses

192.174.122.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 Interface Library (WIL) library always deals with addresses in host order, converting as necessary when communicating with the Winsock.

3.4 Domain Name System

Since IP addresses, even in dotted notation, are difficult to remember, the Domain Name System (DNS) was created. A particular host computer may have a "domain name" associated with it's IP address. For example, IP address "192.174.122.2" may be associated with a computer host named "www.microwealth.com", so that if you know the name, you can request that DNS lookup the IP address for you.

The DNS is a multi-level distributed database beginning with the Winsock itself, which is why it may take perhaps 20 or 30 seconds to return the IP address for a specified host name. Occasionally the DNS will not be able to find the IP address. Trying again at a later time may prove successful.

The primary purpose of the DNS is to lookup IP addresses given a domain name. Note that if you already know the IP address, you don't need to call the DNS.

3.5 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.5.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 and CFGR_S example programs for examples servers.

Sockets are further differentiated as to whether they are TCP sockets or UDP sockets.

3.5.2 Socket Address Structure

The socket requires a socket address structure which contains additional information necessary (port number, remote IP address, etc.) for communications to a remote endpoint.

The WIL library handles all details of socket address structures.

3.5.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. See the UECHOC.C and UECHOS.C example programs.

TCP sockets implement bi-directional data streams, guaranteed to be error free. TCP is used for most application level net programming, including most of the example programs.

3.6 Client and Server Side

There are two distinct classes of internet programming - Client side and Server side.

3.6.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 |
    +--------+            +--------+

3.6.2 Client Programs

3.7 Stream (TCP) Programming

1. The TCP connection is 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. Additional 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.8 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 2.X, several additional asynchronous Winsock commands were added in addition to the traditional blocking commands.

3.9 Synchronous Versus Asynchronous Programming

There are two different styles of Winsock programming: Synchronous and Asynchronous. Each has its advantages and disadvantages. WIL4C supports both styles of programming.

Examples of the synchronous style include HOST, SFINGR, VIEW, WHO_S, WHO_C, ECHO_S, and ECHO_C.

Examples of the asynchronous style include AFINGR, FINGER, NNTP, MAIL, and FROM.

FTP is an example employing both synchronous and asynchronous styles.

3.9.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 or console mode running under Win32. On the positive side, synchronous programs are easier to follow and require less code.

3.9.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 four Finger programs SFINGR, AFINGR, CFINGR, 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. CFINGR is written for Win32 console mode.

Studying the four Finger programs (SFINGR, SFINGR, CFINGR, and FINGER) is a good way to compare the synchronous versus the two asynchronous styles of Winsock programming.

Refer to Section 3.11 "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).

3.10 Win32 Console Mode

Console mode programs are Win32 programs that run at the command prompt level. They work like DOS programs in that they interface to the console (keyboard & CRT) and have no Graphical User Interface (GUI). There are multiple examples of console mode programming in the WIL4C distribution zip file, such as ECHO_S.C and ECHO_C.C.

3.11 The ASYNC Functions

The ASYNC functions are only used in the asynchronous style of Winsock programming. They are not used in the synchronous or console styles.

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.11.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 (e.g.: POP3) */
 LPSTR ServerName,  /* server name (e.g.: mail.iquest.com) */
   int Port,        /* sever port */
   int SuccessMsg,  /* wParam for WM_MSG if successful */
   int FailureMsg)  /* wParam for WM_MSG if failure */

Socket = AsyncConnect(hMainWnd, "POP3", "mail.iquest.com", 110, SUCCESS_MSG, FAILURE_MSG);

Upon success, the returned socket may be used for socket I/O.

3.11.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 */

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 (e.g.: "125").

In the following call to AsyncRead, the caller is awaiting a single line of text. 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.11.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 */

AsyncRead = AsyncWrite("LIST", SUCCESS_MSG, FAILURE_MSG);

3.11.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 the 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.11.5 AsyncGetBufPtr

LPSTR AsyncGetBufPtr(void);

3.11.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;

3.11.7 AsyncSetEcho

   int AsyncSetEcho(int EchoFlag);

3.11.8 AsyncSetDebug

   int AsyncSetDebug(int DebugFlag);

3.11.9 POST Macros

   #define POST_MSG(m) PostMessage(hMainWnd,WM_USER+1,(m),0)

   #define POST_PARM(m,p) PostMessage(hMainWnd,WM_USER+1,(m),(p))

4.0 Internet Protocols

4.1 Finger

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.

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 24. 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: The client connects to the SMTP server on the remote host using well known port 24. Once connected, the server responds with a greeting message, which may be one or more lines.

1. 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.
   
   
2. The client sends the "MAIL FROM" command as shown in the example below. The server should respond with "250 OK".
   
   
3. 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.
   
   
4. The client sends the "DATA" command as shown below. The server responds with "250 OK".
   
   
5. 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.
   
   
6. 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".

If another email is to be sent, go back to step (4) above, otherwise sign off by sending the "QUIT" command.

4.2.2 SMTP Example

In the following example, the caller mike@marshallsoft.com sends a 3 line email message to Pierre at pierre@thelouve.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 THELOUVE.COM SMTP server version 1.2.1

C: HELO marshallsoft.com

S: 250 Nice to meet you marshallsoft.com

C: MAIL FROM:<mike@marshallsoft.com>

S: 250 OK

C: RCPT TO:<pierre@thelouve.com>

S: 250 OK

C: DATA

S: 250 OK

C: first line of email

C: second 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.

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 16.

All server responses consist of a single line of text ending with a carriage return, line feed pair and beginning with either an "+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 16. 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 an "+OK".

The client is now "logged onto" the POP3 server. Several commands can now be sent including:

1. The STAT command requests the # of messages (and total bytes) waiting.
   
   
2. The RETR command retrieves a particular message number.
   
   
3. The DELE command deletes a particular message number. Refer to the following POP3 example for the usage of these commands.
   
   
4. 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.

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.

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 newsgroup 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 (e.g.: 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.

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.

4.4.2 NNTP Example

In the following NNTP session, the client connects to the NTTP server, requests a list of all newsgroups, selects newsgroup comp.lang.c, requests the current (first) article, requests 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.

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 sometimes 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 response 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.

Occasionally, 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 of response for code 101.
   100 last line of response.

4.5.1 FTP Protocol

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.

The client is now "logged onto" the FTP server. Several commands can now be sent including:

1. 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".
   
   
2. 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.
   
   
3. 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 transferring binary files.
   
   
4. 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 164.112.131.70, we use the port command PORT 165,113,131,70,24,2.
   
   
5. 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 transferred.
   
   
6. 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 transferred. Note that most anonymous FTP sites do not allow uploading.
   
   
7. The QUIT command logs off of the FTP server.

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@thelouve.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 it 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.

4.6 HTTP

The HTTP (Hyper Text Transfer Protocol) protocol defines the interaction 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 interpret 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 ISP's (Internet 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.

4.6.2 HTTP Example

Suppose that the following Web page HELLO.HTM is on the MarshallSoft Web site at www.marshallsoft.com.

<HTML> <HEAD>
<TITLE> MarshallSoft Computing, Inc. </TITLE> </HEAD>
<H1> Hello </H1>
Hello, world!
</BODY> </HTML>

The following exchange 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: <HTML> <HEAD>

S: <TITLE> MarshallSoft Computing, Inc. </TITLE>

S: </HEAD>

S: <H1> Hello </H1>

S: Hello, world!

S: </BODY> </HTML>

C: (Disconnects)

It is up to the HTTP client to interpret the HTML lines, for which knowledge of the HTML specification is necessary. Note that the client disconnects after receiving each page.

4.7 Echo

The echo server accepts TCP connections on well known port 7. It echoes everything it received back to the originator until the connection is closed by the client.

The primary purpose of the ECHO protocol is as a diagnostic tool.

4.8 TELNET

The TELNET protocol implements a "Network Virtual Terminal". It is used to connect to a specified server on a specified port for sending and receiving ASCII commands and server responses. Most commonly, TELNET is used to connect to your shell account on your ISP.

The primary TELNET RFC's are:

RFC 854 : TELNET PROTOCOL SPECIFICATION

RFC 855 : TELNET OPTION SPECIFICATIONS

Also see the comments in TELNET.C for a list of additional RFC's.

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 RFC's from the Internic for detailed protocol information. Also experiment with the appropriate example program. Unfortunately, there is no substitute for trial and error! Other good resources 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.

6.0 Summary

6.1 WIL4C Function Summary

Refer to the WIL4C Reference Manual (WIL_REF) for detailed information on the communications and support functions.

There are 59 functions in the WIL library. Also examine the usage of these functions in the example programs.

            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 number.

wilCancelBlocking : Cancels blocking call.

wilCloseSocket : Close socket.

wilConnect : Initiate connection to remote port.

wilDataIsReady : Is socket readable (data is ready).

wilDebug : Returns debug 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.

wilMakeAddr : Compute IP address from dotted text format.

wilMakeDotted : Construct IO address in dotted text format.

wilParseDecimal : Parse decimal response code.

wilPeekSocket : Peek into socket.

WilPing : Ping a destination IP address.

wilReadLine : Read line terminated with linefeed.

wilReadOOB : Read Out-Of-Bound data.

wilReadSocket : Read from socket.

wilReadString : Read string from socket.

wilReadUdpSocket : Read from UDP 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.
    wilWriteUdpSocket : Write to UDP socket.
         wilUdpSocket : Create UDP socket.