Introduction
jsTP.exe is an ActiveX EXE that can be used to download files via HTTP using script.
It also has specific functionality for use with RSS feeds.
An ActiveX EXE is a COM object. That is, it can be created with CreateObject
and provides various properties and methods that are available to any COM compatible
programming system, such as script.
jsTP Requirements:
jsTP.exe uses the older Windows winsock library (v. 1.1) to provide its functionality, so it
can be used on all Windows versions, starting from Win95. The only dependency (other file
required for use) is the VB6 runtime (MSVBVM60.DLL). The VB6 runtime is pre-installed on
WinME, 2000, XP and will be present on any system where any Visual Basic 6 software has
ever been installed. If you receive an error message about MSVBVM60.DLL see the JSWare
install tips page for information about getting the VB6 runtime.
Like any COM component, jsTP must be registered with the system before use.
If it is not registered you will receive an error: "Could not create ActiveX object..." when using
CreateObject. An ActiveX EXE is registered in a different way from an ActiveX DLL or OCX.
To register jsTP.EXE, place the file in the system folder. Then open Start -- Run and type
the following:
C:\Windows\System\jsTP.exe /regserver
To unregister before removing jsTP from the system, use:
C:\Windows\System\jsTP.exe /unregserver
(Note that path of file may need to be changed to match the path of your system folder.)
General usage tips:
In order to download files, jsTP must first be initialized by calling
StartUp. If StartUp is not called you will receive an error when RequestFile
is used, such as "Winsock error - Failed to create socket."
Once initialized, any number of files can be downloaded by using the
RequestFile method and then waiting for the OnDownloadFinish event. The RollPage.vbs
file shows how that can be done by using the Busy property to keep the script
looping between the time a server request is made and the time that download is completed (or fails).
When all files are downloaded, ShutDown should be called to disconnect jsTP.
If it is not called, jsTP will still disconnect when it is unloaded but it should not be done
that way. jsTP uses Windows Sockets services. It is the nature of Windows Sockets
that usage must be initialized and then "deregistered". Also, an ActiveX EXE may not be
unloaded when a script is ended if it is not explicitly set to nothing.
This is an
important point: When finished downloading files always
use:
TP.ShutDown
Set TP = Nothing
If those lines are not used, jsTP could end up running in the background,
still connected to the Windows Sockets service, after your script is finished.
Back to Top
Properties, Methods and Events
Property Port
• Port number for connection. Default is 80.
ex.: TP.Port = 81
Back to Top
Property Online
• Whether there is currently an online connection. Boolean.
ex.: If TP.Online = True Then ...
Notes: An online connection must be present for jsTP to work.
There is no connecting or dialup function.
Back to Top
Property ProxyConnection
• Whether the online connection is through a proxy. Boolean.
ex.: If TP.ProxyConnection = True Then ....
Notes: There may be special considerations if you are using a proxy connection.
jsTP contacts a specified server address to request files for download.
It may not always work through a proxy connection.
Back to Top
Property Busy
• Whether jsTP is currently busy with a server transaction. Boolean.
ex.: If TP.Busy = True Then ....
Notes: Property Busy is used to keep a script alive while using jsTP.
Since it takes time to contact a server and download a file, a script waiting
for the download to finish must have a way to maintain the pause without
quitting. Busy provides that method. When jsTP successfully sends a file
request Busy is set to True. When the OnDownloadFinish event occurs,
Busy is set to False. The script can therefore be made to wait during downloads
by using the following:
While TP.Busy = True
Wend
Back to Top
Property CurSize
• Returns size of current file download in bytes.
ex.: Num = TP.CurSize
Notes: The CurSize property refers to the current download.
The property is only valid after a download has finished and before
another download is attempted. If you want to know the file size
CurSize should be used in the OnDownloadFinish event. If it
is used before that it will return 0. jsTP does
not ask the server for the file size. It just records the number of bytes received.
So it cannot return an accurate file size until the download is completed.
None of the file properties or functions should be used before OnDownloadFinish has occurred. They could conflict with the download process.
Back to Top
Property CurFileAsString
• Returns current file download as a single string.
ex.: s = TP.CurFileAsString
Notes: CurFileAsString returns the current file download. This property
must not be used before the OnDownloadFinish event. If it is used before
download is completed it will return "".
The current file is available from the time the download is completed
until the time that another download is attempted.
None of the file properties or functions should be used before OnDownloadFinish has occurred. They could conflict with the download process.
Back to Top
Function StartUp(ErrString)
• Initializes jsTP for use.
ex.: LNumber = TP.StartUp(sErr)
ErrString - Returns error information if startup fails.
Return:
0-Success.
1-System not ready for network communication.
2-Winsock version 1.1 not supported.
3-A blocking winsock is already in use.
4-The limit on number of winsock tasks has been reached.
5-Error with parameter of WSAStartup call.
6-Unknown error.
Notes: StartUp must be called to initialize jsTP before use.
Back to Top
Sub ShutDown
• Shuts down jsTP.
ex.: TP.ShutDown
Notes: ShutDown should be called when download(s) are completed
so that jsTP can disconnect from the Windows Socket service used for network
communication.
Back to Top
Function RequestFile(Server, FilePath)
• Connect to specified server and request a file.
ex.: LNumber = RequestFile("www.somewhere.com", "/index.html")
Server is server URL. It must be formatted as shown. Do not include "http//"
or any slashes.
FilePath is the path of file on server. A file path starts with the slash
after URL. For example, the file http://www.somewhere.com/articles/help/help2.html
would be requested with: RequestFile("www.somewhere.com", "/articles/help/help2.html")
Return:
0-Request sent successfully. (This does not mean file is downloaded. It only means that
the server was contacted and the request was sent.
If there was an error, the function returns a number and the FilePath parameter returns
an error string:
99-SendData failed to send server request.
106-No Internet connection active.
107-Internet connection is via proxy server.
109-Winsock error - Failed to create socket. Error number:
110-Winsock error - Failed to connect to server. Error number:
111-Winsock err - Failure with WSAAsyncSelect. Error number:
112-Failed to resolve server IP address.
113-Server parameter is blank.
114-FilePath parameter is blank.
With errors 109-111 the Error number returned in the error string is a Winsock error
number. The Winsock error code numbers are included in the Winsock errors.txt file.
Notes: Once a request is sent successfully the next step will be to check the
returns in the OnDownloadFinish event.
Back to Top
Function WriteTextFile(Path, IfDelete)
• Writes current file download to disk as text file.
ex.: LNumber = TP.WriteTextFile("C:\webpage.html", True)
Path - Full path of file to write.
IfDelete - Whether to overwrite if file exists.
Return:
0-Success.
1-File exists (IfDelete = False).
2-No bytes to write.
3-No current file.
Notes: A file can be written any time after the OnDownloadFinish event occurs with
a successful result, until another download attempt is made.
None of the file properties or functions should be used before OnDownloadFinish has occurred. They could conflict with the download process.
Back to Top
Function WriteBinaryFile(Path, IfDelete)
• Writes current file download to disk as binary file.
ex.: LNumber = TP.WriteBinaryFile("C:\pic.jpg", True)
Path - Full path of file to write.
IfDelete - Whether to overwrite if file exists.
Return:
0-Success.
1-File exists (IfDelete = False).
2-No bytes to write.
3-No current file.
Notes: A file can be written any time after the OnDownloadFinish event occurs with
a successful result, until another download attempt is made.
None of the file properties or functions should be used before OnDownloadFinish has occurred. They could conflict with the download process.
Back to Top
Function FormatCurCSS(NumberItems As Variant, IfDescription As Variant)
• Returns a formatted HTML string for use with RSS feeds.
ex.: s1 = TP.FormatCurRSS(10, True)
NumberItems - Maximum number of items to include from RSS index page.
IfDescription - Whether to include description part of RSS item.
Return:
Returns formatted string on success. Otherwise returns "".
Notes: FormatCurRSS is designed to simplify the use of jsTP for
parsing the XML of RSS index pages. The string HTML returned contains the
contents of NumberItems number of items, if there are that many
available. The formatting includes style properties designed to allow
easy adjustment of the graphical style.
The returned string includes website title followed by
the items. Each item includes title, date(if available), author(if available),
description(if IfDescription is set to True), and link.
The returned string can be inserted into an HTML page to provide
a clearly laid out RSS listing. The details of the format are as follows:
<H2>Website Title</H2>
<H4> Item Title </H4>
<SPAN ID="T1"> Date </SPAN> <BR> (if present)
<SPAN ID="T1"> Author</SPAN> <BR> (if present)
<BR> <SPAN ID=T2> description </SPAN> <BR> <BR> (optional)
<A HREF="Link URL" TARGET="_blank"> Link URL</A> <BR> <BR>
The formatted text includes header HTML tags and style IDs so that the graphical
appearance of headers, links, descriptions, etc. can all be adjusted by using STYLE
properties in the webpage, without needing to edit the formatted text. The main page
title [H2] and item titles [H4] can each be assigned
style properties through the H2 and H4 tags. The Date and Author lines will both conform to
a style ID value of "T1". The description section text can be set by using a style ID of T2.
The link style can be set through the A tag.
Example:
#T1 {font-size: 13px; color: #800000; font-family: verdana, arial;}
#T2 {font-size: 13px; color: #000000; font-family: verdana, arial;}
H2 {font-size: 24px; color: #000000; font-family: arial}
H4 {font-size: 18px; color: #000000; font-family: arial; background-color: #E0E0E0;}
A {font-size: 13px; color: #0000FF; font-family: verdana, arial;}
Those style settings would result in a light gray bar behind item headers
with brown text for date and author, black text for description, and blue text for links.
A sample of styles in usage can be seen in the RollPage.vbs script file. It writes
a STYLE tag when creating a newsreader webpage.
Notes: The optional Description element of RSS items is filtered in the
process of formatting the text. All HTML tags are removed. The main purpose of that is to keep
a consistent appearance for each item when formatted items are used in a webpage, eliminating any
HTML that might conflict with the formatted styles. HTML removal also serves to avoid downloading ads, pictures and
tracking web bugs that may have been added to some RSS feeds.
None of the file properties or functions should be used before OnDownloadFinish has occurred.
They could conflict with the download process.
Back to Top
Event OnConnect(ServerURL)
• Occurs when connection is made with server. In most cases this event will probably
not be of use. ServerURL contains URL of server connected to.
Back to Top
Event OnDisconnect
• Occurs when connection is closed with server. In most cases this event will probably
not be of use.
Back to Top
Event OnDownloadFinish(ResponseCode, ResponseString)
• Occurs when file download process is complete, regardless of whether it was successful.
Return:
If connection with server failed, ResponseCode will be -1 and
ResponseString will be a text error message.
If server conversation was completed, ResponseCode will be the server
response code and ResponseString will be the server response string.
If the file was successfully, completely downloaded, server response will be 200
and the string will be "OK". Other codes can be, for example, 404- "Not found",
301- "Moved permanently", etc.
If ResponseCode is 200 the downloaded file will be available
through the jsTP file methods and properties (WriteTextFile, CurFileAsString, etc.) It can
then be written to disk, returned as a text string, or formatted with
the FormatCurRSS function.
Notes: In the case of server errors 301-303, which indicate the requested
file is at a new URL, the ResponseString will include not only the server
error string but also the server Location header, which contains the new file URL
in the following format:
Location: http://www.somewhere.com/newfile.html
Back to Top
License
You use all script code and components from JSWare at your own risk.
The components (compiled DLL and EXE files) may be used for personal or
commercial purposes. No payment or attribution is required for either use.
The components may be redistributed if they are required as support files
for scripts or software that you have written.
Also, the script code may be used freely, in part or as whole scripts,
for any purpose, personal or commercial, without payment or attribution.
I ask only that you not redistribute these scripts and components, except
as required for your direct use. Instead, please direct others to obtain copies
of JSWare scripts and components directly from www.jsware.net.
Also, none of the code here may be redistributed under another license. If a
work using code from JSWare is distributed with restrictions of any kind
the code from JSWare must be kept exempt from those restrictions.
This includes, but is not limited to, code sold for profit, code with usage restrictions
and code distributed as so-called "Open Source" with redistribution restrictions.
Joe Priestley
Back to Top