'
' =============================================================================
' QFileAssociation           April 2004                     by Jacques PHILIPPE
'
'             Association of an Executable to a File Extension
'                 with Possibility to restore the Old one
' Documentation                                              Version 0.0.1 Beta
' =============================================================================
'        *****  WITH NO WARRANTY. USE AT YOUR OWN RISK. I USE IT  *****
' =============================================================================
' For All Examples :
' ----------------
'    $Include "QFileAssociaton.Inc"
'    Dim myFA As QFileAssociation
'
' Example 1 : simple setting of a new file association WITHOUT the possiblilty to
' ---------   restore the one that was set before.
'
'    myFA.SetFileAssociation (".Bas", "C:\RapidQ\RapidQ.Exe")
'
' Example 2 : setting of a new file assiociation WITH the possibility to restore
' ---------   the one that was set before.
'
'    myFA.NewDefaultDescriptorValue = "BAS_JFE"  ' Any name for the new descriptor
'    myFA.BU_Prefix = "YOUR_MARK"                ' Any mark : used to create back up of old FA
'    myFA.SetFileAssociationAndSaveOld (".bas", "C:\\RapidQ\\JFE\\JFE.EXE %1")
'
' Example 3 : restoring the previous file association
' ---------
'
'    myFA.BU_Prefix = "YOUR_MARK"      ' This is a Mark used to create back up of old FA
'    myFA.Restore (".bas")
'
' Example 4 : reading all the keys and values relative to a file association.
' ---------   This method helps to debug your FA.
'
'    Print myFa.ShowRelatedKeysAndValues (".Bas")
'
' Example 5 : Methods SetFileAssociation, SetFileAssociationAndSaveOld and Restore return an
' ---------   error number (if <16 then all is OK). That error number is transformed into a
'             error text by the method GetFileAssociationErrorAsString
'
'    Print GetFileAssociationErrorAsString(myFA.SetFileAssociation (".Bas", "C:\RapidQ\RapidQ.Exe"))
'
' NOTE : you should set up once and for ever QFileAssociation.BU_Prefix in the QFileAssociation
'        Code. So you will never have to bother about it anymore. But it's not mandatory.
' =============================================================================
' PROPERTIES
' =============================================================================
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' X   ALL PROPERTIES, TO THE  EXCEPTION OF BU_Prefix, ARE RESET TO DEFAULT    X
' X                                                                           X
' X   VALUES AFTER METHODS SetFileAssociation, SetFileAssociationAndSaveOld   X
' X                                                                           X
' X                     AND Restore HAVE BEEN CALLED.                         X
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' -----------------------------------------------------------------------------
'    NewDefaultDescriptorValue  String    Used when FA set with restore possibility, it like
'                                         a 'name' for the new file assciation. Will be used
'                                         in Registry Key to identify the FA.
'                                         Default value is "" and will result in a Descriptor
'                                         like this "BAS_File" for extension ".Bas"
' -----------------------------------------------------------------------------
'    DefaultIcon                String    A path to an Icon that will be associated with the
'                                         file Extension.
'                                         Default value is "", the result will be that the
'                                         icon of the application associated with the
'                                         extension will be used.
' -----------------------------------------------------------------------------
'    OpenType                   String    "Open", "Print" or "Explore" see API ShellExecute
'                                         documentation.
'                                         Default value is "Open"
' -----------------------------------------------------------------------------
'    Open                       String    ??? dont know ??? Let it unset !
'                                         Default Value is ""
' -----------------------------------------------------------------------------
'    BU_Prefix                  String    A string used to identify your file associations
'                                         Back Up in the Registry. Set it once for all in
'                                         the code of your QFileAssociation.Inc file :
'                                           - in the PRIVATE PROPERTIES AREA, uncomment
'                                             BU_Prefix As String
'                                           - in the PUBLIC PROPERTIES AREA, comment
'                                             BU_Prefix As String
'                                           - in the CONSTRUCTOR, replace "YOUR_MARK" by IE
'                                             "JDOE" if you're called JAMES DOE !
' -----------------------------------------------------------------------------
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' X   ALL PROPERTIES, TO THE  EXCEPTION OF BU_Prefix, ARE RESET TO DEFAULT    X
' X                                                                           X
' X   VALUES AFTER METHODS SetFileAssociation, SetFileAssociationAndSaveOld   X
' X                                                                           X
' X                     AND Restore HAVE BEEN CALLED.                         X
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' =============================================================================
' METHODS
' =============================================================================
' -----------------------------------------------------------------------------
' Function SetFileAssociation (FileExtension As String, Command As String) As Long
'       - FileExtension : the file extension with its dot to be associated with the
'                         command : IE  ".Bas". Maximum 4 characters + the dot (IE : ".JPEG")
'       - Command : the path of the application to execute for that file extension
'                   add " %1" if the file must be passed to the application as a command line
'                   argument (always add %1).
'       - returned values (more than one error is possible) :
'               SFA_SIMPLE_SET_ALL_OK = 2
'               SFA_ERROR_FILE_ASSOCIATION_BUSY = 256
'               SFA_ERROR_EXTENSION_IS_AN_NULLTRING = 512
'               SFA_ERROR_EXTENSION_MORE_THAN_FOUR_CHARACTERS = 16384
'
'    Simply set a new file assiciation. The old one is overwritten.
'
'    Example : iError = myFA.SetFileAssociation (".Bas", "c:\Windows\Notepad.Exe %1")
'
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' X   ALL PROPERTIES, TO THE  EXCEPTION OF BU_Prefix, ARE RESET TO DEFAULT    X
' X                                                                           X
' X   VALUES AFTER METHODS SetFileAssociation, SetFileAssociationAndSaveOld   X
' X                                                                           X
' X                     AND Restore HAVE BEEN CALLED.                         X
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' -----------------------------------------------------------------------------
' Function SetFileAssociationAndSaveOld (FileExtension As String, Command As String) As Long
'       - FileExtension : the file extension with its dot to be associated with the
'                         command : IE  ".Bas". Maximum 4 characters + the dot (IE : ".JPEG")
'       - Command : the path of the new application to execute for that file extension.
'                   Add " %1" if the file must be passed to the application as a command line
'                   argument (always add %1 :).
'       - returned values (more than one error is possible) :
'               SFA_SET_RESTORABLE_ALL_OK = 1
'               SFA_ERROR_FILE_ASSOCIATION_BUSY = 256
'               SFA_ERROR_EXTENSION_IS_AN_NULLTRING = 512
'               SFA_ERROR_BACK_UP_OLD_ALREADY_EXISTS = 64
'               SFA_ERROR_NO_EXTENSION_DESCRIPTOR_DEFINED = 32
'               SFA_ERROR_EXTENSION_NOT_YET_DEFINED_CANT_SAVE_OLD_DESCRIPTOR = 128
'               SFA_ERROR_INVALID_OPENTYPE_OPEN_SET = 16
'               SFA_ERROR_EXTENSION_MORE_THAN_FOUR_CHARACTERS = 16384
'    Descriptors named YOUR_MARK_OLD, YOUR_MARK_NEW are created so that the OLD file
'    association can be restored and the new deleted. This function can only be used once
'    even if NewDefaultDescriptorValue is change (to avoid multiple new keys and values
'    to be add to the Registry). After calling Restore, it's possible to call this
'    function anew.
'
'    note : Properties NewDefaultDescriptorValue, DefaultIcon, OpenType, Open, BU_Prefix
'                      will be used to set file association with this function.
'
'    example : iReturn = myFA.SetFileAssociationAndSaveOld (".bas", "C:\RapidQ\JFE\JFE.EXE %1")
'
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' X   ALL PROPERTIES, TO THE  EXCEPTION OF BU_Prefix, ARE RESET TO DEFAULT    X
' X                                                                           X
' X   VALUES AFTER METHODS SetFileAssociation, SetFileAssociationAndSaveOld   X
' X                                                                           X
' X                     AND Restore HAVE BEEN CALLED.                         X
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' -----------------------------------------------------------------------------
' Function Restore (FileExtension) As Long
'       - FileExtension : the file extension to be restored : IE  ".Bas".
'               Maximum 4 characters + the dot (IE : ".JPEG")
'       - returned values (more than one error is possible) :
'               SFA_RESTORE_ALL_OK = 4
'               SFA_ERROR_FILE_ASSOCIATION_BUSY = 256
'               SFA_ERROR_EXTENSION_IS_AN_NULLTRING = 512
'               SFA_ERROR_RESTORE_FA_KEY_MISSING_CANT_RESTORE = 4096
'               SFA_ERROR_RESTORE_NEW_AND_OR_OLD_DESCRIPTOR_MISSING_CANT_RESTORE = 1024
'               SFA_ERROR_RESTORE_EXTENSION_KEY_DONT_EXIST = 2048
'               SFA_ERROR_EXTENSION_MORE_THAN_FOUR_CHARACTERS = 16384
'    Restores the 'old' file association and delete the 'new' ! Nothing from the 'new'
'    file association is left in the Registry.
'
'    note : BU_Prefix is used to look for descriptors named YOUR_MARK_OLD, YOUR_MARK_NEW
'        so BU_Prefix used here must be the same than the one used when setting the 'new'
'        file association.
'
'    Example : iReturn = myFA.Restore (".Bas")
'
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' X   ALL PROPERTIES, TO THE  EXCEPTION OF BU_Prefix, ARE RESET TO DEFAULT    X
' X                                                                           X
' X   VALUES AFTER METHODS SetFileAssociation, SetFileAssociationAndSaveOld   X
' X                                                                           X
' X                     AND Restore HAVE BEEN CALLED.                         X
' XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
' -----------------------------------------------------------------------------
' Function ShowRelatedKeysAndValues (FileExtension As string) As string
'       - FileExtension : the file extension with its dot you want to see the Registry datas
'             relative to that file extension : IE  ".Bas"
'       - returned value is a formatted string showing all Registry Keys and values relative
'             to that file association.
'
'    Returns a formatted string showing all the Registry Keys and values relative to this file
'    association.
'    It helps to debug file association (easier than editing the Registry).
'
'    Example : Print ShowRelatedKeysAndValues (".Bas")
' -----------------------------------------------------------------------------
' Function GetFileAssociationErrorAsString (Error As Long) As String
'       - Error : is the integer value returned by the methods SetFileAssociation,
'             SetFileAssociationAndSaveOld and Restore.
'       - returned value is a formatted string containing text about the error(s). More than
'             one error is possible.
'    Example : Print (GetFileAssociationErrorAsString(myFA.Restore (".Bas")))     
' -----------------------------------------------------------------------------
' =============================================================================
' BASIC FILE ASSOCIATION REGISTRY STRUCTURE
' =============================================================================
' There are something like 100.000 keys and values in your Registry. So adding five or ten
' more is not a problem.
' ----------------------------------------------------------------------------------------------------------------------------------------
'              Path         Keys                   |  ValueName        |   ValueData           | Note
' ----------------------------------------------------------------------------------------------------------------------------------------
' HKEY_CLASSES_ROOT
'   |___________ '.Bas'  __________________________ "" (default value)  "BAS_File"              "BAS_File" is the Default Descriptor
'   .                              |_______________ "YOUR_MARK_OLD"          "BAS_JFE"               "BAS_JFE"  is a new Descriptor (not used)
'   .
'   |___________ 'BAS_File' _______________________ (no defined value)
'   .               |__ 'Shell' ___________________ "" (default value)  "Open"                  BTW maybe "Open", "Print", "Explore"
'   .                      |__ 'Open' _____________ (no defined value)
'   .                             |__ 'Command' ___ "" (default value)  "C:\path\BasIde.exe %1 %2 %3"
'   .
'   |___________ 'BAS_JFE' ________________________ (no defined value)
'   .               |__ 'Shell' ___________________ "" (default value)  "Open"                  BTW maybe "Open", "Print", "Explore"
'   .                      |__ 'Open' _____________ (no defined value)
'   .                             |__ 'Command' ___ "" (default valur)  "C:\JFE\JFE.EXE %1 %2"
' ----------------------------------------------------------------------------------------------------------------------------------------
'
' Registry is composed of Keys (like directories), ValueNames (like files) and ValueDatas for that
' ValueName. For FileAssociation ValueDatas are all Strings (but elsewhere, integer, binary, ... are
' possible)
' As Directories, Keys are organised hierachically. A Key can contain many ValueNames (Variables)
' and the ValueName may have a single ValueData. A special ValueName is "" the default value, it's
' the one that most often contains the used ValueData.
'
' regedit.exe or regedt32.exe allows to edit the Registry.
'
' The RapidQ  QRegitry.Html is the most flawed RapidQ documentation file I ever read :)
' ------------------------------------------------------------------------------------------------------------------
'