gif" BORDER=0 HEIGHT=88 WIDTH=140>

Chapter 30 -- ActiveX Control Reference

Chapter 30 ActiveX Control Reference

The TCP Control
The UDP Control
The FTP Client Control
The HTTP Client Control
The HTML Control
The SMTP Control
The NNTP Control
The POP Control

So far in this section you have been given a whirlwind tour of ActiveX, its implementation, and general characteristics. The remainder of this chapter focuses on showing you different ActiveX Controls, their properties, and their methods.

The TCP Control

The Transmission Control Protocol (TCP) is the first of two principle methods for transmitting data over the Internet today. TCP is a connection oriented protocol most often used for transmitting Internet Protocol (IP) packets over a network. Connection oriented protocols like TCP are responsible for ensuring that a series of data packets sent over a network all arrive at the destination and are properly sequenced. The ActiveX TCP control allows you to easily handle TCP data packets in your applications without knowing much about the details of the TCP protocol.

Properties

Table 30.1 summarizes all the properties available in the TCP control. Not suprisingly, all the data elements required to create a TCP connection are included as properties in this control.

Table 30.1 Summary of Properties in the TCP Control

Property	Purpose
`BytesReceived`	The amount of data in the receive buffer.
`LocalHostName`	The name of the local machine.
`LocalIP`	The Internet Protocol (IP) address of the local machine.
`LocalPort`	The TCP port used by the local machine for this communication.
`RemoteHost`	The name of the remote machine.
`RemoteHostIP`	The IP address of the remote machine.
`RemotePort`	The TCP port used by the remote machine for this communication.
`SocketHandle`	Handle used to communicate with the WinSock layer.
`State`	Returns the current status of the connection.

Before we dive into the properties themselves, consider the basic components of a TCP connection. A TCP connection requires that both the client and the server have both an IP address and a port.

The specified port must not be used by any other application. Many ports are already defined as standard ports and are therefore off-limits to your application. For instance, Web browsers use port 80 to connect to Web servers. Most books about TCP/IP will contain a good list of port numbers that are already spoken for. A good rule of thumb is to use port numbers higher than 1,000-these are mostly free.

Now let's take a look at a few of these properties in a bit more detail.

The RemoteHost, RemotePort, and LocalPort Properties. RemoteHost, RemotePort, and LocalPort are the properties you'll be setting in your programs most often. If the application you're writing is a client that will initiate connections with another application, you'll set the RemoteHost and RemotePort properties to the appropiate host and port. The RemoteHost should be a string with either a domain name (for example, ftp.myhost.com) or a dot format IP address (for example, 198.5.164.222). Set the RemotePort number equal to the port number that the server listens on.

If the application you're writing is a server that will listen for connections from another application, you'll set LocalPort to the port number you want to listen for connections on. (Note that the combination of an IP address and a host name is sometimes referred to as a socket.) The TCP control will take care of setting LocalHost on the client side.

The State Property. The State property stores the current state of the TCP connection. Since State is a read-only property, you'll never set the state of the connection. However, you'll want to use the value of State in all sorts of ways. Table 30.2 summarizes the
values that State may contain.

Table 30.2 Values That State May Contain

Value	Description
`sckClosed`	Default. The socket is closed.
`sckOpen`	The socket is open.
`sckListening`	Listening on the socket.
`sckConnectionPending`	Connection pending.
`sckResolvingHost`	Resolving the host name to obtain an IP address.
`sckConnecting`	Currently connecting.
`sckConnected`	Connected.
`sckClosing`	Another application is closing the socket.
`sckError`	The socket is errored.

Most of the time, your programs will be checking to see if the connection is sckOpen or sckClosed.

Methods

The process of creating a connection involves each of the following steps:

Server listens on a specific port.
Client requests a connection with the server.
Server accepts the connection.
Data is transferred between the client and the server.
Either the client or the server closes the connection.

As you'll see in Table 30.3, the TCP control has a method for each of these actions.

Table 30.3 Summary of Methods in the TCP Control

Method	Description
`Accept`	Accepts an incoming connection.
`Close`	Closes a TCP connection.
`Connect`	Makes a connection request to a distant machine.
`GetData`	Obtains the current block of data.
`Listen`	Creates and listens on a socket.
`PeekData`	Obtains a copy of the current block of data.
`SendData`	Sends data to a remote machine.

Connecting Clients and Servers

So, to implement the server-side of a TCP connection you'll use the following methods:

Listen
Accept

Say you have a TCP control named MyTCPControl. To start the server, your VB code would look something like Listing 30.1.

Listing 30.1 Starting a Server Listening for a Connection

MyTCPControl.LocalPort = 1252 MyTCPControl.Listen

When a client requests a connection to the server, the server must accept the connection. Your VB code for accepting a connection would look like Listing 30.2.

Listing 30.2 Accepting an Incoming Connection

Private Sub MyTCPControl_ConnectionRequest(ByVal requestID As Long) MyTCPControl.Accept requestID End Sub

Note that you'll use a response function for the ConnectionRequest event to obtain the requestID for the connection.

To implement the client-side of a TCP connection, your VB program will contain code like Listing 30.3. Assume that your client program has a TCP control named MyOtherTCPControl.

Listing 30.3 Initiating a Connection with a Server

MyOtherTCPControl.RemotePort = 1252 MyOtherTCPControl.RemoteHost = "198.5.164.222" MyOtherTCPControl.Connect

Sending and Receiving Data

Both clients and servers use the data transmission methods the same way. To send data from one to the other, your code will look something like this:

MyTCPControl.SendData "This is my message"

To obtain received data, you'll usually write a response to the DataArrival event (more on the DataArrival event in a moment). Your code will look something like Listing 30.4.

Listing 30.4 Getting Data From the Input Buffer

Private Sub sktStockServer_DataArrival(ByVal bytesTotal As Long) Dim A MyTCPControl.GetData A DoSomethingWith A End Sub

Note that calling GetData causes the incoming buffer to be emptied. If you want to look at the incoming data without clearing the data, you'll use PeekData in a similar manner.

Events

You've already seen how several of the most important events summarized in Table 30.4 are used.

Table 30.4 Summary of Events in the TCP Control

Event	Description
`Close`	Triggered when the remote machine closes the connection.
`Connect`	Signals that the connection is ready for data transfer.
`ConnectionRequest`	Occurs when a distant machine requests a connection.
`DataArrival`	Fires when new data has arrived in the receive buffer.
`Error`	Signals a background processing error.
`SendProgress`	Used to signal progress of data transfers.

The UDP Control

The User Datagram Protocol (UDP) is the second of two principle methods for transmitting data over the Internet. UDP is a connection-less protocol most often used for transmitting Internet Protocol (IP) packets over a network. Connection-less oriented protocols like UDP are typically employed for sending independent data packets over a network where one packet has no relationship to the next sequential packet. UDP is often used for network services that do not require an ongoing conversation between client and server. UDP senders typically don't care whether the receiver actually receives the message. Instead, UDP is used for discrete transmissions of information where the individual requests and replies are unrelated to one another. The best part about the ActiveX UDP control, however, is the ease with which you can implement these sorts of services without knowing much about the details of the UDP protocol.

Properties

