Teach Yourself ActiveX in 21 Days

• HTML.OCX—Hypertext Markup Language Control
• HTTPct.OCX—Hypertext Transfer Protocol Client Control
• SMTPct.OCX—Simple Mail Transfer Protocol Client Control
• POP3ct.OCX—Post Office Protocol Client Control
• NNTPct.OCX—Network News Transfer Protocol Client Control
• FTPct.OCX—File Transfer Protocol Client Control
• State Logic
  • The Control State
  • The Protocol State
    • FTP
    • HTTP
    • POP
  • The DocObject States
• Summary
• Q&A
• Workshop
• Quiz

— 20 —

Using the Internet Control Pack

Microsoft licensed a set of controls from NetManage that allows programmers to add standard Internet features to their applications. Supported protocols of this control pack include FTP, NNTP, SMTP, POP3, HTTP and, of course, straight WinSock.

Any IDE that is an OLE container application and supports custom controls can use this control pack. Some of these programs include Visual Basic, Access, Visual FoxPro, Visual C++, and many more. For demonstration purposes (and because of its similarity to VBScript, with which you are familiar), you will use Visual Basic.

You will use Visual Basic to create several Internet projects, including:

• A POP3 mail checker
  
  
• An SMTP mail-sending utility
  
  
• An HTML Web browser
  
  
• An HTTP keyword-search utility
  
  
• An FTP directory-information utility
  
  
• An NNTP newsgroup-information utility
  
  

HTML.OCX—Hypertext Markup Language Control

The HTML control is a powerful Web-page-viewing tool that can request, retrieve, parse and display a Web document. Figure 20.1 shows the HTML control loaded in Visual Basic .

---

Note
If you are creating a project for distribution, make sure the dependent files, including NMOCOD.DLL, NMORENU.DLL, NMSCKN.DLL, NMW3VWN.DLL, and HTML.OCX,are distributed as well.

---

Figure 20.1. The HTML control , shown in the lower-right corner of the tool box.

To learn to use the functions of the HTML control within Visual Basic, you will create a basic Web-browser program using the following steps:

1. Create a new form with an HTML control, then add a simple text box and command button (see Figure 20.2). The user enters his URL in the text box and, after pressing the command button, the URL is launched in the HTML control.
   
   
2. Code the action to be taken (in this case, when the user presses the command button). You need only add code on the command button's Click event:
   
   

   
   
   
   Private Sub cmdGo_Click()
   
   
   
    HTML.RequestDoc txtURL.Text
   
   
   
   End Sub

3. Enable different status indicators. In Figure 20.2, you added a list box named lstStatus. You will now add status indicators to this list box to log certain activities; add the code as follows:
   
   

   
   
   
   Private Sub HTML_BeginRetrieval()
   
   
   
    lstStatus.AddItem "Retrieving: " & txtURL.Text
   
   
   
   End Sub
   
   
   
   Private Sub HTML_DoRequestDoc(ByVal URL As String, ByVal Element  As HTMLElement, ByVal
   
   
   
    DocInput As DocInput, EnableDefault As Boolean)
   
   
   
    lstStatus.AddItem "Connecting to: " & txtURL.Text
   
   
   
    txtURL = URL
   
   
   
   End Sub
   
   
   
   Private Sub HTML_EndRetrieval()
   
   
   
    lstStatus.AddItem "Document Complete"
   
   
   
   End Sub

   
   
   To see a working example of this sample application, refer to the \vb4\icp- directory on the enclosed CD-ROM.
   
   

---

The HTML Control's RequestDoc Method

HTML.RequestDoc URL

The HTML.RequestDoc method is used to retrieve and display the HTML document returned by an HTTP request from the supplied URL. For example, HTML.RequestDoc "http://www.microsoft.com/activex" will retrieve and display Microsoft's ActiveX home page.

---

Figure 20.2. A simple Web browser application using Visual Basic and the ICP HTML control .

For the basic meat and potatoes of a Web browser, that's all there is to it. However, several additional properties, methods and events are available within the HTML control; I suggest you acquaint yourself with them to add powerful functionality to the display of your Web content.

HTTPct.OCX—Hypertext Transfer Protocol Client Control

The HTTP control (Figure 20.3) can perform low-level HTTP commands with the GET and PUT methods. It does not, however, perform any kind of interpretation on the markup.

