MIME multipart content type.

The ContentType property describes the MIME multipart content type of data to be posted (such as "application").

This property can be set at any time. This property has no default value.

Http.ContentType = "application"

Enable or disable firewall/proxy support.

The Firewall property enables or disables the built-in firewall support for the HTTP ActiveX control. Most corporate networks have a firewall between their internal network and the outside world. In this case, applications would have to connect to a firewall server to access the remote host.

The Firewall property can be set to one of the following values:

The HTTP ActiveX control supports SOCKS version 4.2 as well as HTTP proxy support. If the application requires to go through a HTTP proxy server, the Firewall property must be set to FW_PROXY. If the Firewall property is set to FW_SOCKS, the HTTP ActiveX control will try to connect to a SOCKS (v4.2) server.

If the Firewall property is not set to FW_NONE, then the FirewallPort and FirewallServer properties have to be set before using the Get, Head or Post methods.

If the Firewall property is set to FW_SOCKS, then the FirewallServer, FirewallPort, FirewallUser and UserAgent properties must all be set before using the Get, Head or Post methods. If any of these properties are not set then the control will not go via the SOCKS server, instead the control will atttempt to connect directly to the remote host.

This property can be set at design time or at run time before a transaction is initiated. The default value for this property is FW_NONE.

Http.Firewall = FW_SOCKS
Http.FirewallServer = "127.43.101.12"
Http.FirewallPort = "1080"
Http.FirewallUser = "john"
Http.UserAgent = "Distinct HTTP"
Http.Get ()

Firewall server port.

The FirewallPort property specifies the remote port on the firewall SOCKS server (v 4.2) on which the SOCKS service resides, if the Firewall property is set to FW_SOCKS. Most SOCKS services listen for connection requests on port 1080. Sometimes, usually for security reasons, port numbers other than 1080 are used.

If the Firewall property is set to FW_PROXY, then the FirewallPort property specifies the remote port on which the HTTP proxy service resides. Most HTTP servers listen for connection requests on port 80. Sometimes, usually for security reasons, port numbers other than 80 are used.

If the application will be connecting to the SOCKS or HTTP proxy service on a different port to the default, then the FirewallPort property must be set before the connection attempt is made. An application may even want to query the user for the correct port before the transaction. The custom control does not verify the setting of the FirewallPort property and any value is therefore legal.

This property can be set at design time or at run time before a transaction is initiated. The default value for this property is port "1080" for SOCKS and "80" for HTTP proxy support.

Http.FirewallPort = "1080"

Name or IP address of the firewall server.

The FirewallServer property specifies the name or internet address of the remote server. If the Firewall property is set to FW_SOCKS, then the FirewallServer property specifies the SOCKS server (v4.2); otherwise for FW_PROXY the FirewallServer property specifies the HTTP proxy server. This property must be set before any transaction (Get, Head or Post), unless the Firewall property is set to FW_NONE.

There are three possible ways of specifying the remote server.

Machine Name
An application only needs to specify the name of the server if the remote server if the internet address of the server is defined in the local host table. If the server is not defined in the local host table, then the underlying protocol will contact the domain server to resolve the internet address of the server.

Machine and Domain Name
An application can specify the machine name and the domain name of the remote server. Fully domain qualified machine names are written from left to right in ascending order (eg. speedy.distinct.com). If both machine and domain names are specified, then the underlying protocol will contact the domain server to resolve the internet address of the server.

Internet Address
Sometimes the user knows only the internet address of the server that he or she wants to use. In this case, the internet address can be entered in what is known as the dotted decimal notation (eg. 127.43.101.12).

This property can be changed at design time and at run time before a connection has been established. There is no default value for this property.

Http.FirewallServer = "127.43.101.12"

User name for SOCKS.

The FirewallUser property specifies the user name that is to be authenticated at the SOCKS server.

If the Firewall property is set to FW_SOCKS, then the FirewallServer, FirewallPort, FirewallUser and UserAgent properties must all be set before any transaction is initiated. If any of these properties are not set then the control will not go via the SOCKS server, instead the control will atttempt to connect directly to the remote host.

This property can be changed at design time and at run time before any transaction. There is no default value for this property.