Table 30.5 summarizes all the properties available in the UDP control. All the data elements required to create a UDP connection are included as properties in this control.

Table 30.5 Properties of the UDP ActiveX Control

Property	Purpose
`LocalHostName`	The name of the local machine.
`LocalIP`	The Internet Protocol (IP) address of the local machine.
`LocalPort`	The TCP port used by the local machine for this communication.
`RemoteHost`	The name of the remote machine.
`RemoteHostIP`	The IP address of the remote machine.
`RemotePort`	The TCP port used by the remote machine for this communication.
`SocketHandle`	Handle used to communicate with the WinSock layer.

Consider the basic components of a UDP connection. A UDP connection (like a TCP connection) requires that both the client and the server have both an IP address and a port.

The specified port must not be used by any other application. Many ports are already defined as standard ports and are therefore off limits to your application. For instance, FTP servers use ports 20 and 21 to manage connections between clients and servers. As mentioned in the previous chapter, a good rule of thumb is to use port numbers higher than 1,000 because they are mostly free.

Now let's take a look at a few of these properties in a bit more detail.

The RemoteHost, RemotePort, and LocalPort Properties. Just like the TCP control, the RemoteHost, RemotePort, and LocalPort on the UDP control are the properties you'll be setting in your programs most often. Remember that you'll set the RemoteHost and RemotePort properties to the host and port on which your application will be sending a message. On the receiving application, you'll set LocalPort to the port number you want to receive the message on. (Note that the combination of an IP address and a host name is sometimes referred to as a socket.)

Methods

Unlike the TCP control, there are only a couple of methods in the UDP control. This is because the connection-less UDP protocol is less involved. Table 30.6 summarizes these methods.

Table 30.6 Methods for the UDP Control

Method	Description
`Connect`	Makes a connection request to a distant machine.
`GetData`	Obtains the current block of data.
`SendData`	Sends data to a remote machine.

Because the UDP protocol does not involve an ongoing conversation between two computers, there is no need for the Accept, Listen, and Close methods found in the TCP control. The reasons for this will become more obvious in a moment.

Connecting the Sending and Receiving Application

To implement the receiving side of a UDP connection, you'll do the following:

Set the LocalHost property.
Employ the GetData method when data arrives (for example, when the DataArrival event is triggered).

Say you have a UDP control named MyUDPControl. To program the receiver, your VB code would look something like this:

MyUDPControl.LocalPort = 1252

You will also need to provide an event handler for the DataArrival event (more on this in a moment) as shown in Listing 30.5.

Listing 30.5 Using GetData to Receive UDP Datagrams

Private Sub MyUDPControl_DataArrival(ByVal bytesTotal As Long) Dim ADatagram MyUDPControl.GetData ADatagram DoSomethingWith Adatagram End Sub

To implement the sender side of a UDP connection, you'll do the following:

Set the RemoteHost property
Set the RemotePort property
Send data using the SendData method

When a sending application sends data over the network, you'll initialize the RemotePort and RemoteHost properties and then send data using the SendData method (see Listing 30.6). Assume that your sender program has a UDP control named MyOtherUDPControl.

Listing 30.6 Setting the RemoteHost and RemotePort Properties

Dim ADatagram MyOtherUDPControl.RemoteHost = "198.5.164.222" MyOtherUDPCOntrol.RemotePort = 1252 MyOtherUDPControl.SendData Adatagram

Events

Similar to the method list, the event list for the UDP control is quite sparse. Table 30.7 summarizes the events that are fired by the UDP control.

Table 30.7 Summary of Events in the UDP Control

Event	Description
`DataArrival`	Fires when new data has arrived in the receive buffer.
`Error`	Signals a background processing error.

In the UDP control, these events are triggered in the same way as the TCP control.

The FTP Client Control

The File Transfer Protocol (FTP) provides a simple interface for moving text and binary files over the Internet. FTP is one of the most popular applications used on the Internet today. In fact, many Web browsers support the FTP protocol in addition to other more popular protocols like HTTP. Like most of the other Internet protocols, FTP requires both a client and a server to complete file transfers. The technical details of the FTP protocol are a bit more complicated but, fortunately, the ActiveX FTP client control allows us to avoid knowing much about FTP itself.

Properties

Table 30.8 summarizes all the properties available in the FTP Client control. All the data elements required to transfer a file from an FTP server are included as properties in this control.

Table 30.8 Properties of the FTP Client ActiveX Control

Property	Purpose
`AppendToFile`	Tells whether file operations are appended or not.
`Busy`	`True` if a command is currently in progress.
`DocInput`	Refers to the `DocInput` object which must be set before invoking the `SendDoc` method and conveys information about the progress of the data transfer.
`DocOutput`	Refers to the `DocOutput` object which must be set before invoking the `GetDoc` method and conveys information about the progress of the data transfer.
`EnableTimer`	Tells the kind of timer that is fired by the `TimeOut` event.
`Errors`	Refers to a collection of errors detailing the last error.
`IsAuthenticated`	`True` if authentication has been successfully completed.
`ListItemNotify`	Tells how the `ListItem` event will pass an `FTPDirItem` object.
`LocalFile`	The file name to be used in `GetFile` and `PutFile` operations.
`NotificationMode`	Determines how notification of inbound data will be provided.
`Password`	Sets the password to be used for logging on to an FTP server.
`ProtocolState`	Indicates whether the FTP client is not connected, waiting for authorization to connect, or connected to an FTP server.
`RemoteDir`	The current directory on the remote server.
`RemoteFile`	The file name to be used in `GetFile` and `PutFile` operations.
`RemoteHost`	The host name or IP address of the server to be connected to.
`RemotePort`	The port number used to connect to the FTP server.
`ReplyCode`	The reply code sent by the server in response to requests from the client.
`ReplyString`	The reply string sent by the server in response to requests from the client.
`State`	Used to report the current state of the FTP connection.
`TimeOut`	Tells how long to wait before firing the `TimeOut` event for the type of timer referred to by `EnableTimer`.
`URL`	The Uniform Resource Locator such as `ftp://myhost.com/myfile.txt`.
`UserID`	Sets the user name to be used for logging on to an FTP server.

Now let's take a look at a few of these properties in a bit more detail.

The DocInput and DocOutput Properties.Input and DocOutput objects allow you to control and monitor the incoming and outgoing documents from client to server. These objects also allow the output of one control to be streamed directly to the input of another control.

The EnableTimer Property. Often times, you'll want to take some action after a time-out period has expired. For instance, you might want to ask the user to try again later if a connection took more than 30 seconds to obtain. The EnableTimer property tells what kind of timer is enabled. The kinds of timers that can be enabled are listed in Table 30.9.

Table 30.9 EnableTimer Settings

Kind of Timer	Value
`prcConnectTimeout`	Enables a connect timer. If a connection is not established within the time-out period, the `TimeOut` event is triggered.
`prcReceiveTimeout`	Enables a receive timer. If no data arrives within the time-out period, the `TimeOut` event is triggered.
`prcUserTimeout`	Provides a mechanism for adding user-defined timers. To implement such a timer, add an integer to `prcUserTimeout`.

So, to enable a connect timer, your code would look something like Listing 30.8.

Listing 30.8 Enabling Timers