Figure 20.3. The cursor is pointing to the HTTP control in the lower-right corner of the tool box.

The HTTP control is one of those tools that is useful for digging up meta-information (information about information). Even if you've never used a professional Web browser, you've seen the basics of what they can do in the previous sample (see Figure 20.2).

---

Note
Remember: HTTP is a protocol; HTML is a document format.

---

Millions of individuals and organizations that want to distribute information have put graphical information presentations on the Web. Although these presentations are very end-user-friendly, there is no predefined, global, everybody-does-it format for these displays. There is, however, a predefined, global, everybody-uses-it stream for transferring these displays; it's called HTTP.

By tapping into the HTTP stream, you can capture information within the document or data being transferred. Then you can perform programmatic functions on that information, such as a keyword search.

To demonstrate how the HTTP control works, let's create a simple application. This application takes a user-defined URL and searches for instances of a user-defined keyword within the URL's pages. Follow these steps to create the application:

1. Create a new project in Visual Basic. Add a form with text boxes, list boxes, and labels, as shown in Figure 20.4.
   
   
2. Add your standard features (such as Ctl+X and File | Exit commands for closing the application). Then add functionality to the program. The function of the application you are creating is to send a request for a Web document, and to search the resulting character stream for occurrences of the keyword.
   
   
3. Code the command button. When the form is initially run, it waits for the user to enter a URL into the text bar and to press the Add button. This will add this site and its results to the list of search results. The code to do this is contained within the Add button's Click event:
   
   

   
   
   
   Private Sub cmdAddSite_Click()
   
   
   
    lblStatus = "Searching: " & txtURL.Text
   
   
   
    HTTP.URL = txtURL.Text
   
   
   
    HTTP.GetDoc txtURL.Text
   
   
   
    lstURLs.AddItem txtURL.Text
   
   
   
    lstHitCount.AddItem "Searching"
   
   
   
   End Sub

   
   
   Now, when the user clicks the Add button (line 1), the status bar indicates that a search is in progress (line 2). In lines 3 and 4, the HTTP control is told to request the Web page at the URL in the text box. When this request is made, one of two things happens: either it works or it doesn't.
   
   
4. If it doesn't work, put a line in the search results and the status bar defining the error as reported by the HTTP_Error event:
   
   

   
   
   
   Private Sub HTTP_Error(Number As Integer, Description As String,  Scode As Long, Source As 
   
   
   
   String, HelpFile As String, HelpContext As Long, CancelDisplay As Boolean)
   
   
   
    lblStatus.Caption = Description
   
   
   
    lstURLs.AddItem txtURL
   
   
   
    lstHitCount.AddItem "Error"
   
   
   
   End Sub

5. If it does work, the DocOutput event will fire. Within this event, code the process that reads the incoming data into a buffer, and add the process that scans the buffer for the keyword.
   
   In the following example, look for the state to change to Data mode. Then scan whatever comes in for the value of the Text property of the text box (such as a user-defined keyword). If there's a match, log it to the results display. When the state changes to Transfer Complete mode, log that to the display as well.
   
   

   
   
   
   Private Sub HTTP_DocOutput(ByVal DocOutput As DocOutput)
   
   
   
    Select Case DocOutput.State
   
   
   
    Case 0 'No Activity
   
   
   
    Case 1 'Beginning Transfer
   
   
   
    Case 2 'DocHeader Transfer Beginning
   
   
   
    Case 3 'Data transferred
   
   
   
    DocOutput.GetData Content, 8
   
   
   
    If InStr(1, Content, txtKeyword.Text, 1) Then
   
   
   
    lstURLs.AddItem HTTP.URL
   
   
   
    lstHitCount.AddItem "Match"
   
   
   
    End If
   
   
   
    Case 4 'Error
   
   
   
    Case 5 'Transfer Complete
   
   
   
    lstURLs.AddItem HTTP.URL
   
   
   
    lstHitCount.AddItem "Finished"
   
   
   
    End Select
   
   
   
   End Sub

   
   
   To see a working example of this sample application, refer to the \vb4\icp- directory on the enclosed CD-ROM.

---

