.-------+----------+--------- [Latest X] -------+---------------------:
        |                     LatestX System v1.00 by TuS                     |
        :-------+----------+----------+-----------------+---------------------:

Index
-----
    1)Features
    2)How it works
    3)Supported Functions
     3.1)FTPD Events
     3.2)USER Commands
    5)Requirements
    6)Setup & Install (w/RaidenFTPD)
    7)Configurable Options
    8)Credit
    9)Change Log

1)Features
-----------
    - Standalone Latest X directory system for RaidenFTPD
    - Creates Junction points for directory links
    - Supported events onNewDir, onDelDir, onNukeDir, onUnNukeDir
    - Integrates into RaidenFTPD VFS (For sections)
    - Supports Multiple Running RaidenFTPD servers
    - Coded in vbs which is natively supported by Windows
      (no third party engine needs to be installed to interpret the scripts)

2)How it works
---------------
The FTPD LatestX system monitors FTPD events for directory creation, deletion,
nukes, unnukes and maintains a collection of junction points to the most X recent folders
created on the FTPD.

Typically, the Junction points are created in "_VFTPDROOT\_LATEST" folder. Every
junction point is named [SECTION]-[ParentFolder]-RELEASE. Sections are extracted from the
FTPD VFS (See configuration options in the script file).

Junction point management is done by using Sysinternal's Junction v1.06 - Windows
junction creator and reparse point viewer.

3)Supported Functions
----------------------
3.1)FTPD Events

    NEWDIR
    FTPD Command MKD. Check and create the [NEWDIRS]\[SECTION]-[ParentFolder]-RELEASE
    Junction point in the FTPD ROOT.
    RaidenFTPD event: onNewDir

    DELDIR
    FTPD Command RMD. Check and delete the [NEWDIRS]\[SECTION]-[ParentFolder]-RELEASE
    Junction point from the FTPD ROOT.
    RaidenFTPD event: onDelDir

    ## TODO ## IGNORE THIS LINE ## missing FTPD variables to process the command
    MOVEDIR
    Monitors Directory move. Check and update the [NEWDIRS]\[SECTION]-[ParentFolder]-RELEASE
    Junction points in the FTPD ROOT.
    RaidenFTPD event: onMoveDir
    ## TODO ## IGNORE THIS LINE ## missing FTPD variables to process the command

    NUKEDIR
    Monitors FTPD NUKE. Check and update the [NEWDIRS]\[SECTION]-[ParentFolder]-RELEASE
    Junction points in the FTPD ROOT. This is recursive.
    RaidenFTPD event: onNukeDir

    UNNUKEDIR
    Monitors FTPD NUKE. Check and update the [NEWDIRS]\[SECTION]-[ParentFolder]-RELEASE
    Junction points in the FTPD ROOT. This is recursive.
    RaidenFTPD event: onUnNukeDir