... '-------------------------------------- '-- Define a custom timeout '-------------------------------------- prcMyCustomTimeout = prcUserTimeout + 1 '-------------------------------------- '--- Enable the connect timeout '-------------------------------------- MyFTPControl.EnableTimer(prcConnectTimeout) = True '-------------------------------------- '--- Disable the receive timeout '-------------------------------------- MyFTPControl.EnableTimer(prcReceiveTimeout) = False '-------------------------------------- '--- Enable a user define timeout '-------------------------------------- MyFTPControl.EnableTimer(prcMyCustomTimeout) = True ...

As is apparent from Listing 30.8, you can enable all, none, or any number of timers as required for your applications.

The ListItemNotify Property. The ListItemNotify property allows you to select whether requests for a directory listing will be passed as an FTPDirItem object through the ListItem event or as data blocks through the DocOutput event. As you'll see in the explanation of the ListItem event, the FTPDirItem makes obtaining details about files and directory entries easy.

The NotificationMode Property. When you use the FTP ActiveX control to transfer data, you can select when you will be notified that data has arrived. Table 30.10 shows the available modes.

Table 30.10 NotificationMode Settings

Value	Meaning
0	Notify when the data transmission has been completed. This is the default setting.
1	The arrival of data causes an event to be continuously fired.

The ProtocolState Property. This property provides protocol-specific information about the state of the connection. For the FTP control, there are three states that the protocol can be in. These states are listed in Table 30.11.

Table 30.11 FTP ProtocolState Values

Value	Meaning
`ftpBase`	The default state of the protocol prior to connecting to an FTP server.
`ftpAuthorization`	Authorization using the `UserID` and `Password` is currently underway.
`ftpTransaction`	Authorization has been completed and the FTP client has identified itself to the FTP server.

The State Property. The State property stores the current state of the FTP connection. Since State is a read-only property, you'll never set the state of the connection. However, you'll want to use the value of State in all sorts of ways. Table 30.12 summarizes the values that State may contain.

Table 30.12 Values That State May Contain

Value	Description
`prcConnecting`	This is the state of the FTP connection after requesting a connection and before receiving acknowlegement of the server.
`prcResolvingHost`	If the `RemoteHost` property is a domain name and not an IP address, the connection will reach this state while the host name is obtained.
`prcHostResolved`	After the host name has been resolved to an IP address, this state is reached.
`prcConnected`	The connection is established.
`prcDisconnecting`	The close connection process has been initiated but has not yet completed.
`prcDisconnected`	When the connection is closed and acknowledgment has been received, the state holds this value. This is also the state of the FTP control when instantiated.

Methods

Most of the action in an FTP session involves sending and receiving files. The methods to accomplish this work are summarized in Table 30.13.

Table 30.13 Methods for the FTP Client Control

Method	Use
`Abort`	Stops the last request for a data transfer.
`Account`	Sends account information to the FTP server. Check the reply string to determine the results.
`Authentication`	Authenticates the user using the `UserID` and `Password` properties.
`Cancel`	Stops a pending request.
`ChangeDir`	Requests that the directory on the FTP server is changed.
`Connect`	Issues a request to the FTP server to open a connection. If a connection is established, the `State` property is set.
`CreateDir`	Creates the specified directory on the FTP server if the user is permitted.
`DeleteDir`	Deletes the specified directory on the FTP server if the user is permitted.
`DeleteFile`	Deletes the specified file on the FTP server if the user is permitted.
`Execute`	Executes a command directly on the server via the RFC-959 `Quote` command.
`GetDoc`	Requests the retrieval of a document identified by a URL and can be used in conjunction with the `DocInput` and `DocOutput` objects and events.
`GetFile`	Obtains a file from the FTP server and places it in the current directory.
`Help`	Obtains a help listing from the FTP server. The `ReplyString` property will contain the results of the request.
`List`	Returns a detailed listing of a FTP server directory. The `ListItemNotify` property indicates how and when this List is returned.
`ListSize`	Lists files by size.
`Mode`	Sets the FTP mode.
`NameList`	Returns a list of filenames from the FTP server.
`NOOP`	Causes the FTP server to reply with an OK in the `ReplyString` property.
`ParentDir`	Asks the FTP server to change directory to the parent of the current directory.
`PrintDir`	Asks the FTP server to reply with the current directory.
`PutFile`	Places a file in server's current directory.
`Quit`	Closes the connection and fires the `Quit` event.
`ReInitialize`	Issues a reinitialize request and obtains a reply in the `ReplyString` property.
`SendDoc`	Requests that a document identified by the URL to be sent to the server and can be used in conjunction with the `DocInput` and `DocOutput` objects and events.
`Site`	Obtains the type of file system supported by the remote system. The reply is found in `ReplyString`.
`State`	Obtains the state of the connection as defined in RFC-959 `Stat` command.
`System`	Requests that the server identify which operating system it requires. Checks `ReplyString` for the response.
`Type`	Sets the type of data to be transferred.

Most of these methods are self-explanatory. However, one merits additional discussion.

The Type Method. You'll use FTP to transfer files that contain all sorts of data. The FTP protocol requires that you identify the type of data contained in the transfer in order to ensure that data is transferred reliably. The values to be passed to the Type method are shown in Table 30.14.

Table 30.14 Transfer Types for the Type Method

Type	Meaning
`ftpAscii`	Text file transfer. This is the default `Type`.
`ftpEBCDIC`	The file to be transferred is an Extended Binary Coded Decimal Interchange file.
`ftpImage`	For transferring image files.
`ftpBinary`	Binary files are transferred using this type.

Getting and Putting Files

The primary purpose of the FTP protocol is to transfer files from client to server and back again. The there are two methods to make this happen using the FTP ActiveX control including:

Using DocInput and DocOutput objects and events with the SendDoc and GetDoc methods
Using the GetFile and PutFile methods

The DocInput and DocOutput approach is available in a number of different controls from the Internet Control Pack, including the HTTP and NNTP controls. So for variety, you'll use the GetFile and PutFile approach in the example program in this chapter.

To send a file from the client to the server, you'll have take several steps after connecting the FTP server. You'll need to set the LocalFile property to the filename that needs to be transferred. Next, you'll set the RemoteFile to the filename to an appropriate name for the distant system. Finally, you'll invoke the PutFile method to complete the transfer. Your code would look something like Listing 30.9.

Listing 30.9 Sending a File to the Server

... '-------------------------------------- '-- Set the two and from file names '-------------------------------------- MyFTPControl.LocalFile = "FileToSend.txt" MyFTPControl.RemoteFile = "SendItHere.txt" '-------------------------------------- '-- Send the file '-------------------------------------- MyFTPControl.PutFile ...

Getting a file from the server to the client to you, you'll use a very similar approach. You'll need to set the LocalFile and RemoteFile as appropriate and then invoke the GetFile method to complete the transfer. Your code would look something like
Listing 30.10.

Listing 30.10 Getting a File From the Server

... '-------------------------------------- '-- Set the two and from file names '-------------------------------------- MyFTPControl.LocalFile = "SendItHere.txt" MyFTPControl.RemoteFile = "FileToSend.txt" '-------------------------------------- '-- Get the file '-------------------------------------- MyFTPControl.GetFile ...