Note
If you are creating a project for distribution, make sure the dependent files, including NMOCOD.DLL, NMORENU.DLL, NMSCKN.DLL, and HTTPct.OCX are distributed as well.

---

Figure 20.4. The shell for a Web-search application using Visual Basic and the ICP HTTP control.

Using this code as is, you can create a basic application that will search Web sites for key phrases. Companies such as Yahoo!, WebCrawler and even Microsoft use these kinds of search methods to find content, without having to deal with the variations in individual styles of presentation.

SMTPct.OCX—Simple Mail Transfer Protocol Client Control

The SMTP control (see Figure 20.5) can perform both basic and high-level e-mail sending functions. Using this control, you can make various e-mail reporting functions automatic, acquiring information for the message programmatically through Visual Basic.

Figure 20.5. The cursor is pointing to the SMTP control in the lower-right corner of the tool box. Also, an SMTP control is shown loaded onto the form .

To demonstrate the use of this control, let's make a simple mail-sending program . It will use basic fields (To, From and Subject), and will have a multiline text box for the message body. The user will have to supply the name of the mail server. To create this application, perform the following steps:

1. Create a Visual Basic form with text boxes, labels, and so on (see Figure 20.6). These text boxes will define the areas within which the user will enter the header and body information for the message.
   
   

   ---

   Note
   If you are creating a project for distribution, make sure that the dependent files, including NMOCOD.DLL, NMORENU.DLL, NMSCKN.DLL, and SMTPct.OCX are distributed as well.
   

   ---

   Figure 20.6. The shell for a mail-sending utility using Visual Basic and the ICP SMTP control .
   

2. Add some code behind the Send button. When the user finishes composing his message, he presses the Send button; the code that you have added launches a series of activities that transmits the message from the user to the destination e-mail address.
   The code behind the Send button looks something like this:
   
   

   
   
   
   Private Sub cmdSend_Click()
   
   
   
   'Fill in the Document Headers
   
   
   
    With SMTP.DocInput.Headers
   
   
   
    .Add "From", txtFrom.Text
   
   
   
    .Add "To", txtFrom.Text
   
   
   
    .Add "Subject", txtFrom.Text
   
   
   
    End With
   
   
   
   'Send the Message
   
   
   
    SMTP.RemoteHost = txtMailHost.Text
   
   
   
    SMTP.SendDoc , , txtMessage.Text
   
   
   
   End Sub

   
   
   In the first part of this code, the document headers are defined. These are the meat and potatoes of an Internet mail message. They are also the foundation for other network applications (such as HTTP and MIME).
   In the second part of the code, the SMTP control connects to the mail server and sends the text of the message.
   To see a working example of this sample application, refer to the \vb4\icp- directory on the enclosed CD-ROM.
   
   

---

