                                  TWebFileInfo

                                  Version 0.81
                               October 20th, 1998

                       Copyright 1998 Computer Solutions
                              Released as FreeWare


Description

  TWebFileInfo retrieves information about a product from the product's
  home page.  It can be used in your application to determine if a newer
  version of the product exists on the home page.  If a newer version is
  available, TWebFileInfo can download a file via HTTP and run the update.

  This component is not designed to determine information on random files on
  random servers.  Rather, the home page must be intentionally updated to
  provide the information to TWebFileInfo.

  TWebFileInfo was written by Jon Robertson.  I can be contacted via email at
  JonRobertson@pobox.com.


License

  This component may be used freely and distributed in commercial or private
  environments, provided this notice is not modified or removed and there is
  no charge for the component other than nomial handling fees.  This component
  may be included in compilations of other software, as long as there is no
  charge for TWebFileInfo specifically.

  DFS.INC is Copyright 1996-1998, Brad Stowers, used by permission.  Please
  observe Brad's DFS license agreement when using or distributing DFS.INC.
  Brad's DFS web page is located at http://www.pobox.com/~bstowers/delphi.

  TWebFileInfo uses THttpCli from the excellent freeware Internet Component
  Suite, used by permission.  ICS is Copyright 1997-1998, Francois Piette, All
  Rights Reserved.  ICS is available at http://www.rtfm.be/fpiette/indexuk.htm


How It Works

  TWebFileInfo will retrieve the home page and parse it for certain META Tags
  which provide information to TWebFileInfo.  These tags do not affect the
  appearance of the home page and are hidden to the normal user.

  If TWebFileInfo determines that an update is available, you have the option
  of downloading the update via HTTP and running it once the download is
  complete.

  I recommend using TVersionInfoResource from Brad Stower's DFS page to
  retrieve version information about your application at run-time.  Brad's
  DFS page is located at http://www.pobox.com/~bstowers/delphi/

  I recommend Inno Express by Jordan Russel for creating a self-contained
  Setup program for your application.  The home page for Inno Express is
  http://www.connect.net/jordanr/isinfo.htm


Special Note For Previous Users

  Versions before 0.70 did not use modal dialogs.  This caused problems
  because your application was still accessible while an update was
  downloading (among other problems).

  Version 0.70 does use modal dialogs.  However, you do not have the option
  of providing a custom user interface with this version.  The wfioDisplayUI
  flag is forced to True in this version.

  Users who have already created an user interface for a previous version may
  use the 0.62 source which is included in this archive.  Note however that
  0.62 will not be supported.

  If REQUESTED, I'll rewrite the component to allow the programmer to create
  a custom user interface.


Installation Instructions for ICS users

  If you already have Internet Component Suite by Francois PIETTE installed,
  do NOT install the package provided for WebFileInfo.  Create a directory
  for the package.  Copy the files from the Source directory into the new
  directory.  Start Delphi or C++ Builder if it isn't running already.  From
  the main menu, select Component|Install Component|Browse (it does not matter
  if you may specify an existing package or a new package).  Now locate the
  WebFileInfo.pas source file in the newly created directory.


Installation Instructions for Delphi 2

  Delphi 2 does not support packages.  In order to use WebFileInfo with D2 you
  must download and install Francois PIETTE's Internet Component Suite.
  The ICS home page is at http://www.rtfm.be/fpiette.

  Once you have installed ICS, follow the instructions for ICS users above.


Installation Instructions for Delphi 3 and Delphi 4

  Create a directory for the package.  Copy the files from the WebFileInfoD3
  directory into the new directory.  Start Delphi if it isn't running
  already.  From the main menu, select Component|Install Packages|Add.  Now
  locate the WebFileNfo package in the newly created directory.


Installation Instructions for C++ Builder 1

  C++ Builder 1 does not support packages.  In order to use WebFileInfo with
  BCB1 you must download and install Francois PIETTE's Internet Component
  Suite.  The ICS home page is at http://www.rtfm.be/fpiette.

  Once you have installed ICS, follow the instructions for ICS users above.


Installation Instructions for C++ Builder 3

  Create a directory for the package.  Copy the files from the WebFileInfoC3
  directory into the new directory.  Start C++ Builder 3 if it isn't running
  already.  From the main menu, select Component|Install Packages|Add.  Now
  locate the WebFileNfo package in the newly created directory.


Properties

  To simplify the explaination of the properties, I will divide them into
  two groups.  The first group are local properties which are not affected
  by the content of the home page.  The second group of properties contain
  information retrieved from the home page.