Events

The FTP Control provides numerous events on which your application can take action. Table 30.15 summarizes the events that are fired by the FTP control.

Table 30.15 Summary of Events in the FTP Control

Event	Description
`Abort`	Occurs after the `Abort` method is invoked.
`Account`	Fired after the `Account` method is invoked.
`Authenticate`	Triggered after the `Authentication` method is invoked.
`Busy`	Fires when a command is in progress and when a command is completed.
`Cancel`	Occurs at the completion of the cancellation of a request.
`ChangeDir`	Triggered by the execution of a CWD or an invocation of the `ChangeDir` method.
`CreateDir`	Occurs after the execution of a MKD or by calling the `CreateDir` method.
`DelDir`	Occurs after the execution of a RMD or by calling the `DeleteDir` method.
`DelFile`	Triggered by the execution of a DELE or an invocation of the `DeleteFile` method.
`DocInput`	Fired when data arrives at the control.
`DocOutput`	Triggered when data is sent from the control.
`Execute`	Occurs after the calling the `Execute` method.
`Help`	Occurs after the execution of a HELP or by calling the `Help` method.
`ListItem`	If `ListItemNotify` is set to `true`, this event is triggered by every `ListItem` in a directory.
`Mode`	Triggered by calling the `Mode` method.
`NOOP`	Fired when the NOOP method is invoked.
`ParentDir`	Occurs after the execution of a CDUP or by calling the `ParentDir` method.
`PrintDir`	Triggered by the execution of a PWD or an invocation of the `PrintDir` method.
`ProtocolStateChanged`	Whenever the state of the FTP session changes this event is fired.
`Reinitialize`	Occurs after the execution of a REINIT or by calling the ReInitialize method.
`Site`	Fired by the `Site` event or by invoking the `Site` method.
`State`	Triggered by the execution of the `State` method.
`StateChanged`	Occurs anytime the `State` of the connection changes and therefore the `State` property changes.
`System`	Triggered by the execution of a SYST or an invocation of the `System` method.
`TimeOut`	Occurs when a given event fails to occur within the time period specified in the `TimeOut` property.
`Type`	Fired after the `Type` method has been called.

Let's take a close look at a few of these events.

The ListItem Event. The ListItem event is used to parse directory entries. If you set the ListItemNotify property to true, the ListItem event will fire each time a new entry from a directory entry is returned. The ListItem event has an FTPDirItem passed in as a parameter. Take a moment to look at Table 30.16 where the properties of the FTPDirItem object are summarized.

Table 30.16 Properties of the FTPDirItem Object

Property	Description
`Attributes`	Contains the file system attributes.
`Date`	Stores the last modified date of the file or directory entry.
`Details`	Returns details about the file or directory entry.
`Filename`	Keeps the name of the file.
`Size`	Keeps the size of the file.

When the ListItem event fires, you'll want to format a text entry for display to the user. Your code might look something like Listing 30.11.

Listing 30.11 Responding to the ListItem Event Using the FTPDirItem Object

Private Sub MyFTPControl_ListItem(ByVal Item As FTPDirItem) Dim LineToDisplay As String Select Case Item.Attributes Case 1 If its a directory LineToDisplay = Item.Filename & " " Item.Date Case 2 'If its a file LineToDisplay = Item.Filename & " " Item.Size & " " Item.Date End Select ShowDirectoryListing LineToDisplay End Sub

This listing assumes that there is a ShowDirectoryListing procedure which populates a list box or some other control.

The ProtocolStateChanged Event.

Listing 30.12 Responding to the ProtocolStateChanged Event

Private Sub MyFTPControl_ProtocolStateChanged(ByVal ProtocolState As Integer) elect Case ProtocolState ase ftpAuthorization Status.Panels(1).Text = "Authoru]izatin" ase ftpBase tatus.Panels(1).Text = "Base" se ftpTransaction tatus.Panels(1).Text = "Transaction" nd Select End Sub

Of course, you would need to have a StatusBar control named Status to use this code.

The HTTP Client Control

The HyperText Transfer Protocol (HTTP) is absolutely the most popular protocol on the Internet today. After all, HTTP is the protocol for the World Wide Web. Like most of the other Internet protocols, HTTP requires both a client and a server to complete document transfers.

Properties

Table 30.17 summarizes all the properties available in the HTTP Client control. All the data elements required to transfer a file from an HTTP server are included as properties in this control.

Table 30.17 Properties of the HTTP Client ActiveX Control

Property	Purpose
`Busy`	`True` if a command is currently in progress.
`DocInput`	Refers to the `DocInput` object which must be set before invoking the `SendDoc` method and conveys information about the progress of the data transfer.
`DocOutput`	Refers to the `DocOutput` object which must be set before invoking the `GetDoc` method and conveys information about the progress of the data transfer.
`Document`	This property plus the `RemoteHost` identifies the target document.
`EnableTimer`	Tells the kind of timer that is fired by the `TimeOut` event.
`Errors`	Refers to a collection of errors detailing the last error.
`Method`	Sets the HTTP method to be used to request information from the HTTP server.
`NotificationMode`	Determines how notification of inbound data will be provided.
`ProtocolState`	Indicates whether the FTP client is not connected, waiting for authorization to connect, or connected to an FTP server.
`RemoteHost`	The host name or IP address of the server to be connected to.
`RemotePort`	The port number used to connect to the FTP server.
`ReplyCode`	The reply code sent by the server in response to requests from the client.
`ReplyString`	The reply string sent by the server in response to requests from the client.
`State`	Used to report the current state of the FTP connection.
`TimeOut`	Tells how long to wait before firing the `TimeOut` event for the type of timer referred to by `EnableTimer`.
`URL`	The Uniform Resource Locator such as `http://myhost.com/myfile.htm`.

Now let's take a look at a few of these properties in a bit more detail.

The DocInput Property. Controls that have the DocInput property can use properties of the DocInput object. Although it is somewhat counter intuitive, DocInput refers to data that will be sent from your application to a remote machine. As you'll see more clearly through the end of this chapter, the DocInput object is also passed through the DocInput event. With the DocInput object and the corresponding event working together, control and action during document transfer can be quite robust.

Properties of the DocInput Object. The DocInput object makes many properties available for dealing with Internet documents. These properties are summarized in Table 30.18.

Table 30.18 Properties of the DocInput Object

Property	Value
`BytesTotal`	Returns either the size of the document to be passed or 0 if the size is not known.
`BytesTransferred`	Returns the number of bytes already transferred.
`DocLink`	Allows data sent from a `DocOutput` object to be connected directly to this `DocInput` object.
`Filename`	Source from which `DocInput` data comes from. Valid only if `DocLink` is empty.
`Headers`	A reference to a `DocHeaders` collection.
`State`	Stores the current state of a document transfer.
`Suspended`	`True` if the document transfer has been suspended.

Let's take a moment and examine the Headers property and the State property a bit more closely.

The Headers property is a reference to a DocHeaders collection. The DocHeaders collection is basically a collection of DocHeader objects. The DocHeader object consists of a name and a value property. The Name property keeps the MIME header label (such as "Content-type") and the value property stores that MIME header's value (such as text/html). You'll find the Headers property to be quite useful in working with the DocOutput object as you'll see in a moment.