3.2)USER Commands

    #    COMMAND: site latestx
        Show help
        .-------+----------+--------- [LatestX] --------+---------------------:
        | Syntax: site latestx <command>                                      |
        +-------+----------+----------+-----------------+---------------------+
        | Commands:                                                           |
        |    repair : Check existing LatestX entries (delete broken)          |
        |    clear  : Clear all LatestX entries (reset)                       |
        |                                                (Config: 25 folders) |
        :-------+----------+----------+-----------------+---------------------:

    #    COMMAND: site latestx clear
        Purge all existing junction points

        Command Output when Junctions points exists
        .-------+----------+--------- [LatestX] --------+---------------------:
        | Deleting 3 links...                                                 |
        +-------+----------+----------+-----------------+---------------------+
        |  01)[DIVX]-DIVX-FR_film2                                  : Deleted |
        |  02)[RIP]-APP2_this_Release                               : Deleted |
        |  03)[TV]-TV_Serie1.S01E01                                 : Deleted |
        |                                                   3 link(s) deleted |
        :-------+----------+----------+-----------------+---------------------:

        Command Output when No Junction point exists
        .-------+----------+--------- [LatestX] --------+---------------------:
        | No links to delete...                                               |
        :-------+----------+----------+-----------------+---------------------:

    #    COMMAND: site latestx repair
        Check and delete all broken junction points

        Command Output when Junctions points are good
        .-------+----------+--------- [LatestX] --------+---------------------:
        | Checking 5 links...                                                 |
        +-------+----------+----------+-----------------+---------------------+
        |  01)[DIVX]-DIVX-FR_film1                                       : OK |
        |  02)[DIVX]-DIVX-FR_film2                                       : OK |
        |  03)[RIP]-APP1_this_Release                                    : OK |
        |  04)[RIP]-APP2_this_Release                                    : OK |
        |  05)[TV]-TV_Serie1.S01E01                                      : OK |
        |                                               No links were deleted |
        :-------+----------+----------+-----------------+---------------------:

        Command Output when some Junctions points are broken
        .-------+----------+--------- [LatestX] --------+---------------------:
        | Checking 5 links...                                                 |
        +-------+----------+----------+-----------------+---------------------+
        |  01)[DIVX]-DIVX-FR_film1                                       : OK |
        |  02)[DIVX]-DIVX-FR_film2                                  : Deleted |
        |  03)[RIP]-APP1_this_Release                                    : OK |
        |  04)[RIP]-APP2_this_Release                               : Deleted |
        |  05)[TV]-TV_Serie1.S01E01                                      : OK |
        |                                                   2 link(s) deleted |
        :-------+----------+----------+-----------------+---------------------:

        Command Output when No Junction point exists
        .-------+----------+--------- [LatestX] --------+---------------------:
        | No links to check...                                                |
        :-------+----------+----------+-----------------+---------------------:

5)Requirements
    - Windows Script Host 5.6 or above
    - Script must be invoked by cscript engine
    - FTPD: RaidenFTPD 2.4.3902 or higher (possibily could work with lower)
    - Sysinternal's Junction v1.06 (Provided in the package)
    - NTFS File system to support NTFS Juction points
    - TuS's KeepNewest v1.00 utility (Provided in the package)