Http.Firewall = FW_SOCKS
Http.FirewallServer = "127.43.101.12"
Http.FirewallPort = "1080"
Http.FirewallUser = "john"
Http.UserAgent = "Distinct HTTP"
Http.URL = "//www.distinct.com"
Http.Get ()

Result of last command executed.

The LastResult property contains the result of the last operation. The property can have any one of the following values.

If a different value than those listed above appears, then an error occurred while the server was executing the command. The LastResult property will contain the reply code from the HTTP server.

The LastResult property reflects the result of the last operation caused by invoking the Get, Head, or Post methods.

The value of this property should be checked immediately after initiating the operation. Accessing other properties may change the value of the property.

This property can be read at any time. There is no default value for this property.

Http.Get()
If Http.LastResult <> HTTP_SUCCESS Then
MsgBox "Unable to get URL", 64, "Sample Program"
End If

URL address.

The URL (Universal Resource Locator) property specifies the address and path for the resource of interest. This property is used to identify the location of the resource. The URL is a formatted string that determines a network resource using a name, location, address or any other characteristic. The protocol is part of the URL string. The HTTP ActiveX control supports 2 protocols: HTTP and HTTPS.

For the HTTP protocol, the URL should have the following syntax:

"http:" "//" host [":" port] [path]

For the HTTPS protocol, the URL should have the following syntax:

"https:" "//" host [":" port] [path]

Other than these two protocols, the HTTP ActiveX control also supports the access of local files. In this case, the URL should have the following syntax:

"file:" "///" [path]

The above syntax is used to identify a resource located on the host server listening for a TCP connection on port and the location for the resource is specified by path.

The host must be a valid internet host name or dotted-decimal IP address. The port and path parameters are optional. If the port is not specified, the default port 80 is used. If the path is not present in the URL, it is given a "/" by default.

If the protocol ("http:" or "https:" or "file:") is not specified then "http:" is assumed as default. Any other protocol is invalid.

Examples of valid URL strings:

http://www.distinct.com:80/

https://www.distinct.com/

//www.distinct.com/products/

http://www.distinct.com

file:///c:\temp\index.htm

This property can be set at design time or at run time before a transaction is initiated. There is no default value for this property.

Http.URL = http://www.distinct.com/

User agent.

The UserAgent property specifies the information for the User-Agent request-header field. This property is used to identify the user agent originating the request and can be used for statistical purposes or automated recognition of user agents.

This property should generally contain a name identifying the agent and any product information (such as version numbers) associated with the agent.

If the Firewall property is set to FW_SOCKS, then the FirewallServer, FirewallPort, FirewallUser and UserAgent properties must all be set before any transaction is initiated. If any of these properties are not set then the control will not go via the SOCKS server, instead the control will atttempt to connect directly to the remote host.

This property can be set at design time or at run time before a transaction is initiated. The default value for this property is Distinct HTTP.

Http.UserAgent = "Distinct HTTP"

Local error has occurred.

The OnError event occurs when a property is accessed in an illegal way or when a connection with the remote server cannot be established. The table below lists all possible error codes delivered by this event.

The following describes each error in more detail.

ERR_URL_NOT_DEFINED
URL not specified. Make sure that the URL property is set before using the Get, Head or Post methods.

ERR_CANNOT_GET_URL
Cannot get specified URL. Make sure that the URL property contains the correct address and path. This error is returned during a Get or Head method.

ERR_IN_ACTION
Another action is already in progress.

ERR_CANNOT_PERFORM_ACTION
Unable to initialize the underlying Distinct support files. There may be a license violation or one or more of the support DLLs may be missing.

ERR_CANNOT_POST_URL
Cannot post specified document. Make sure that the URL property contains the correct address and path. This error is returned during a Post method.

Sub Http_OnError (ErrorCode As Integer)
If ErrorCode = ERR_CANNOT_GET_URL Then
MsgBox "Unable to get specified URL", 64, "Sample Program"
End If
End Sub

Received header information.

The OnHeader event occurs in response to calling the Get or Head method. It may also occur in response to a Post method. This event delivers the MIME header information for the document. The header information will vary with the document and one or more OnHeader events will occur to deliver this information.

The OnHeader event contains two parameters: the FieldName parameter delivers the field name (such as "ContentType" or "ContentLength") and the FieldValue parameter gives the value for the field.