Note

MIME stands for Multipurpose Internet Mail Extensions. MIME headers and values are employed in many applications on the Internet. To learn more about MIME headers, you should review RFC 1521 or see http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs.

The DocInput object's State property provides information about the current state of the document transfer. There are several possible States that can be achieved; they are summarized in Table 30.19.

Table 30.19 Values for the State Property in the DocInput Object

State	Meaning
`icDocNone`	No document transfer is in progress.
`icDocBegin`	A document transfer is being initiated.
`icDocHeaders`	Document headers are being transferred.
`icDocData`	A block of data is being transferred.
`icDocError`	An error has occurred during the document transfer.
`icDocEnd`	Document transfer has completed.

During the DocInput event response function, your application can take action based upon this State value.

Methods of the DocInput Object. The DocInput object exposes several methods for use in your Visual Basic applications. Table 30.20 summarizes these methods and their function.

Table 30.20 DocInput Object Methods

Method	Use
`GetData`	Retrieves the data currently being transferred when the `DocInput` event is fired.
`SetData`	Used to specify the data that will next be transferred when the `DocInput` event is fired.
`Suspend`	Suspends a transfer in progress.

The DocOutput Property. All controls that have the DocOutput property can access the properties of the DocOutput object. More importantly (as we'll discuss in more detail in a moment), the DocOutput object is passed through the DocOutput event. The DocOutput object and event provides all the necessary tools to do sophisticated processing of document transfer. Even though it seems backwards, DocOutput refers to data that will be received by your application from a remote machine. In the next few sections, you'll be introduced to the key properties and methods of the DocOutput object.

Properties of the DocOutput Object. The properties made available by DocOutput are the same as those of the DocInput object with one exception. The DocOutput object does not have a DocLink property. These properties are summarized in Table 30.21.

Table 30.21 Properties of the DocOutput Object

Property	Value
`BytesTotal`	Returns either the size of the document to be passed or zero if the size is not known.
`BytesTransferred`	Returns the number of bytes already transferred.
`Filename`	Source from which data comes from.
`Headers`	A reference to a `DocHeaders` collection.
`State`	Stores the current state of a document transfer.
`Suspended`	`True` if the document transfer has been suspended.

The Headers property in DocOutput is exactly the same as in the DocInput object. Using the Headers property in the DocOutput object will be a common task. Listing 30.13 provides a brief demonstration of how to use this important property.

Listing 30.13 Using the Headers Property

Private Sub http_DocOutput(ByVal DocOutput As DocOutput) Dim hdr As DocHeader Select Case DocOutput.State ... Case icDocHeaders For Each hdr In DocOutput.Headers MsgBox "Name: " & CStr(hdr.Name) & " Value: " & CStr(hdr.Value) Next ... End Select End Sub

In this example, each time a new header is received, a message box is presented with the name and value of the header. Not a particularly useful function, but it demonstrates clearly how to use and access the Headers collection.

DocInput and DocOutput both use the same values for the State property. So handling the various states of the data transfer will be handled with a Select Case statement for each of the states in DocOutput in the same manner as for DocInput. A simple example of such a statement is provided in Listing 30.14 in the section on the DocInput and DocOutput events.

Methods of the DocOutput Object. The DocOutput object exposes the same methods exposed by the DocInput object.

The Method Property. The Method property allows you to set the type of request that will be issued to the Web server. Table 30.22 summarizes the types of requests available.

Table 30.22 Method Settings

Setting	Meaning
`prcGet`	The HTTP `GET` request is used to obtain a document from the server.
`prcHead`	The HTTP `HEAD` request returns only the document header from the server.
`prcPost`	The HTTP `POST` request is issued to the server.
`prcPut`	The HTTP `PUT` request places a document on the server.

The ProtocolState Property. This property provides protocol-specific information about the state of the connection. For the HTTP control, there are two states that the protocol can be in. These states are listed in Table 30.23.

Table 30.23 HTTP ProtocolState Values

Value	Meaning
`prcBase`	The default state of the protocol prior to connecting to an HTTP server.
`prcTransaction`	Connection with the HTTP server has been obtained.

Methods

Most of the action in an HTTP session involves sending and receiving files. The methods to accomplish this work are summarized in Table 30.24.

Table 30.24 Methods for the HTTP Client Control

Method	Use
`Cancel`	Stops a pending request.
`Connect`	Issues a request to the HTTP server to open a connection. If a connection is established, the `State` property is set.
`GetDoc`	Requests the retrieval of a document identified by an URL and can be used in conjunction with the `DocInput` and `DocOutput` objects and events.
`PerformRequest`	Like `GetDoc`, `PerformRequest` is another way to retrieve a document from the HTTP server.
`SendDoc`	Requests that a document identified by the URL be sent to the server and can be used in conjunction with the `DocInput` and `DocOutput` objects and events.

Most of these methods are self-explanatory. However, a few of them bear additional discussion.

Events

The HTTP control provides numerous events on which your application can take action. Table 30.25 summarizes the events that are fired by the HTTP control.

Table 30.25 Summary of Events in the HTTP Control

Event	Description
`Busy`	Fires when a command is in progress and when a command is completed.
`Cancel`	Occurs at the completion of the cancellation of a request.
`DocInput`	Fired when data is sent from the control.
`DocOutput`	Triggered when data is sent to the control.
`Error`	Fires when an error is encountered.
`ProtocolStateChanged`	Whenever the state of the HTTP session changes, this event is fired.
`StateChanged`	Occurs anytime the state of the connection changes and therefore the `State` property changes.
`TimeOut`	Occurs when a given event fails to occur within the time period specified in the `TimeOut` property.

The DocInput and DocOutput Events. The DocInput and DocOutput events provide the programmer with a DocInput and DocOutput object. The properties and methods available in the DocInput and DocOutput objects allow you to control and monitor the incoming and outgoing documents from client to server. The most common way to use a DocInput or DocOutput event is to handle the various States in a Select Case statement. Listing 30.14 provides a basic skeleton for this approach.

Listing 30.14 Using DocOutput State Values

Private Sub http_DocOutput(ByVal DocOutput As DocOutput) Select Case DocOutput.State Case icDocBegin Case icDocHeaders Case icDocData Case icDocEnd Case icDocError End Select End Sub

The ProtocolStateChanged Event. You may want to notify the user of changes to the state of the connection between the client and the server. The ProtocolStateChanged event is triggered when changes occur at the protocol level. When the event fires, you'll be passed an integer that represents the current ProtocolState. Refer to the discussion of the ProtocolState property for a list of possible values. Listing 30.15 provides an example of how this event might be used.

Listing 30.15 Responding to the ProtocolStateChanged Event

Private Sub MyHTTPControl_ProtocolStateChanged(ByVal ProtocolState As Integer) Select Case ProtocolState Case prcBase Status.Panels(1).Text = "Base" Case prcTransaction Status.Panels(1).Text = "Transaction" End Select End Sub

Of course, you would need to have a StatusBar control named Status to use this code.

The HTML Control

The HyperText Markup Language (HTML) is the code that describes how Web pages should look. After all, HTML documents are carried via the HTTP protocol over the World Wide Web between client and server.

Properties

Table 30.26 summarizes all the properties available in the HTML control. All the data elements required to transfer and render an HTML document over the World Wide Web are included as properties in this control.

Table 30.26 Properties of the HTML ActiveX Control

Property	Purpose
`BackImage`	Stores the background image to be used in rendering the page.
`BaseURL`	Equal to the value of the `<BASE>` tag or URL if there is no base.
`DeferRetrieval`	`True` if embedded objects are not downloaded. `False` if embedded objects are downloaded.
`DocBackColor`	Keeps the `BGCOLOR` attribute of the `<BODY>` tag.
`DocForeColor`	Stores the `TEXT` attribute of the `<BODY>` tag.
`DocInput`	Refers to the `DocInput` object which must be set before invoking the `SendDoc` method and conveys information about the progress of the data transfer.
`DocLinkColor`	Equal to the value of the `LINK` attribute of the `<BODY>` tag.
`DocOutput`	Refers to the `DocOutput` object which must be set before invoking the `GetDoc` method and conveys information about the progress of the data transfer.
`DocVisitedColor`	Keeps the value of the `VLINK` attribute of the `<BODY>` tag.
`ElemNotification`	Used to parse each HTML element. Set to `false` unless you're using the HTML control as a parser in another application.
`EnableTimer`	Tells the kind of timer that is fired by the `TimeOut` event.
`FixedFont`	Identifies the font to be used for fixed width text.
`Forms`	Refers to an HTMLForms collection.
`Heading1Font`	The font is used for text enclosed in H1 tags.
`Heading2Font`	The font is used for text enclosed in H2 tags.
`Heading3Font`	The font is used for text enclosed in H3 tags.
`Heading4Font`	The font is used for text enclosed in H4 tags.
`Heading5Font`	The font to be used for text enclosed in H5 tags.
`Heading6Font`	The font to be used for text enclosed in H6 tags.
`LayoutDone`	`True` when the main HTML document has been rendered but embedded objects have not been downloaded.
`LinkColor`	The color used for text representing Hypertext links.
`ParseDone`	True when the HTML has been parsed.
`RedrawProperty`	Set this property to `false` to make changes to the HTML docu-ment and avoid display defects. To cause the HTML control to be redrawn, set this property to true.
`RequestURL`	The URL that is currently being requested.
`RetainSource`	Set this to true to keep the source HTML code.
`RetrieveBytesDone`	Reports the number of bytes retrieved so far.
`RetrieveBytesTotal`	If available, the total number of bytes to be transferred.
`SourceText`	The HTML code currently rendered by the HTML control(read-only).
`TimeOut`	Tells how long to wait before firing the `TimeOut` event for the type of timer referred to by `EnableTimer`.
`TotalHeight`	The height in pixels of the complete document.
`TotalWidth`	The width in pixels of the complete document.
`UnderlineLinks`	`True` if hyptertext links should be underlined.
`URL`	The URL to be retrieved.
`UseDocColors`	If this is false, document specific color settings are ignored and the defaults are used.
`ViewSource`	Determines whether the HTML code should be rendered or shown as text.
`VisitedColor`	The color to render the text of visited links.

Now let's take a look at a few of these properties in a bit more detail.

URL versus RequestURL. At first glance, it might seem that these two properties are redundant. But, of course, they are not. The RequestURL property is set by the argument you pass to RequestDoc at execution. The URL property, on the other hand, is set during the process of fulfilling the request and thus may look a bit different from the original address you requested. For instance, the port number might be appended to the domain name. Listing 30.16 shows how these two properties are used.

Listing 30.16 Using URL and RequestURL

... HTML.RequestDoc txtURL.Text Status.Panel(2).Text = "Retrieving " & HTML.RequestURL ... ... Private Sub HTML_EndRetrieval() Status.Panels(2).Text = "Document complete" txtURL.Text = HTML.URL End Sub

While there are some methods and events you haven't seen yet here, you can see that the RequestURL property is used before the retrieval of the document and the URL property is used after completion of the document retrieval.

HTMLForms Properties and Methods.

The Forms property points to an HTMLForms collection. The HTMLForms collection contains a number of HTMLForm objects. Table 30.27 details the properties of the HTMLForm object.

Table 30.27 Properties of the HTMLForm Object

Property	Value
`Method`	Must be one of `prcGet`, `prcHead`, `prcPost`, or `prcPut` HTML verbs.
`URL`	The ACTION URL from the form.
`URLEncodedBody`	Stores all the values of all of the form fields in text.

The HTMLForm object exposes only one method, the RequestSubmit function. RequestSubmit is used to send a form for processing. The RequestURL property of HTML object is set to the action URL for the form. The URL property is updated after processing of the request has successfully begun.

Methods

The HTML control offers very few methods for execution. The three available methods are summarized in Table 30.28.

Table 30.28 Methods for the HTML Control

Method	Use
`Cancel`	Stops a pending request.
`RequestAllEmbedded`	Requests all that all the embedded objects in the main document be downloaded.
`RequestDoc`	Requests that the main document be downloaded.

Most of the time, you'll use RequestDoc. However, say that you had a configuration option that allowed the user to turn off the downloading of images and other embedded objects. (This is a common feature in most Web browsers so that you don't have to wait for big graphics to download if you don't want to.) You might then want the user to be able to download embedded objects on demand. This type of scenario would be an excellent situation for using the RequestAllEmbedded method.

Events

The HTML control provides numerous events on which your application can take action. Table 30.29 summarizes the events that are fired by the HTML control.

Table 30.29 Summary of Events in the HTML Control

Event	Description
`BeginRetrieval`	Occurs when the document transfer is initiated.
`DocInput`	Fired when data is sent from the control.
`DocOutput`	Triggered when data is sent to the control.
`DoNewElement`	Fires during HTML parsing when a new element is added.
`DoRequestDoc`	Triggered by either a call to `RequestDoc` or a click by the user on a hypertext link.
`DoRequestEmbedded`	Occurs when an embedded item is to be transferred.
`DoRequestSubmit`	Triggered by either a call to `RequestSubmit` or a user submitting a form.
`EndRetrieval`	Fires when the document and embedded objects have all been transferred.
`LayoutComplete`	Occurs when the entire main document has been transferred, although embedded objects may still be downloading.
`ParseComplete`	When the HTML source has been parsed, this event fires.
`TimeOut`	Occurs when a given event fails to occur within the time period specified in the `TimeOut` property.

The SMTP Control

The Simple Mail Transport Protocol (SMTP) is responsible for carrying electronic mail messages over the Internet. You'll encounter many cases where your applications need to send e-mail. Consider, for example, an application that copies files at night for use by users in the morning. You might want the application to fire off an e-mail in the event of an error.

Properties

Table 30.30 summarizes all the properties available in the SMTP control. All the data elements required to send e-mail messages to an SMTP server are included as properties in this control.

Table 30.30 Properties of the SMTP Client ActiveX Control

Property	Purpose
`Busy`	`True` if a command is currently in progress.
`DocInput`	Refers to the `DocInput` object which must be set before invoking the `SendDoc` method and conveys information about the progress of the data transfer.
`Errors`	Refers to a collection of errors detailing the last error.
`NotificationMode`	Determines how notification of outbound data will be provided.
`ProtocolState`	Indicates whether the SMTP client is not connected, waiting for authorization to connect, or connected to an SMTP server.
`RemoteHost`	The host name or IP address of the SMTP server to be con-
nected to.
`RemotePort`	The port number used to connect to the SMTP server.
`ReplyCode`	The reply code sent by the server in response to requests from
the client.
`ReplyString`	The reply string sent by the server in response to requests from
the client.
`State`	Used to report the current state of the SMTP connection.

You have seen all of these properties in previous controls. Note that port 25 is standard for SMTP. Unless you need to run a special SMTP server on another port, the default value will be fine.

Methods

The SMTP control offers a few methods for programmers. The two available methods are summarized in Table 30.31.

Table 30.31 Methods for the SMTP Client Control

Method	Use
`Cancel`	Stops a pending request.
`SendDoc`	Sends the mail message.

Your applications will make extensive use of SendDoc. To familiarize yourself with the elements of this handy function, take a look at each of the following parameters:

URL-This optional parameter permits you to identify a remote document for
sending.
Headers-SMTP uses a number of headers to send mail, including things such as the To and From addresses. So the SMTP control accepts a DocHeaders collection for passing these headers. This parameter is optional.
InputData-An optional parameter for a buffer of data that holds the document to be sent.
InputFile-A file on the local system that is the document to be sent may optionally be set.

You'll always use the Headers parameter to set up SMTP headers as necessary.

Events

The SMTP Control provides numerous events on which your application can take action. Table 30.32 summarizes the events that are fired by the SMTP client control.

Table 30.32 Summary of Events in the SMTP Client Control

Event	Description
`Busy`	This event is triggered when commands are in progress.
`Cancel`	This event is triggered when the `Cancel` method is executed.
`DocInput`	Fired when data is sent from the control.
`Error`	Occurs when an error has been encountered.
`ProtocolStateChange`	When the state of the protocol changes, this event is fired.
`StateChanged`	When the `State` of the SMTP control changes, this event is thrown.
`TimeOut`	Occurs when a given event fails to occur within the time period specified in the `TimeOut` property.

The NNTP Control

The Network News Transmission Protocol (NNTP) is used to read from and post to the UseNet news network.

Properties

Table 30.33 details the properties available in the NNTP control. All the data elements required to retrieve and post news articles to an NNTP server are included as properties
in this control.

Table 30.33 Properties of the NNTP Client ActiveX Control

Property	Purpose
`ArticleNumbersSupported`	If this property is `true`, the `GetArticleNumbers` method will properly return a list of article numbers.
`Busy`	`True` if a command is currently in progress.
`DocInput`	Refers to the `DocInput` object which must be set before invoking the `SendDoc` method and conveys information about the progress of the data transfer.
`DocOutput`	Refers to the `DocOutput` object, which must be set before invoking the `GetDoc` method and conveys information about the progress of the data transfer.
`EnableTimer`	Tells the kind of timer that is fired by the `TimeOut` event.
`Errors`	Refers to a collection of errors detailing the last error.
`LastUpdate`	The date used by `NEWGROUPS` and `NEWNEWS` to decide what is "new."
`NotificationMode`	Determines how notification of outbound data will be provided.
`OverviewSupported`	`True` if the `GetOverviewFormat` and `GetOverview` methods will return headers stored in the server's overview database.
`PostingAllowed`	When the server permits posting of messages, this property is set to `true`.
`ProtocolState`	Indicates whether the NNTP client is not connected, waiting for authorization to connect, or connected to an NNTP newsserver.
`RemoteHost`	The host name or IP address of the NNTP server to be connected to.
`RemotePort`	The port number used to connect to the NNTP server.
`ReplyCode`	The reply code sent by the server in response to requests from the client.
`ReplyString`	The reply string sent by the server in response to requests from the client.
`State`	Used to report the current state of the NNTP connection.
`TimeOut`	Tells how long to wait before firing the `TimeOut` event for the type of timer referred to by `EnableTimer`.
`URL`	The URL of the document being retrieved.

Although explaining the details of the NNTP protocol is beyond the scope of this book, you should take note of the LastUpdate property explained in the next section. In addition, you can find RFC 977 which defines the NNTP protocol with the other RFCs at http://ds.internic.net/ds/rfc-index.html.

The LastUpdate Property. NNTP provides a mechanism for deciding which articlesand groups are to be transmitted (for example, what things are new). A call to the ListNewGroups method uses this property as the date the group list was last updated.Say that the LastUpdate property is equal to 7/3/96 and on 7/4/96 a new group comp.new.group is added. A call to ListNewgroups made on 7/5/96 in your application can obtain the comp.new.group during the DocOutput event.

Methods

The NNTP control offers a number of methods for programmers. These methods are summarized in Table 30.34.

Table 30.34 Methods for the NNTP Client Control

Method	Use
`Cancel`	Stops a pending request.
`Connect`	Issues a request to the POP server to open a connection. If a connection is established, the `State` property is set.
`GetAdministrationFile`	Sends the NNTP `XMOTD` command and retrieves the server's administrator data.
`GetArticleByArticleNumber`	Requests an article from the newsserver using the article number. Successful requests fire the `DocOutput` event.
`GetArticleByMessageID`	Requests an article from the newsserver using the message ID. The `DocOutput` event is triggered on success.
`GetArticleHeaders`	Obtains specific headers from a list of articles.
`GetArticleNumbers`	Gets a list of article numbers from the newsserver. Triggers the `DocOutput` event on success.
`GetBodyByArticleNumber`	Obtains the body of an article based on the article number. Fires the `DocOutput` event on success.
`GetBodyByMessageID`	Obtains the body of an article based on the message ID. Causes the `DocOutput` event to occur on success.
`GetDoc`	Requests the retrieval of a document identified by an URL and can be used in conjunction with the `DocInput` and `DocOutput` objects and events.
`GetHeaderByArticleNumber`	Obtains the header of an article based on the article number. Fires the `DocOutput` event on success.
`GetHeaderByMessageID`	Obtains the header of an article based on the message ID. Causes the `DocOutput` event to occur on success.
`GetOverView`	Returns information from the overview database for the specified article.
`GetOverViewFormat`	Retrieves a list of headers in the order they appear in the overview database.
`GetStatByArticleNumber`	Requests the stat of an article.
`ListGroupDescriptions`	Requests a list of group descriptions and triggers the `DocOutput` event.
`ListGroups`	Requests a list of groups and fires the `DocOutput` event.
`ListNewGroups`	Requests a list of new groups from the NNTP server. The `DocOutput` event occurs on success.
`Quit`	Closes the connection and fires the `Quit` event.
`SelectGroup`	Requests a list of articles from the newsserver. Triggers the `DocOutput` event on success.
`SendDoc`	Requests the transmission of a document identified by an URL and to the server. Used in conjunction with the `DocInput` event.
`SetLastArticle`	Selects a newsgroup's last article.
`SetNextArticle`	Selects a newsgroup's next article.

The NNTP control is rich with methods to make the interface with the newsserver simple and flexible. To fully exploit the power of the NNTP control, you'll need to learn a bit about some of these functions.

Current Article Pointer. The newsserver keeps a "current article pointer" that refers to the article that will be acted on by the server unless an article number is passed. There are several functions that rely on this current article pointer including the following:

SetLastArticle
SetNextArticle
The GetArticle functions

SetLastArticle moves the article pointer to the last article in a newsgroup. The SetNextArticle advances the article pointer to the next article in the newsgroup. All of the GetArticle functions will act on the current article unless an appropriate reference is passed. For instance, take a look at Listing 30.17.

Listing 30.17 The Current Article Pointer

... ... '---------------------------------- '-- Without a parameter the '-- current article is retrieved '---------------------------------- MyNNTPControl.GetArticleByArticleNumber '---------------------------------- '-- Retrieves article 903 and moves '-- current article pointer '---------------------------------- MyNNTPControl.GetArticleByArticleNumber 903 ... ...

Say that the article pointer was referencing article 847. The first call would return article 847, while the second call returns article 903 and advances the current article pointer.

Events

The NNTP Control provides numerous events that your application can handle. Table 30.35 summarizes the events that are thrown by the NNTP client control.

Table 30.35 Summary of Events in the NNTP Client Control

Event	Description
`AuthenticateRequest`	Triggered when the newsserver requests authentication.
`AuthenticateResponse`	Occurs after an authentication response is received from the newsserver.
`Banner`	Fires when the server's welcome banner is received.
`Busy`	This event is triggered when commands are in progress.
`Cancel`	This event is triggered when the `Cancel` method is executed.
`DocInput`	Fired when data is sent from the control.
`DocOutput`	Fired when data arrives at the control.
`LastArticle`	Occurs when the last article in a list is reached.
`NextArticle`	Triggered by selecting the next article in the list.
`ProtocolStateChange`	When the state of the protocol changes, this event is fired.
`SelectGroup`	Occurs when the `SelectGroup` method is successful.
`StateChanged`	When the `State` of the NNTP control changes, this event is thrown.
`TimeOut`	Occurs when a given event fails to occur within the time period specified in the `TimeOut` property.

The POP Control

The Post Office Protocol (POP) is used to retrieve mail from a POP server. Typically, SMTP is used to transport mail to the appropriate POP server. The POP protocol is then used to retrieve and delete messages. The Post Office Protocol will be handy for any applications that need to download mail messages from a server.

Properties

Table 30.36 details the properties available in the POP control. All the data elements required to retrieve e-mail messages from a POP server are included as properties in this control.

Table 30.36 Properties of the POP Client ActiveX Control

Property	Purpose
`Busy`	`True` if a command is currently in progress.
`DocOutput`	Refers to the `DocOutput` object which must be set before invoking the `GetDoc` method and conveys information about the progress of the data transfer.
`EnableTimer`	Tells the kind of timer that is fired by the `TimeOut` event.
`Errors`	Refers to a collection of errors detailing the last error.
`MessageCount`	Stores the number of messages currently available on the POP server.
`NotificationMode`	Determines how notification of outbound data will be provided.
`Password`	Sets the password to be used for logging on to a POP server.
`ProtocolState`	Indicates whether the POP client is not connected, waiting for authorization to connect, or connected to a POP server.
`RemoteHost`	The host name or IP address of the POP server to be connected to.
`RemotePort`	The port number used to connect to the POP server.
`ReplyCode`	The reply code sent by the server in response to requests from the client.
`ReplyString`	The reply string sent by the server in response to requests from the client.
`State`	Used to report the current state of the POP connection.
`TimeOut`	Tells how long to wait before firing the `TimeOut` event for the type of timer referred to by `EnableTimer`.
`TopLines`	Keeps the number of lines to be returned in response to a `TOP` command.
`TopSupported`	Set to `true` when the server supports the `TOP` command.
`URL`	The URL of the document being retrieved.
UserID	Sets the user name to be used for logging on to an POP server.

Note

Explaining the details of the POP protocol is beyond the scope of this book. However, you can find RFC 1081, which defines the POP protocol, with the other RFCs at ftp://ds.internic.net/rfc.

Methods

The POP control offers a few methods for programmers. The available methods are summarized in Table 30.37.

Table 30.37 Methods for the POP Client Control

Method	Use
`Authenticate`	Authenticates the user using the `UserID` and `Password` properties.
`Cancel`	Stops a pending request.
`Connect`	Issues a request to the POP server to open a connection. If a connection is established, the `State` property is set.
`Delete`	Deletes the specified message on the POP server.
`GetDoc`	Requests the retrieval of a document identified by an URL and can be used in conjunction with the `DocInput` and `DocOutput` objects and events.
`Last`	Initiates a `Last` request.
`MessageSize`	Requests the size of the next message. The `MessageSize` event is fired when the request is successful.
`NOOP`	Causes the POP server to reply with an OK in the `ReplyString` property.
`Quit`	Closes the connection and fires the `Quit` event.
`Reset`	Issues a `RSET` command. Any messages marked for deletion are unmarked.
`RetrieveMessage`	Downloads the passed message number. The message is streamed through a `DocOutput` object.
`TopMessage`	Sends a `Top of Message` request for the message number passed through a `DocOutput` object.

You've encountered most of these methods in previous chapters. There are a few, however, that are specific to the POP control and deserve a bit more attention.

The MessageSize Method. Sometimes you may want to know the size of a mail message before retrieving a message from the POP server. Perhaps you're concerned that some hacker has sent you a 2 GB mail message (yuck!). You might also build a specialized application that waits for a message of a certain size and then replies with a special message. Using MessageSize in your applications is simple. Take a look at Listing 30.18.

Listing 30.18 Using the MessageSize Method

... ... Dim SizeOfThisMsg As Integer Dim MsgOfInterest As Integer MsgOfInterest = 1 MyPOPControl.MessageSize MsgOfInterest

To act on the size of the message, you'll respond to the MessageSize event.

The RetrieveMessage Method. Certainly the most important method exposed by the POP control is RetrieveMessage. Not suprisingly, RetrieveMessage is used to obtain a mail message from the POP server. When the POP control receives the message from the server, you have two options for the output. You can access the POP control's built-in DocOutput object, or you can pass RetrieveMessage your own DocOutput object. In most cases, you'll simply use the DocOutput object in the POP control. Listing 30.19 shows the alternate method of passing your own DocOutput object.

Listing 30.19 Using RetrieveMessage

Dim MyOwnDocOutput As DocOutput Dim MsgOfInterest As Integer ... ... POP.RetrieveMessage MsgOfInterest, MyOwnDocOutput ... ...

Events

The POP control provides numerous events that your application can handle. Table 30.38 summarizes the events that are thrown by the POP client control.

Table 30.38 Summary of Events in the POP Client Control

Event	Description
`Authenticate`	Triggered after the `Aut`

Chapter 30

ActiveX Control Reference

CONTENTS

Properties

Methods

Connecting Clients and Servers

Sending and Receiving Data

Events

Properties

Methods

Connecting the Sending and Receiving Application

Events

Properties

Methods

Getting and Putting Files

Events

The ProtocolStateChanged Event.

Properties

Methods

Events

Properties

HTMLForms Properties and Methods.

Methods

Events

Properties

Methods

Events

Properties

Methods

Events

Properties

Methods

Events