Skip to main content.

Web Based Programming Tutorials

Homepage | Forum - Join the forum to discuss anything related to programming! | Programming Resources

Web Programming Desktop Reference 6in1

Chapter 30 -- ActiveX Control Reference

Chapter 30

ActiveX Control Reference


CONTENTS




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

PropertyPurpose
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

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

  1. Server listens on a specific port.
  2. Client requests a connection with the server.
  3. Server accepts the connection.
  4. Data is transferred between the client and the server.
  5. 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

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

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

EventDescription
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

PropertyPurpose
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

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

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:

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

EventDescription
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

PropertyPurpose
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 TimerValue
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

ValueMeaning
0Notify when the data transmission has been completed. This is the default setting.
1The 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

ValueMeaning
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

ValueDescription
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

MethodUse
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

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

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

EventDescription
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

PropertyDescription
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

PropertyPurpose
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

PropertyValue
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

StateMeaning
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

MethodUse
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

PropertyValue
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

SettingMeaning
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

ValueMeaning
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

MethodUse
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

EventDescription
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

PropertyPurpose
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

PropertyValue
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

MethodUse
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

EventDescription
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

PropertyPurpose
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

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

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

EventDescription
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

PropertyPurpose
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

MethodUse
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 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

EventDescription
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

PropertyPurpose
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.
UserIDSets 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

MethodUse
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

EventDescription
Authenticate Triggered after the Aut