Local Properties

  Active         - Determines if the component has retrieved information
                   about the URL.  Active is set to True once GetFileInfo()
                   has successfully retrieved the information.  If Active
                   is already set to True when GetFileInfo() is called,
                   the information is not retrieved a second time.

                   To force a recheck, set Active to False before calling
                   GetFileInfo() or CheckForUpdate().  Changing the HomeURL
                   property automatically sets Active to False.

  CurrentVersion - This should contain the current version of your product.
                   It will be compared against the version information
                   retrieved from the home page to determine if a newer
                   version is available.

  DateFormat     - Specify which format the product's date is stored in.  See
                   the section on DateFormat for more information.

  HomeURL        - This should contain the location of the product's home
                   page where the information will be retrieved from.

  InfoTags       - Set of strings containing the tag constants to search for
                   when the home page is parsed.  See the section on InfoTags
                   for more information.

  LastError      - String containing the last error.  This is usually an error
                   provided by WinSock or the HTTP component used.

  Options        - Set of options to control the run-time behavior of the
                   component.  See the section on Options for more information.

  ProxyHost      - Address of the proxy server to use, if required.

  ProxyPort      - Port of the proxy server to use, if required.

  UIFont         - Font to use for user interface.

  UIOwnerFont    - Flag to determine if parent's font should be used for
                   user interface.  Please see the section below on
                   UIOwnerFont.

  VersionFormat  - Determines how the version strings are compared.  See the
                   section on VersionFormat for more information.


Retrieved Properties

  DownloadURL      - This contains the location of the file to be downloaded.
                     It is used to download the update if requested.

  ProductAuthor    - The name of the product's author.

  ProductDate      - TDateTime containing the date of the product.  This value
                     is converted from ProductDateStr.  ProductDateStr must
                     be in one of the supported formats in order to convert
                     it to a TDateTime value.  See the section on DateFormat
                     for more information.

  ProductDateStr   - String containing the date of the product, retrieved from
                     the web page.  See the section on DateFormat for more
                     information.

  ProductName      - Contains the name of the product.

  ProductReadMe    - Contains the URL of the product's ReadMe.  This ReadMe
                     should be a text file because it is displayed in an
                     internal TMemo control.  If you want do use a non-text
                     format, take a look at ProductReadMeExt.

  ProductReadMeExt - Contains the URL of the product's extended ReadMe.  This
                     ReadMe can be in any format you choose as long as it is
                     supported by Win95.  The ReadMe will be downloaded and
                     executed via ShellExecute().

  ProductVersion   - Contains the version of the product.  Used to determine if
                     the file has been updated.

  RunParams        - Parameters passed to the update program.

                     For example, Inno Setup displays a dialog asking if the
                     user wants to install your program.  Since TWebFileInfo
                     already has a similar dialog, this dialog is redundent.
                     By sending /SP- as a parameter to Inno's SETUP.EXE, the
                     Inno dialog is not displayed.


Events

  OnDownloadProgress - Triggered while downloading the file via DownloadFile().
                       Two parameters are sent, BytesReceived and FileSize.
                       Very useful to display status to the user during the
                       download.

                       If the wioDisplayUI option is used, then the value of
                       OnDownloadProgress will be ignored and the event will
                       be handled internally.


Methods

  CheckForUpdate - This all-in-one function will determine if an update is
                   available, prompt the user to display the ReadMe file,
                   prompt the user whether to download the update, optionally
                   run the update after download, and optionally close
                   the application during the update.  GetFileInfo() and
                   DownloadFile() are called by CheckForUpdate(), as needed.

  GetFileInfo    - Retrieves the current information about a product from the
                   specified home page.

  DisplayReadMe  - Retrieves the current information and displays the current
                   ReadMe file available.

                   displayPrompt parameter determines if the routine should
                   prompt the user before displaying the ReadMe file.

  DownloadFile   - Retrieves the file from the URL specified in the DownloadURL
                   property.  The parameter destPath specifies where to store
                   the file.  destPath may also include a file name, which will
                   be used instead of the file name provided by the web page.


Options

  wfioAlwaysOverwrite  - Determines if the component should check for an
                         existing file with the same name before downloading.

  wfioDisplayReadme    - Determines if CheckForUpdate should provide the user
                         the option of viewing the ReadMe file before
                         downloading the update.

  wfioDisplayUI        - When set, a status dialog is automatically displayed
                         while the update is downloading.
        
                         NOTE:  The wfioDisplayUI flag is forced to True in
                                this version.  Please email me if you need to
                                turn this option off.

  wfioRunUpdate        - When set, the update is automatically executed after
                         downloading.  This is most useful when the update is
                         enclosed in a Setup program.

  wfioExitDuringUpdate - When set, the component will close the application
                         using Application.Terminate once the update program
                         has been started.  This is most useful when the
                         update is enclosed in a Setup program.

                         Make sure you are aware of Application.Terminates
                         behavior before using this option.