6)Setup & Install (w/RaidenFTPD)
    + Prerequisite
     This install "guide" assumes following:
      - RaidenFTPD installed to "C:\RaidenServer\RaidenFTPD",
      - You're VFS file is named same as the server name:
        ex: if the server is called "RaidenFTPD32", value provided by the "%h" 
        variable then your VFS file should be called "RaidenFTPD32.vfs".
     
     If this is not the case then you will have to adapt the settings in the config
     file.

    + System files
     Copy the content of this package to a folder.
     In this guide we use : "C:\RaidenServer\RaidenFTPD\Addons\LatestX"

    + Edit "LatestX.config" file
     Even though you have identical setup as described in this setup, open you're
     favorite text editor and inspect/edit the following file : "LatestX.config".
     Make sure every path and filenames matche you're configuration.
     DO NOT CHANGE ANY LOG LEVEL YET.

    + Cscript as default engine
     Set cscript as default script engine. To do this open command prompt and type
     the following: cscript //H:Cscript.
     You should receive this reply if successful: The default script host is now
     set to "cscript.exe". Default script engine in Windows is wscript. This is
     fine, if we would like messages to appear as a dialog. However this is a
     system which in most cases never will be monitored directly. An error with
     wscript engine will wait for someone to click a button, hence the script will
     never complete if an error occurs. This again might lead to multiple instances
     of unfinished script processes. It's possible to omit setting cscript as
     default engine, and call the script directly using "cscript scriptname".

    + Setup RaidenFTPD
     Create a new user (username: script / password: <anything>), this step is optional
     as it is not really used by the script. It is used to set the ownership of the
     "_LATEST" VFS entry so that the normal users cannot create or delete the script
     created    Junction Points.

     Locate your VFTPDRoot folder, it should allready contain an entry for each VFS
     entry. Using Explorer create the "_LATEST" folder (or any other name but be sure
     to have matching configuration in your config file : Const DIR_NAME = "_LATEST").
     Add a new VFS entry using raider VFS Editor:
        Physical Path: <Drive>\<VFTPDRoot>\_LATEST
        Virtual Path: _LATEST
        Owner: script
        Group: script
        Set the security as following
                                            R  W  X  L
                             Owner user     x  .  .  x
                             Owner group    x  .  .  x
                             Other group    x  .  .  x
     
     Save the VFS file and reload the server.

     Security setup on the _LATEST VSF entry is just to deny directory creation/deletion to normal
     users. If you want to be able to do this as a op then you would need to set the rights properly.
     But i would not recommend allowing that, just let the script do its job.

    FTPD event
    ----------------
    Go to the directory "C:\RaidenServer\RaidenFTPD" and open your server's *.ftpd
    file.

    Open your favorite text editor and look for the following:

    "OnNewDir=", replace it by the following line:
        onNewDir=exec://C:\WINDOWS\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\addons\LatestX\LatestX.vbs" "%@" "%h" "NEWDIR" "%G" "%r"

    "onDelDir=", replace it by the following line:
        onDelDir=exec://C:\WINDOWS\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\addons\LatestX\LatestX.vbs" "%@" "%h" "DELDIR" "%G" "%r"

    ## TODO ## IGNORE THIS LINE ## missing FTPD variables to process the command
    "onMoveDir=", replace it by the following line:
        onMoveDir=exec://C:\WINDOWS\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\addons\LatestX\LatestX.vbs" "%@" "%h" "MOVEDIR" "%G" "%r"
    ## TODO ## IGNORE THIS LINE ## missing FTPD variables to process the command

    "onNukeDir=", replace it by the following line: (the "%e/%r" is NOT a typo error)
        onNukeDir=exec://c:\windows\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\Addons\LatestX\LatestX.vbs" "%@" "%h" "NUKEDIR" "%G"  "%e/%r"

    "onUnNukeDir=", replace it by the following line: (the "%e/%r" is NOT a typo error)
        onUnNukeDir=exec://c:\windows\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\Addons\LatestX\LatestX.vbs" "%@" "%h" "UNNUKEDIR" "%G"  "%e/%r"

    Parameter Description
        Param 1: GCID    : Variable :  "@"     : used for the response outputs
        Param 2: Server  : Variable : "%h"     : used for the Server and VFS file Identification
        Param 3: CmdType : Static   : "NEWDIR" : used for the Command Type Identification
                                      "DELDIR"
                                      "MOVEDIR"
        Param 4: PhyPath : Variable : "%G" : the full physical dir/file name which the client just accessed
        Param 5: VirPath : Variable : "%r" / "%e/%r" : the virtual dir/file name which the client just accessed
        
        For Nuke/UnNuke the Virtual Path has to be built using variables %e and %r
        The "%e/%r" is NOT a typo Error

    !!! Save the file !!!

    Command dispatcher
    ------------------
    Now, go to the directory "C:\RaidenServer\RaidenFTPD\VirtulFS" and create a folder
    with the same name as you're server. You're server name can be found in *.ftpd.
    In this case it's RaidenFTPD32.

    Open your favorite text editor and create a file named sitecmd.ini in this directory.
    Copy the following into the file and save it:

    [root]
    [super]
    [normal]
    [guest]
    [EGGDROP-root]
    [EGGDROP-super]
    [EGGDROP-normal]
    [EGGDROP-guest]

    Each section represents a type of user. If you only want to allow root and super
    users to execute a command, you would insert the command into those sections.
    In this case we will allow only root and super users to perform LatestX command
    on our site.

    x86 System :
    [root]
    Latestx=ask://C:\WINDOWS\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\Addons\LatestX\LatestX.vbs" "%@" "%h" %!
    [super]
    Latestx=ask://C:\WINDOWS\System32\cscript.exe "C:\RaidenServer\RaidenFTPD\Addons\LatestX\LatestX.vbs" "%@" "%h" %!
    [normal]
    [guest]
    [EGGDROP-root]
    [EGGDROP-super]
    [EGGDROP-normal]
    [EGGDROP-guest]

    !!! IMPORTANT !!! !!! WARNING !!! !!! IMPORTANT !!! !!! WARNING !!!
    Some variables are in "", others are not. It's crucial to the system that you
    provide the arguments exactly as described in this documentation. This has
    something to do with how the various scripts interpret the arguments.

    Parameter Description
        Param 1: GCID    : Variable :  "@" : used for the response outputs
        Param 2: Server  : Variable : "%h" : used for the Server and VFS File Identification
        Param 3: Command : Variable :  %!  : Whole string for site command, not including 'site' itself

    !!! Save the file !!!

    +Restart the FTPD

    +Create a new folder and check that:
        - The event was fired (Raiden GUI) you can also have a look on the different params provided
          to the script
        - A new Juction point is created correctelly in "_LATEST"
        - That you can browse it using your FTP Client

    +Inspect script log
    Open the log directory <ScripthPath>\Logs and verify that the log only contain
    Information/Success    entries. If not you must correct the error according to the
    log.

    +Do the same thing for the 4 remaining FTPD event Delete, Move, Nuke, UnNuke and check the logs

    +Validate the different user commands
    You can import the provide LatestX.v1.0.fce FlashFxp Command export file for
    this. Sorry, i can not provide other FTP Client exports.

    +Tuning off logs
    Once that you're system is working flawless you can trun off the logs ie: Const FILELOG = 0
    to have better performance on execution time.
    Script has log "rollover". The rollover function makes sure that no more than n logs exist
    in your log directory. Number of logs can be tuned ie: Const NUMBEROFLOGS = 5.

    Now, there's really no point of logging if you're not going to read it.
    So if you know that you'll never read any log what's so ever, set log levels to 0:
        ie: Const EVENTLOG = 0
            Const FILELOG = 0

    WARNING! Do NOT use eventlog level 2 & 3. Default is 0, and we recommend you to keep it
    that way. If you insist on getting entries into eventlog, use level 1, and make sure you're
    eventlog do overwrite with new events.