Note
For the full text of the SMTP protocol, including some of the magical optional headers, refer to RFC-822 (http://ds0.internic.net/rfc/rfc822.txt)

---

Mail headers must include From and To headers, should include a Subject header, and the last section can be the body of the message. There are some additional, optional headers: CC to send a carbon copy to another recipient, BCC to send a blind carbon copy, Return-Receipt-To to receive confirmation of a message receipt, or Reply To to allow the receiver reply to an address other than the originator's.

Some interesting headers with which you can work include:

• X-Mailer—Defines which mailer program is sending the message.
  
  
• Keywords—Defines a few words, relative to the message topic, from which a search can be performed quickly.
  
  
• Comments—Allows an area in which miscellaneous notes can be embedded in the message.
  
  
• Content-Type—Allows for MIME-encoded multimedia mail.
  
  

POP3ct.OCX—Post Office Protocol Client Control

In the previous section, you used SMTP to send an e-mail message to another person on the Net. What you might not realize is that your message probably didn't go directly to the addressee's computer; rather, it probably went to that person's post office, where it waited until the user retrieved it using his preferred mail program (see Figure 20.7).

Figure 20.7. Several different mail programs are available, including Microsoft Internet Mail and News and Microsoft Exchange.

If you use an e-mail program such as Eudora, Internet Mail and News, or Microsoft Exchange (see Figure 20.7), you probably download your mail from a mail server (your post office), then read it when you're darn good and ready.

Using an e-mail program is the easy way to read mail, as opposed to checking your mail via telnet and a UNIX shell. When you access your mail server with those kinds of Rlogin (remote login) utilities, you are reading your mail directly from the server. To retrieve the messages and read them at your leisure offline, you need to use an e-mail client that supports the POP3 Post Office Protocol .

The POP3 control is used to retrieve mail or information about mail from the an Internet server. To demonstrate the use of this control, let's create a simple application to check mail and see how many messages are waiting.

1. Create a Visual Basic form with text boxes, labels, and so on (see Figure 20.8).
   
   

   ---

   Note
   If you are creating a project for distribution, make sure the dependent files, including NMOCOD.DLL, NMORENU.DLL, NMSCKN.DLL, and POP3ct.OCX, are distributed as well.
   

   ---

   Figure 20.8. The shell for a mail-checking utility using Visual Basic and the ICP POP3 control .
   

2. Code the procedures that occur when the user clicks the command button labeled Check Mail.
   In this sample, the user supplies certain basic information (UserID, Password and Mail Host). He then presses the Check Mail button whenever he wants to check his e-mail. As with the earlier samples in this chapter, you are making this application to perform one function—check the mail. Therefore, the code that starts the process is in the Check Mail button.
   
   

   
   
   
   Private Sub cmdCheckMail_Click()
   
   
   
    POP3.Connect txtRemotehost.Text
   
   
   
   End Sub

3. This begins the logon process. When the systems connect, the ProtocolStateChanged event fires and returns a value of 1 (Authorizing). At this point, you are connected to the POP server, but you need to fire off your authentication before you can do anything there.
   
   

   ---

   Note
   If you want to see what goes on in the background of an SMTP transfer, use Telnet to connect to your mail host on port 25. Then you can log in manually (with your logon name and password). To see what commands your mail host supports, Enter help or ? when prompted. (Remember: be very, very careful.) You can also perform this on port 21 to an FTP server and, to some extent, with your UseNet news server on port 119 without even logging in.
   

   ---

4. Monitor the state of the protocol to determine the proper time to send your UserID and Password for the server to authenticate. This is conducted using a bit of code in the ProtocolStateChanged event like so:
   
   

   
   
   
   Private Sub POP3_ProtocolStateChanged(ByVal ProtocolState As Integer)
   
   
   
   If ProtocolState = 1 Then
   
   
   
    POP3.Authenticate txtUserID.Text, txtPassword.Text
   
   
   
   End If
   
   
   
   End Sub

5. Code the way the computer handles the response when the server tells it how many messages are waiting.
   
   When you are logged on and authenticated, the server sends you information—such as the number of messages waiting. Retrieve this information from the RefreshMessageCount event. This event fires immediately after logon:
   
   

   
   
   
   Private Sub POP3_RefreshMessageCount(ByVal Number As Long)
   
   
   
    lstStatus.AddItem "Message Count: " & Number
   
   
   
   End Sub

   
   
   To see a working example of this sample application, refer to the \vb4\icp- directory on the enclosed CD-ROM.
   
   

Now that you are familiar with the POP3 and SMTP controls, you should be able to create your own e-mail programs instead of requiring bulky and expensive third-party programs.

NNTPct.OCX—Network News Transfer Protocol Client Control

In the previous section, you used SMTP to send an e-mail message to another person on the Net and POP3 to retrieve your own messages. You had to use two different controls because the sending and receiving of private e-mail occurs through two different protocols. News messages only require one protocol (and thus, one control) because they are not sent to one individual; they are broadcasted to anyone who happens to be listening.

---

Note
Microsoft operates a public news server at news://msnews.microsoft.com. This server provides a forum for users of Microsoft products (in other words: everybody) to discuss and receive tech support on Microsoft products and technologies. Microsoft even has a cadre of MVPs (Most Valued Professionals) who unofficially monitor these groups and provide assistance.

---

If you have Internet access, you probably already have the use of an NNTP, or UseNet news server. Each server makes all incoming messages to a particular newsgroup available to the subscribers of that newsgroup. Each server also broadcasts articles (messages) posted by subscribers and makes them available to all the servers that request it. For this reason, a news provider must either maintain only it's own newsgroups (like Microsoft does), or to accept all news traffic (like most ISP news servers do). These newsgroups can be read by any of the NNTP news readers, of which Microsoft's Internet Mail and News client is only one (see Figure 20.9).

Figure 20.9. Microsoft's Internet Mail and News Client.

The NNTP control is used to post articles to and retrieve articles from a news server. To demonstrate a few of the basic functions of this control, let's make a simple application to log on to Microsoft's news server and report information about the articles available.

1. Create a Visual Basic form with text boxes, labels, and so on (see Figure 20.10).
   
   In the NNTP example, the users enter the news server and name of the newsgroup from which they wish to retrieve message information. When data is entered in both, they press the Check button to poll the server.

   ---

   Note
   If you are creating a project for distribution, make sure the dependent files, including NMOCOD.DLL, NMORENU.DLL, NMSCKN.DLL, and NNTPct.OCX are distributed as well.
   

   ---

   Figure 20.10. The shell for a UseNet meta-information utility using Visual Basic and the ICP NNTP control.
   
   

2. Code how the program will behave when the user clicks the Check button. In this case, the program allows the user to connect to the news server.
   
   To poll the server, connect to it, and provide any UserID and Password information required by your UseNet provider. For the most part, connecting is done simply by coding the connect button as follows:
   
   

   
   
   
   Private Sub cmdCheck_Click()
   
   
   
    NNTP.Connect txtNewsHost.Text
   
   
   
   End Sub

3. Monitor the ProtocolStateChanged event of the NNTP control. After the connection request is made and the remote server responds, the state of the protocol changes. This fires the ProtocolStateChanged event. When this event fires with a protocol state of 1 (Connected), you must have a bit of code that immediately tells the server which group you want to access:
   
   

   
   
   
   Private Sub NNTP_ProtocolStateChanged(ByVal ProtocolState As Integer)
   
   
   
    If ProtocolState = 1 Then NNTP.SelectGroup txtNewsGroup.Text
   
   
   
   End Sub

4. After your program successfully executes the SelectGroup method, the control will respond by firing the SelectGroup event.
   
   

   ---

   Note
   Remember: a method is the way you tell a control to do something; an event is the way the control tells you it did something.
   

   ---

   
   
   
5. After you tell the server which group you want to access, the server responds with information about that group, including the number of the first article, the number of the last article, and the total number of articles it is holding for that group. Retrieve that information in the SelectGroup event. To do this, code the NNTP_SelectGroup event as follows:
   
   

   
   
   
   Private Sub NNTP_SelectGroup(ByVal groupName As String, ByVal firstMessage As  Long, ByVal lastMessage As Long, ByVal 
   
   
   
   msgCount As Long)
   
   
   
    lstNews.AddItem "GroupName: " & groupName
   
   
   
    lstNews.AddItem "First Msg: " & firstMessage
   
   
   
    lstNews.AddItem "Last Msg: " & lastMessage
   
   
   
    lstNews.AddItem "Total: " & msgCount
   
   
   
    NNTP.Quit
   
   
   
   End Sub

6. You're ready to test the project. If you are not already connected to the Internet, get there—then run the project. In the News Server box, enter msnews.microsoft.com in the newsgroup box, enter MSNBC.BreakingNews.
   
   In this example, you performed the simplest of news functions. Explore the power of this utility in the retrieving and posting of articles, and in the decoding, formatting and displaying of news postings.
   
   To see a working example of this sample application, refer to the \vb4\icp- directory on the enclosed CD-ROM.
   
   

---

UseNet News
Tens of thousands of UseNet newsgroups are available on most commercial services. Of those, several thousand are active. Many have traffic as high as several hundred messages per day.
Many professionals in a broad spectrum of disciplines use UseNet to keep in touch and to discuss the latest concerns in their field. Search tools (such as DejaNews) provide users with a powerful means of researching any topic. It's all discussed on UseNet.

---

FTPct.OCX—File Transfer Protocol Client Control

In the previous section, you used NNTP to retrieve information about a newsgroup (and you learned that this type of data is called meta-information). In this section, you will learn how to extract meta-information from an FTP server.

FTP servers are used to make files accessible over the Internet for individuals or the public. In fact, many users with dial-up accounts set up their own private FTP sites on their local machines to make files available for a short period of time (only while they're online, for example).

When you post information to an any kind of Internet server (be it HTTP, FTP, Gopher, or whatever), you will usually post it via FTP. Several very popular FTP utilities are available for this operation. One of the best is the WinSock FTP-32 client (see Figure 20.11). In fact, most Web browsers, including Microsoft Internet Explorer and Netscape Navigator, already contain FTP client capabilities.

Figure 20.11. The WinSock FTP-32 client application .

The Internet Control Pack's FTP control is a client control, not a host control. That means it is used to retrieve files, not make them available. However, with this control, you can add FTP retrieval features into your own applications—making the Internet portion of any application you may write virtually invisible to the user. The following illustrates this:

From an MS-DOS command prompt, type FTP.exe FTP.Microsoft.Com. The output will be as follows:

Connected to ftp.microsoft.com



220 ftp Microsoft FTP Service (Version 2.0)



User(ftp.microsoft.com:(none)): _

Respond to the User prompt as Anonymous. The output will be as follows:

Password: _

Respond to the Password prompt with your e-mail address (user@domain.net). The output will be as follows:

230-This is FTP.MICROSOFT.COM please read the file index.txt for additional  details.



230 Anonymous user logged in.



ftp>

Quit the FTP session by typing Quit. The output will be as follows:

C:\Windows> _

Logging on to and off of an FTP server using the command line involves a great many steps. Placing those, or any other, processes in a graphical environment can greatly reduce the intimidation factor involved in getting your application accepted by potential users.

The FTP client control is terrific when you're building an Internet application that demands minimal user interaction. Command-line (see Figure 20.12) and graphical FTP (see Figure 20.11), as done today, is intimidating to users who are not familiar with basic Internet features such as directory trees and client/server connections.

Figure 20.12. The Windows 95 Command Line FTP Client .

The FTP control is used to upload and download files from an FTP server. To demonstrate the basic functions of this control, let's create a simple application to log on to Microsoft's FTP server and report information about the available files. Follow these steps:

1. Create a Visual Basic form with text boxes, labels, and so on (see Figure 20.13).
   
   

   ---

   Note
   If you are creating a project for distribution, make sure the dependent files, including NMFTPSN.DLL, NMOCOD.DLL, NMORENU.DLL, NMSCKN.DLL, and FTPct.OCX, are distributed as well.
   

   ---

   Figure 20.13. The shell for an FTP directory-information utility using Visual Basic and the ICP FTP control.
   

2. After the objects have been placed on the form, add the code that starts the process. This happens after the users have entered their data in the text boxes and pressed the Connect button. Behind that button is one command:
   
   

   
   
   
   Sub cmdConnect_Click
   
   
   
    FTP.Connect txtFTPServer.Text
   
   
   
   End Sub

   
   
   In this example, users specify a server, their login information, and a directory on that server. When they click the Connect button, information about that directory is displayed in the window. The login process for the FTP control works the same as if it were being conducted from the command line.
   
   

   ---

   Warning

   Different types of FTP servers respond differently. You might have to refer to the documentation of the FTP protocol (RFC 959)

   ---

   ---

   Note
   FTP Protocol (RFC 959)
   

   
   

   
   
   
   http://ds0.internic.net/std/std9.txt

   
   Although every FTP server has its own custom prompts and menus, each must conform to this FTP standard.
   

   ---

   
   
   
3. Monitor the protocol for a change in its state. When the control enters the Authorizing state, respond with the UserID and Password for this connection.
   
   To perform this logon step, add a bit of code to the FTP_ProtocolStateChanged event like so:
   
   

   
   
   
   Private Sub FTP_ProtocolStateChanged(ByVal ProtocolState As Integer)
   
   
   
   Select Case FTP.ProtocolState
   
   
   
    Case 0 'Idle
   
   
   
    Case 1 'Authorizing
   
   
   
    lblStatus.Caption = "Authorizing: " & txtPassword.Text
   
   
   
    FTP.Authenticate txtUserID.Text, txtPassword.Text
   
   
   
    Case 2 'Authorized
   
   
   
   End Select
   
   
   
   End Sub

4. Add a bit of code to determine when your connection is authenticated. In this case, go immediately to the user-defined directory on the FTP server. As soon as the FTP_Authenticate event fires, respond by telling it which directory you want to visit with the FTP.ChangeDir method like so:
   
   

   
   
   
   Private Sub FTP_Authenticate()
   
   
   
    FTP.ChangeDir txtFTPDir.Text
   
   
   
   End Sub

5. Monitor the FTP_ChangeDir event. This event fires as soon as the server enters the requested directory. When this happens, request a listing of the current directory using the FTP.List method like so:
   
   

   
   
   
   Private Sub FTP_ChangeDir()
   
   
   
    FTP.List "*"
   
   
   
   End Sub

   ---

   Warning

   Not all FTP servers work the same. On some, the List method doesn't work, but the PrintDir method does. Use the DocObject properties and methods whenever possible to accommodate these variations. The DocObject will allow you to take any and all data that is returned, but the PrintDir method may not return any data at all. It is best to code procedures that will analyze the DocObject properties and identify what type of data is being returned from the server.

   ---

6. After you invoke the FTP.List method, monitor the FTP_ListItem event. This event fires as each item in the list comes down the pipe. These items are passed through the control as an FTPDirItem object. The FTPDirItem is an object that is specific to the FTP client control. In this example, you are retrieving the value of the Detail property from the FTPDirItem. Add this Detail property with a bit of code in the ListItem event like so:
   
   

   
   
   
   Private Sub FTP_ListItem(ByVal Item As FTPDirItem)
   
   
   
    If ItemDetail <> "" Then lstFTP.AddItem Item.Detail
   
   
   
   End Sub

   
   
   To see a working example of this sample application, refer to the \vb4\icp- directory on the enclosed CD-ROM.
   
   

---

Warning

If you are working with the ICP FTP control, you may encounter errors when you attempt to manipulate the FTPDirItem through your code. If you do, try registering the FTP control and its dependent files with the RegSvr32.exe utility. This will register the OLE controls in your operating system as well as your development environment. Also, ensure that the FTP control and any dependent libraries are referenced in your development's OLE references. In Visual Basic, this can be done from the menu using the Tools | References menu option.

---

Again, the real power of a control, such as the FTP client, is the retrieval of meta-information instead of just raw data. With this control, you can produce other reports, such as an Archie report or even the files themselves. This is an automatic or manually updated database that contains listings of the billions of megabytes of redundant files found on remote FTP servers. When you query this utility for a file, it will be able to give you several options to help you find it.

State Logic

The ICP begs to use state logic . What are the states used in these controls?

The ICP makes uses of three different kinds of states:

• The state of the control
  
  
• The state of the protocol
  
  
• The state of the DocObjects
  
  

The Control State

The state of the control is returned in the control's State property (such as FTP.State). These control states are:

1. Connection requested
   
   
2. Resolving Host
   
   
3. Host Resolved
   
   
4. Established Connection
   
   
5. Disconnecting
   
   
6. Idle
   
   

The Protocol State

The state of the protocol is returned in the control's ProtocolState property (such as FTP.ProtocolState). Different protocols share similar states; the following states are specific to the named protocols:

FTP

• 0—Idle
  
  
• 1—Authorizing
  
  
• 2—Authorized
  
  

HTTP

• 0—Idle
  
  
• 1—Connection Established
  
  

POP

• 0—Idle
  
  
• 1—Authorizing
  
  
• 2—Authorized
  
  
• 3—Quitting
  
  

The DocObject States

The state of the items being transferred are returned in the object's State property (such as DocInput.State).

• 0—Idle
  
  
• 1—Initiating Transfer
  
  
• 2—DocHeader Transfer
  
  
• 3—DataBlock Transfer
  
  
• 4—Error During Transfer
  
  
• 5—Transfer Complete
  
  

Summary

In this chapter you have been introduced to the controls distributed with the Microsoft Internet Control Pack. These ActiveX controls are useful for performing standard Internet functions—such as news, mail and file transfers—through a custom interface. Among other things, these controls allow the programmer to add Internet functions to the background of his own applications—which means the user need not be Internet-savvy to benefit from the Net.

With the FTP control you can perform file transfer functions.

With the NNTP control, you can search for and retrieve articles from UseNet news services.

With the SMTP and POP3 controls, you can send and receive e-mail with anyone that has an Internet address.

With the HTTP control you can perform Web functions, such as posting information to a CGI script or retrieving Web documents.

With the HTML control you can retrieve, parse, and display Web documents.

Q&A

• Q What .DLL's need to be installed on a user's machine to work with the Internet Control Pack?
  
  
• A Each control in the ICP needs its .OCX file (of course).
  
  The WinSck.OCX needs only itself and the NMSCKN.DLL.
  
  Each of the rest needs NMSCKN.DLL, NMORENU.DLL,and NMOCOD.DLL (in addition to its .OCX).
  
  The FTP control needs the additional NMFTPSN.DLL.
  
  The HTML control needs the additional NMW3VWN.DLL.
  
  
• Q What is the DocObject?
  
  
• A The DocObject, as it relates to the Internet Control Pack, is a block of data that is transferred over the Internet. Depending on what information the server is sending, you can reference its properties to identify properties such as headers, file sizes, filenames, and so on.
  
  
• Q What are DocInput/DocOutput
  
  
• A The DocInput and DocOutput objects (and their properties, methods and events) are streams of incoming and outgoing Internet data. They are common to all controls in the ICP, and are the context within which the Object Model for Scripting is implemented within applications (as opposed to within HTML).
  
  
• Q With all these client controls, the next logical step is to build servers and hosts for these protocols. How is this done with the ICP?
  
  
• A The WinSock control is the one to use when building a server (applications that wait for connections rather than initiating them). This control taps directly into the Windows interface from the TCP/IP stream. To build a server for one of the established protocols (such as SMTP or POP3), you must build a WinSock-based application that can properly respond to the SMTP and POP3 standard commands. You can do this with a protocol-specific control that references the WinSock library, or a WinSock control that references the WinSock library.
  
  

---

Fax-2-Fax
You are, by now, familiar with the standard TCP/IP protocols—SMTP/POP3, NNTP, FTP, HTTP, and so on. A wonderful benefit of the WinSock control is the ability it gives a programmer to produce his own "proprietary" protocols.
In 1995, Lawrence Kern, a Telecom Corridor CPA, and a couple of Telecom lawyers from the pre-regulation days got together to address the opportunities in telephony on the emerging Internet. They began with the idea that a fax transmission is not all that different from an e-mail or other message transmission; thus it could be sent over the Internet better, faster, cheaper, quicker and more reliably than over long-distance telephone lines.
The system they eventually developed went through many trial phases before a final demonstration of the process was completed. They wanted to determine which protocol to use to transmit a fax image and its associated data over the Net. Several were tried, including FTP, SMTP/POP3, and a brief try with uuencoding as is used in NNTP.
No pre-established protocol fit the need. Although the development of this project was before the development of ActiveX, there were still several utilities out there that could be used to program against the WinSock interface. Using a shareware .VBX control, Mr. Kern and his team were able to create their own proprietary protocol. Their product was a little bit SMTP, a little bit FTP, and a little bit rock-and-roll.
In the few years since the Fax-2-Fax network was researched and developed, many other fax services have become popular. Among these are The Internet Phone Company (www.tpc.int) and Faxaway (www.faxaway.com). Although these services provide a fast and economical e-mail-to-fax gateway, the Fax-2-Fax network remains the best interface for completing a fax transmission to a remote fax over the Internet.
By forsaking public standards, they were able to create the right tool for the job. They showed tremendous innovation and initiative to create something new. This is the same spirit that brought us things like the Internet, the Public Service Telephone Network, railroads and sliced bread. This is what you can do with the WinSock control.

---

Workshop

Create an SMTP utility that will automatically mail copies of your Autoexec.Bat, Config.SYS, and Win.INI files to yourself with Delete Me in the subject line. Observe the potential risks. Add a POP3 control that will delete the message you just sent to yourself.

Quiz

---

Note
Refer to the Appendix, "Answers to Quiz Questions," for the answers to these questions.

---

1. What two procedures must be invoked to log on to an FTP server?
   
   
2. What three values must be loaded into the SMTP.DocInput.Headers object to send a message?
   
   
3. What method is invoked to change directories during an FTP session?
   
   
4. What method must be invoked to return the first, last and total article numbers from an NNTP server?
   
   
5. What method is used to log on to an NNTP server?
   
   
6. Must a password be used with all news servers?
   
   
7. What event returns the message count from a POP3 server?
   
   
8. What state must a DocObject be in to retrieve the headers information?
   
   
9. The State property of what object identifies whether or not a hostname has been resolved?