This MIME header information can be used by the application to decide the type of document that is being downloaded or to decide if there is enough disk space on the local machine to cache the document.

Sub Http_OnHeader (FieldName As String, FieldValue As String)
' display header information
Display.Text = Display.Text + FieldName + ": " + FieldValue + vbCrLf
End Sub

Received document.

The OnReceive event occurs in response to calling the Get method or sometimes a Post method. this event delivers the contents of the document sent by the HTTP server.

One or more OnReceive events may occur to deliver the complete document. The Buffer parameter contains the data and Bytes indicates the length of the data.

Instead of caching the incoming data to the local disk, the application may want to display this information on screen or pass it to viewer. The Buffer could be written to a disk file, sent to another application using DDE, copied into the clipboard or scanned for the desired information and then discarded.

Normally, the Buffer property is sufficient to obtain the data in most environments. However, if you experience any problems retrieving data (eg. the environment may not support binary data within string data types), use the Receive method provided with this control. This method can be accessed inside the OnReceive event. The data in the Buffer parameter is represented in a different form by the receive method. Please check the reference page for the Receive method for more information.

Sub Http_OnReceive (Buffer As String, Bytes As Long)
' display document transferred
Dim i, j As Integer
Dim Message As String
i = 1
While (i < Bytes)
j = InStr(i, Buffer, Chr(10))
If (j > 0) Then
Message = Mid(Buffer, i, j - i)
Display.Text = Display.Text + Message + Chr(13) + Chr(10)
i = j + 1
Else
Display.Text = Display.Text + Mid(Buffer, i)
i = Bytes
End If
Wend
End Sub

Report progress of transfer.

The OnReportProgress event occurs several times during an HTTP transaction to inform the application of the progress. It delivers the number of bytes transferred as and when more data is received from the other side.

The parameters Number and Total represent the number of bytes currently transferred and the total length of the document. The total length is determined by the ContentLength header information. If this information is not present in the header then Total will be -1.

As the transfer proceeds, one or more OnReportProgress events will occur to deliver the number of bytes transferred so far between the HTTP server and the client. The application can process this data and display the status of the transfer (eg. update a progress bar or status bar).

Sub Http_OnReportProgress (Bytes As Long, Total As Long)
' display number of bytes transferred
NumBytes = NumBytes + Bytes
StatusBar.Panels(2).Text = "Bytes: " & NumBytes & " / " & Total
End Sub

Report status of transfer.

The OnReportStatus event occurs several times during an HTTP transaction to inform the application of the progress. It delivers the connection status of the request.

The Status parameter gives a textual information about the status of the connection. For example, the Status parameter maybe "Resolving Host Name" or "Sending Request".

As the transfer proceeds, one or more OnReportStatus events will occur to keep the application informed of the status. The application can process this data and display the status (eg. update a status bar).

Sub Http_OnReportStatus (Status As String)
' display transaction status
StatusBar.Panels(1).Text = "Status: " + Status
End Sub

Abort transaction.

To abort a transaction, call the Abort method at any time. The transaction in progress will be canceled and no further events will occur to indicate the progress or status of the transaction.

This method must be called only during a GET, HEAD or POST transaction. If this method is called at any other time, the Abort method will fail.

The Abort method returns True if successful, otherwise, it returns False.

Result = Http.Abort ()
If Result = False Then
MsgBox "Unable to abort", 64, "Sample Program"
Exit Sub
End If

Get URL document.

To retrieve a information from a Web site use the Get method. This method retrieves the resource indicated by the URL property. The OnHeader, OnReceive, OnReportProgress and OnReportStatus events will occur during this request. The URL property must be set before calling this method.

If an error occurs, then the OnError event will be fired. The application should set a flag in response to the OnError event, so that it can determine if the action was successful. In addition, the application may want to display an error message in the OnError event to inform the user of the error. Please check the reference page of the OnError event for a complete listing of error codes.

The Get method returns True if successful, otherwise, it returns False.

Http.URL = "//www.distinct.com"
Result = Http.Get ()
If Result = False Then ' error
MsgBox "Unable to get specified URL", 64, "Sample Program"
Exit Sub
End If

Get header information.

