# $language = "Python"
# $interface = "1.0"

# UseDescriptionFieldAsScriptArguments.py
#   Last Modified:
#     21 Feb, 2023:
#       - Bring example into conformity with VBScript edition
#
#     17 Sep, 2019:
#       - Initial conversion from VBScript edition
#
# Description:
#   Designed for use with SecureCRT 6.5 or later.
#
#   This script serves as an example of how to use the "Description" field of
#   the Session Options as arguments that can be read in from a logon script.
#   Since SecureCRT provides a unique field for "notes" and other generic
#   information, one can decide a way to use this mechanism to store arguments
#   that can be "passed" to a common (logon) script that is shared among
#   multiple sessions.  The behavior of the script can then be controlled based
#   on the value(s) stored in the "Description" field as described below.
#
# WARNING:
#   The "Description" field within a saved session's configuration is not
#   stored with any encryption or obfuscation of any kind. For example:
#      Z:"Description"=00000003
#       This is my description!
#       ARG: plain-text-value1
#       ARG: plain-text-value2
#   Alghough you could specify username or password information using the
#   method demonstrated in this script, it is not considered a security best
#   practice to save passwords with any mechanism.
#
# Usage:
#   - Specify arguments to your script as entries within the Description field
#     in the Connection category within the Session Options dialog.  Although
#     this could be done in many different ways, for this example, the choice
#     was to have one argument per line.  This makes parsing arguments that
#     may or may not contain spaces more trivial.
#
#   - This script loads information from the "Description" field in session
#     options by making use of the Session.Config script object's GetOption()
#     method.  In the case of the "Description" option, an array of strings is
#     returned, and we simply iterate over that array looking for lines that
#     begin with "ARG:" and we treat everything to the right of that tag on a
#     single line as the value for that positional argument.  Here's an example
#     of a Description field that has both a description (ignored) as well as
#     arguments that can be used by a logon script with this code:
#
#        This is located in Marge's office on the 3rd floor of the Annex.
#        ARG: script_info_1
#        ARG: script_info_2
#

global g_vArgs
g_vArgs = []

global g_nArgCount
g_nArgCount = 0

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
def GetArgs():
    # Function returns an array of all the arguments parsed from the session's
    # Description field. The caller will check the size of the array returned
    # for evidence of success/fail.

    vDescriptionLines = crt.Session.Config.GetOption("Description")
    
    # Start with an empty array representing the arguments found
    vArgsFound = []
    
    # Read each line of the Description text one by one, looking for any
    # lines which reflect the tag "ARG:". For any args found, append them
    # to the array we're building up.
    for strLine in vDescriptionLines:
        strLine = strLine.strip()

        # Ignore empty lines and lines that don't start
        # with "ARG:" within the Description field
        if strLine[0:4] == "ARG:":
            strArg = strLine[5:].strip()
            vArgsFound.append(strArg)
            
    return vArgsFound

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
def MsgBox(strText):
    # Just a wrapper around simple MsgBox uses so that we get tible bars and
    # ability to display more than 1024 characters "for free".
    crt.Dialog.MessageBox(strText)


#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
def Main():
    global g_vArgs
    global g_nArgCount

    # This script will only work with SecureCRT version 6.5 or later.
    vVersionElements = crt.Version.split(".")
    if int(vVersionElements[0]) < 6:
        bVersionValid = False
    elif int(vVersionElements[0]) == 6 and int(vVersionElements[1]) < 5:
        bVersionValid = False
    else:
        bVersionValid = True
    
    if not bVersionValid:
        MsgBox("This script works with SecureCRT 6.5 or later.\r\n" +
               "The version you are running is {0}".format(crt.Version))
        return

    objConfig = crt.Session.Config

    # Populate the Arguments array and counter variable.
    g_vArgs = GetArgs()
    g_nArgCount = len(g_vArgs)
    if g_nArgCount < 1:
        MsgBox("No arguments found in this session's Description field:\r\n" +
            "=" * 36 + '\r\n' +
            "Session Name: " + crt.Session.Path + '\r\n' +
            "=" * 36 + '\r\n' +
            "Description: " + '\r\n' +
            "=" * 36 + '\r\n' +
            "\r\n".join(objConfig.GetOption("Description")))
        return

    # Use the arguments we discovered;
    # simple example: display them in a dialog box.
    strArgsText = (
        "Found {} argument(s) in the Description field for this session:\r\n" +
        "=" * 36 + '\r\n' +
        "\r\n".join(g_vArgs)).format(g_nArgCount)

    MsgBox(strArgsText)
    
    # strArg1 = g_vArgs[0]
    # strArg2 = g_vArgs[1]
    # ...and so on


# Launch our main subroutine
Main()