Winsock Interface Library
April 4, 2000
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2000
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice : 256-881-4630
FAX : 256-880-0925
email : email@example.com
web : www.marshallsoft.com
MarshallSoft is a member of the Association of Shareware Professionals
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1.1 Documentation Set2 Internet Tutorial
2.1 Networks3 Internet Programming 3.1 Internet RFC's
2.2 Conceptual Architecture
2.3 Internet Protocol Address
2.4 Example Network
2.5 Dial Up Connections
3.2 Protocol Layers4 Internet Protocols
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.1 Finger Protocol5 Problems
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
6.1 WIL Function Summary
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:
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.
The complete set of documentation consists of three manuals in three formats. This is the second manual (WIL_USR) in the set.
Each manual comes in three formats:
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:
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:
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.
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.
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.
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.
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.
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
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.
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:
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:
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 | +-------+--------+ | +-------+--------+
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.
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 "188.8.131.52" 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.
A socket is a small integer number used to identify the endpoint for TCP/IP communications. It is the fundamental Internet network programming interface.
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.
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.
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.
There are two distinct classes of internet programming - Client side and Server side.
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.
+---+----+ +--------+ | LISTEN +------------+ ACCEPT | +--------+ +--------+
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.
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.
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.
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).
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.
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.
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 */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 16. 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.
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:
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);
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);
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 */
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.
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.
int AsyncSetDebug(int DebugFlag);The programmer should rarely have need to use this function.
#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.
The Finger protocol is a very simple protocol. Three example Finger programs are included:
Also see RFC 1288 for a detailed description of Finger.
Note that not all Internet hosts provide Finger servers, although many do.
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.
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.
If another email is to be sent, go back to step (4) above, otherwise sign off by sending the "QUIT" command.
In the following example, the caller firstname.lastname@example.org sends a 3 line email message to Pierre at email@example.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:<firstname.lastname@example.org>
S: 250 OK
C: RCPT TO:<email@example.com>
S: 250 OK
S: 250 OK
C: first line of email
C: second line of email
S: 250 OK
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.
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".
The client side of the POP3 protocol works as follows:
The client is now "logged onto" the POP3 server. Several commands can now be sent including:
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.
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.
S: +OK 2 1950
C: RETR 1
S: +OK 1050 bytes
S: (1st line of email message 1)
S: (last line of email message 1)
C: DELE 1
S: +OK message 1 deleted
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.
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.
The client side of the NNTP protocol works as follows:
211 1982 18726 21918 comp.lang.c
Refer to RFC 1036 for details on article formats.
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.
S: comp.protocols.tcp-ip 514 819 Y
C: GROUP comp.lang.c
S: 211 1982 18726 21918 comp.lang.c
S: 1st line of current article (#18726)
S: last line of current article (#18726)
S: Article 21918 selected. Use ARTICLE to retrieve article.
S: 1st line of current article (#21918)
S: last line of current article (#21918)
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.
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.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.
The client is now "logged onto" the FTP server. Several commands can now be sent including:
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 firstname.lastname@example.org
S: 230-User Pierre logged on.
S: 230 This site allows read access only!
S: (1st line of directory listing)
S: (last line of directory listing)
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: 226 Transfer complete.
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.
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.
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.
Suppose that the following Web page HELLO.HTM is on the MarshallSoft Web site at www.marshallsoft.com.
<TITLE> MarshallSoft Computing, Inc. </TITLE> </HEAD>
<H1> Hello </H1>
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: <HTML> <HEAD>
S: <TITLE> MarshallSoft Computing, Inc. </TITLE>
S: <H1> Hello </H1>
S: Hello, world!
S: </BODY> </HTML>
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.
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.
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.
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 email@example.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.
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.