The Head method obtains the header information from the server. The body of the document is not retrieved. This header information is identical to the one received during a Get operation. This method retrieves the header of the resource indicated by the URL property. The OnHeader, OnReportProgress and OnReportStatus events will occur during this request. The URL property must be set before calling this method.

If an error occurs, then the OnError event will be fired. The application should set a flag in the OnError event, so that it can determine if the action was successful. In addition, the application may want to display an error message in the OnError event to inform the user of the error. Please check the reference page of the OnError event for a complete listing of error codes.

The Head method returns True if successful; otherwise, it returns False.

Http.URL = "//www.distinct.com/"
Result = Http.Head ()

Post document.

The Post method is used to request the server to accept the data enclosed in the request as an input for the resource indicated by the URL property. The Post method may be used to post a message to a news group or mailing list, submit a form or extend a database, etc� The actual function of the Post method is determined by the server processing the request.

The Data parameter must be set to contents to be posted. The ContentType describes the MIME multipart content type for the contents of Data (such as "application"). The ContentLength parameter is set to the length of the request contents in Data. If these parameters are not set correctly, the Post request will fail.

The server may respond to the Post operation by sending a document. In this case, the OnHeader, OnReceive, OnReportProgress and OnReportStatus events will occur.

The Post method returns True if successful, otherwise, it returns False.

Dim ContentLength As Long
Dim ContentType As String
Dim PostData(32768) As Byte

Http.URL = "http://www.distinct.com/"

' filename must be defined
If Len(SFileName.Caption) = 0 Then
MsgBox "File name must be defined!", vbOKOnly + vbInformation, "HTTP Sample"
Exit Sub
End If

' set content type and content length
ContentType = "application"
ContentLength = FileLen(SFileName.Caption) ' length of file

' read entire file into buffer
Open SFileName.Caption For Binary Access Read As #1
Get #1, ContentLength, PostData
Close #1

' send document to remote host
Result = Http.Post (PostData, ContentType, ContentLength)
If Result = False Then ' error
MsgBox "Unable to POST document", vbOKOnly + vbInformation, "HTTP Sample"
End If

Read data in buffer.

The Receive method is used to access the data received in the OnReceive event. Normally, accessing the Buffer parameter in the OnReceive event is sufficient to obtain the data that is received. However, in some environments, you may experience problems retrieving certain types of data (eg. an environment may not support binary data within string data types). In this case use the Receive method to access the data.

Whenever this method is called, as many bytes of data as possible (up to the number specified by the RecvBytes parameter of the Receive method) are copied to the RecvBuf parameter passed to the Receive method.

The Receive method takes a variant buffer (RecvBuf) and the maximum number of bytes to be copied into RecvBuf (specified by RecvLen) as its parameters, and returns a long. The Receive method copies the data received into the RecvBuf, and returns the number of bytes that was copied. In case of errors, the Receive method sets RecvBuf to NULL and returns 0. The application should ensure that the method was successfully executed by checking variant buffer or the return value.

In most cases the RecvLen will be set to the Bytes parameter of the OnReceive event. However, the application must ensure that the RecvBuf is big enough to receive RecvLen bytes of data.

Usually this method is called during an OnReceive event. This event informs the application that more data has arrived from the connected host. At this point, the application should read all the data available and process it. The Bytes parameter in the OnReceive event indicates the number of bytes received.

Dim RecvBuf(1024) As Byte
Dim Len As Long

Sub Http_OnReceive (Buffer As String, Bytes As Long)
...
RecvLen = Bytes
' read data in buffer
Len = Http.Receive (RecvBuf, RecvLen)
...
End Sub

Initialize various components.

The Start method initializes various components of the HTTP control. This method must be called once before calling any other method. The Get, Head and Post methods will fail if the control is not initialized.

Usually the Start method is called when the application is loaded. The Stop method must be called before the application quits to cleanup any initialized components.

The Start method returns True if successful, otherwise, it returns False.

Result = Http.Start ()

Cleanup initialized components.

The Stop method cleans up the various components initialized using the Start method. This method must be called before quitting the application. Usually the Start method is called when the application is loaded and the Stop method is called just before the application quits.

To ensure proper behavior of the HTTP control, the application must initialize and cleanup in the manner described.

The Stop method returns True if successful, otherwise, it returns False.

Result = Http.Stop ()