DateFormat

  The product's date is stored on the web page as a string.  In order to
  convert the string (ProductDateStr) to a TDateTime value (ProductDate),
  the format of the date must be known.

  There is very limited support for different date formats.  If the format that
  you want to use is not supported, send me email and I'll add support for it.

  The following date formats are supported:

  wfidDFSDate - The date is formatted as such: AAA[.] [#]#, ####
                Months other than May are abbreviated using the first three
                letters of the month.  The period only appears after the month
                if the month is abbreviated.


VersionFormat

  Originally, the version values were compared as strings.  However, this does
  not always work.  If your user has version 1.7 and version 1.10 is available,
  TWebFileInfo would report that an update was NOT available.  Here are the
  supported formats:

  wfivBuildNumber  - Use this if your version string is a standard build
                     number.  Each value of the  (major, minor, release, build)
                     is extracted and compared as an integer.  1.3.10 is
                     recognized as newer than 1.3.7.

  wfivSimpleString - The version values are compared as strings, as previously
                     done.  Use this if do not want to use a build number for
                     your version string ("Version 1.7" for example).  However,
                     be aware of the problem when comparing numbers as strings.
                     You might want to use "Version 1.07" instead in the above
                     example.


InfoTags

  In order to determine information about the product from the home page,
  the information is stored in META tags within the home page's source.

  The InfoTags property allows you to specify the names of each tag.
  TWebFileInfo will assign the content of each tag to the property that
  corresponds to the tag name.  If you omit a particular tag name, the
  corresponding property will not be filled.

  Here is a list of the tag names and the corresponding properties:

  AuthorTag      -- ProductAuthor
  DateTag        -- ProductDateStr
  DownloadTag    -- DownloadURL
  ProductNameTag -- ProductName
  ReadMeTag      -- ProductReadMe
  ReadMeExtTag   -- ProeuctReadMeExt
  RedirectTag    -- N/A
  RunParamsTag   -- RunParams
  VersionTag     -- ProductVersion

  Here is an example of the META tags used on the home page for Jon's
  Downloader:

 <META HTTP-EQUIV="dfs-name" CONTENT="Jon's Downloader">
 <META HTTP-EQUIV="dfs-version" CONTENT="1.4.1">
 <META HTTP-EQUIV="dfs-date" CONTENT="Sep. 2, 1998">
 <META HTTP-EQUIV="dfs-author" CONTENT="Jon Robertson">
 <META HTTP-EQUIV="dfs-url" CONTENT="http://www.pobox.com/~bstowers/delphi/freeware/files/downloadersetup.exe">
 <META HTTP-EQUIV="dfs-readme" CONTENT="http://www.pobox.com/~bstowers/delphi/freeware/files/downloader.txt">
 <META HTTP-EQUIV="dfs-runparams" CONTENT="/SP-">


Product ReadMe

  You can display either a ReadMe that is either text format or some other
  format.  Using ReadMeTag, the ReadMe will be downloaded and displayed in a
  TMemo control.  Using ReadMeExtTag, the ReadMe will be downloaded and
  executed via ShellExecute.

  ReadMeExtTag is checked first, and if a value exists for the tag, that
  file is downloaded and executed.  If EITHER the file fails to execute OR
  ReadMeExtTag does not have a value, then the ReadMeTag file is downloaded
  and displayed.


Redirection

  TWebFileInfo supports page redirection through the RedirectTag.  This would
  be handy if you move your product's home page for one reason or another.  The
  redirection tag informs TWebFileInfo where the new page is located so the
  version information will be retrieved from the new page.

  I strongly recommend assigning a value to RedirectTag even if you don't need
  redirection.  The reason is because once redirection becomes necessary, the
  old versions of your application will already know what tag to check for the
  redirection information.


UIOwnerFont

  I wanted to mimick the behavior of ParentFont.  I even tried responding to
  the CM_PARENTFONTCHANGED message.  However, this is not possible since
  TComponent's do not have a Parent property.  Therefore, there is no parent
  to get the font from.  Also, TComponents do not receive the
  CM_PARENTFONTCHANGED message.

  So UIOwnerFont is implemented as the Owner's font.  I don't know how to
  receive notification that the Owner's font has changed without rewriting
  TObject.  Therefore, every time the UIFont property is read, a check is done
  to see if UIOwnerFont is set.  If so, UIFont is assigned the Owner's font.

  Also, the code depends on the owner being descended from TForm.  If the
  Owner is not descended from TForm, then FUIOwnerFont has no affect.  This
  is Ok for components created at design-time.  However, be aware of this
  behavior if creating TWebFileInfo objects in code.  For example,
  UIOwnerFont will not work with an object created with the call
  TWebFileInfo.Create(Application);
  

16-bit Support

  Due to personal coding style, TWebFileInfo is not compatible with D1.
  I've decided not to support D1 unless there it is specifically requested.

  The internal Internet/WinSock support is provided by the Internet Component
  Suite by Francois PIETTE.  ICS is compatible with Delphi 1. In order to use
  TWebFileInfo in Delphi 1, you need to download and install ICS.  The ICS
  home page is at http://www.rtfm.be/fpiette.


Future Revisions

  There will be a 0.82 shortly that is mainly cleanup work.  And I'll probably
  add the ability to wait until the ProductReadMeExt has finished executing
  before continuing with the next dialog.

  Version 1.00 will have a help file with design-time context support.

  Support for additional date formats as requested.


Author's Comments

  I would like to thank Brad Stowers for his help with this project.  It was
  Brad's generosity which prompted this project.  Brad provides the home page
  for Jon's Downloader, one of my freeware applications.  I wanted the ability
  to check for updates via the program without loading a web browser.  Brad
  was very responsive to the idea and even modified his web pages and scripts
  to provide the META tags.

  I would like to thank Francois Piette for the work he has done with ICS.  I
  could not get NetMasters' FastNet components to work.  And NetMasters will
  not support them unless you pay for the support.  Francois' components are
  free, well supported, and work across all versions of Delphi and C++ Builder.

  A quick note about the demo projects:  The projects were created with
  Delphi 3 and C++ Builder 3.  I did not create separate projects for each
  version because it is a hassle (well it is).  If you are having problems
  compiling the demo in a different version, feel free to email me.  I'll do
  my best to help.


Revision History

0.10  + Full implementation using Internet Component Suite is finished.

0.20  + Complete rewrite.
      + Added run-time user interface.
      + Provided options to allow use on pages other than DFS.
      * Removed all support for NetMasters components.

0.30  + Added a cancel button to the download progress dialog.
      * Renamed FileNameTag to ProductNameTag and FileName to ProductName.
      * Renamed other tag names to match "Product" scheme.
      * Derived TWebInfoTags from TPersistent
      * Cleaned up the download progress dialog.  Added the ability to cancel
        a download when wioDisplayUI is used.
      * Corrected return value of DownloadFile.
      * Replaced the TBrowseDirectoryDlg machanism with TSaveDialog.
      * Modified GetFileInfo() to make sure at least one tag was present.

0.40  * Improved this text file.
      * Changed the wioDisplayUI option so it ignores the assigned
        DownloadProgress event instead of replacing it.
      * Improved the "Version x is available" dialog.
      * The Form.Cursor property is set to an hourglass instead of the
        Screen.Cursor property.  This may change again in V1.00.

0.50  + Added "Please Wait" dialogs.
      + Added "Do you want to install" dialog.
      + Added "Read Me" dialog.
      * Moved TWebDlProgress creation to code.  Removed TWebDlProgress form
        file.
      * Moved TWebDlProgress code to WebFileInfo.pas.  Removed
        webdlprogress.pas.
      * If no extension is provided for the file name, the extension of the
        current filter is used.  The only two extensions currently in the
        SaveDialog's filter are .EXE and .ZIP.
      * Cleaned up GetFileInfo.
      * Corrected problem which ignored tag names that did not contain "dfs".

0.60  + Added DateFormat property.
      + Added DisplayReadMe method.
      + Added UIFont property.
      + Added UIOwnerFont property.
      + Added TWfiVersion property editor to provide read only
        ComponentVersion property.
      + Began replacing string constants with consts/resourcestrings.
      * Renamed TWebInfoOption, TWebInfoOptions, and underlying option values.
      * Renamed TWebInfoTags.

0.61  * Fixed access violation which occurred if GetFileInfo was unsuccessful.
        Thanks to Holger Dors for finding this.

0.62  * Finished replacing string constants with consts/resourcestrings.  This
        should simplify creating international apps which use TWebFileInfo.
        Note that the number of string constants seems excessive.  Later I'd
        like to streamline these strings, if possible.

0.70  + Added support for update program parameters via FRunParamsTag and
        RunParams property.
      + Added support for page redirection via FRedirectTag.
      * Switched from synchronous WinSock routines to asynchronous routines.
      * Switched from non-modal dialogs to modal dialogs.
      * Force wfioDisplayUI to quickly implement modal dialog support.  Adding
        support for a custom UI will require a complete rewrite.

0.80  + Added VersionFormat property.
      + Added demo projects.
      * Removed ComponentVersion property and property editor.  Replaced it
        with a component editor which provides version information in the
        component's context (popup) menu.

0.81  + Added ReadMeExtTag InfoTag and ProductReadMeExt property.
      * Fixed bug which prevented lowercase META tags from working.
      * Modified the download dialog to display comma formatted byte values.