7) Configurable Options

    '#------------------------------------#
    '#- Paths and Files Settings         -#
    '#------------------------------------#
    'RaidenFTPD Root folder
    Const RAIDENFTPD_PATH         = "C:\RaidenServer\RaidenFTPD"

    '#------------------------------------#
    '# Script settings                    #
    '#------------------------------------#
    ' Folder where the "virtual directories" should be displayed.
    ' Please create the folder by yourself. (e.g. "_LATEST") Don't use slashes!
    ' The directory should be created in Manually [VFTPDRoot] (check install notes)
    Const DIR_NAME = "_LATEST"

    ' Number of maximum "virtual directories" that will be created.
    ' The script will limit the number of junction points. Every time you create a
    ' new one the oldest will be deleted.(try keeping this under 50)
    Const DIR_VFS_MAX = 50

    ' Use Sections Definition in the VFS File
    ' if set to True the script will try to extract Sections from your servers's
    ' *.ftpd file
    ' False : _LATEST\RELEASE
    ' True    : _LATEST\[SECTION]RELEASE
    Const SECTIONS_ENABLED = True

    ' Level Section Definition in the VFS File
    ' This define where to look for Section Names in the VFS file
    '    ex: VFS Line is <PhysicalPath>|/APPZ|<User>|<Group>|766111|r|0|0|0|0|0|0|0|0|0|
    '        SECLEVEL = 1 will resolve to APPZ
    '    ex: VFS Line is <PhysicalPath>|/Incoming/APPZ|<User>|<Group>|766111|r|0|0|0|0|0|0|0|0|0|
    '        SECLEVEL = 2 will resolve to APPZ
    Const SECTIONS_LEVEL = 1

    ' This define the separator that should be inserted after the section
    '        SECTIONS_SEPARATOR = "" will result in [SECTION]RELEASE
    '        SECTIONS_SEPARATOR = "-" will result in  [SECTION]-RELEASE
    '        SECTIONS_SEPARATOR = "#" will result in  [SECTION]#RELEASE
    ' Do NOT use "/" "\" ":" or any other caracter that cannot be used in file naming
    Const SECTIONS_SEPARATOR = ""

    'Add Additional Directory Info [SECTION][ParentFolder1#ParentFolder2]RELEASE
    'to the Junction Points
    ' False : _LATEST\[SECTION]RELEASE
    ' True    : _LATEST\[SECTION][ParentFolder1#ParentFolder2]RELEASE
    Const DETAILPATH_ENABLED = True

    ' Level used for the detailed path
    ' This define what to include in the detailed path
    '    ex: Virtual Path is "/TV/SERIE.S03.BDRiP/SERIE.S03E01.BDRiP-GRP"
    '        DETAILPATH_LEVEL = 1 will resolve "[TV#SERIE.S03.BDRiP]SERIE.S03E01.BDRiP-GRP"
    '        DETAILPATH_LEVEL = 2 will resolve "[SERIE.S03.BDRiP]SERIE.S03E01.BDRiP-GRP"
    Const DETAILPATH_LEVEL = 2

    ' This define the seperator that should be inserted after the section
    '        DETAILPATH_SEPARATOR = "" will result in [SECTION][DETAILEDPATH]RELEASE
    '        DETAILPATH_SEPARATOR = "-" will result in [SECTION][DETAILEDPATH]-RELEASE
    '        DETAILPATH_SEPARATOR = "#" result in [SECTION][DETAILEDPATH]#RELEASE
    ' Do NOT use "/" "\" ":" or any other caracter that cannot be used in file naming
    Const DETAILPATH_SEPARATOR = ""

    'Ignore list for the DIR processing
    'Folders created/deleted and called as following will be ignored (seperator is |)
    Const DIR_IGNORELIST = "cd1|cd2|cd3|cd4|cd5|cd6|cd7|cd8|cd9|cd10|disc1|disc2|disc3|disc4|disc5|disc6|disc7|disc8|disc9|disc10|sample|sub|subs|proof"

    'Ignore list for the VFS processing
    'Folders created/deleted under theses Virtual Paths will be ignored)(seperator is |)
    Const DIR_VFS_IGNORELIST = "/REQUESTS|/HOME"

    '#------------------------------------#
    '# Output Display settings            #
    '#------------------------------------#
    'Display type
    'true  : Output result in boxed style, typically preferred by expert users.
    '        Important! To unleash this simple "eye candy", the FTPD client must
    '        support a fixed lenght of all characters. If not the output will be
    '        truncated or wrecked.
    'false : Output non boxed result to FTPD client,
    Const SCENEVIEW              = True

    'SCENE Config
    Const WIDTH              = 71

    'SCENE Config
    Const SCENEHEADER         = ".-------+----------+--------- [LatestX] --------+---------------------:"
    Const SCENESEPARATOR      = "+-------+----------+----------+-----------------+---------------------+"
    Const SCENETAIL           = ":-------+----------+----------+-----------------+---------------------:"

    'NORMAL Config
    Const NORMALHEADER        = " - LatestX -"
    Const NORMALSEPARATOR     = ""
    Const NORMALTAIL          = ""

    '#------------------------------------#
    '# Logging settings                   #
    '#------------------------------------#
    'Loglevel Eventlog 1|2|3 0 = None 1 = Success/Error 2 = Full 3 = Debug.
    '!WARNING! Level above 1 is not recommended (Use file, default is 0)
    Const EVENTLOG     = 0

    'Logs folder is <scriptpath>\Logs
    'Loglevel File 1|2|3 0 = None 1 = Success/Error 2 = Full 3 = Debug
    Const FILELOG      = 1

    'Number of logs to store in log directory 0 = Do not delete any.
    '!WARNING! this will make sure that no more than n files will remain in log directory.
    Const NUMBEROFLOGS = 5

8) Credit
    - Christer Finsen and Nils-Erik Auråker for their VBS Script Framework (FTPD Search system)
    - Team John Long for making the one of the world's most versatile FTPD on Windows,
    - And last but not least... pn169 from RaidenFTPD forum... ;)

9) ChangeLog
    v1.00: May 2011
     + Initial Release (Hopefully Bug Free)