# [Note] SecureCRT python script learning note

###### tags: `note`, `SecureCRT`, `Python`, `script`
[toc]

## Wait API of Screen object
In SecureCRT, there are 3 types of events we can wait for in Screen object. They are a cursor, a key and a string (strings). And timers could combine with these events.

- WaitForCursor
- WaitForKey
- WaitForString
- WaitForStrings

### WaitForCursor(t)
This API is usually used with while loop together.
If t is not gave, this API will never return False.

1. Wait until the cursor is still for t(!=0) seconds.
It can be used to wait for TFTP transmission completing.

import time

initTab = crt.GetScriptTab()
initScreen = initTab.Screen
Flag = True
    while Flag:
        tStart = time.time()
	    if initScreen.WaitForCursor(1) == False:
                tEnd = time.time()
                Flag = False
    crt.Dialog.MessageBox('It cost %f sec to wait' % (tEnd - tStart))

2. Launch a periodic task every t(!=0) seconds.
It can be used to do a set of commands periodically. The period is not always t seconds because it is the time when detecting cursor keeps still. For example, if the cursor keeps moving for 10 seconds, the period time is going to be 10 + t seconds.

listCMD = ['uname', 'pwd', 'ls']
initTab = crt.GetScriptTab()
initScreen = initTab.Screen
    while True:
	    if initScreen.WaitForCursor(5) == False:
                for idx, cmd in enumerate(listCMD):
                    initScreen.Send(cmd + '\r')

### WaitForKey(t)
It is similar to WaitForCursor. This API is usually used with while loop together, too. It cannot identify what key is pressed.
If t is not gave, this API will never return False.

1. Wait until no key is pressed for t(!=0) seconds.
It can be used to wait for TFTP transmission completing, too.

import time

initTab = crt.GetScriptTab()
initScreen = initTab.Screen
Flag = True
    while Flag:
        tStart = time.time()
	    if initScreen.WaitForKey(1) == False:
                tEnd = time.time()
                Flag = False
    crt.Dialog.MessageBox('It cost %f sec to wait' % (tEnd - tStart))

2. Launch a periodic task every t(!=0) seconds.
It can be used to do a set of commands periodically, too. The period is not always t seconds because it is the time when no keyboard events detected. For example, if we keeps press keyboard for 10 seconds, the period time is going to be 10 + t seconds.
And I think it is better and more accurate than WaitForCursor to do this work.

listCMD = ['uname', 'pwd', 'ls']
initTab = crt.GetScriptTab()
initScreen = initTab.Screen
    while True:
	    if initScreen.WaitForKey(5) == False:
                for idx, cmd in enumerate(listCMD):
                    initScreen.Send(cmd + '\r')\

### WaitForString(pattren, t)
It is used to wait for a particular string pattern.
If the timeout value t is not gave, the script will halt until that string appears.
If the timeout value t is gave, the script will halt until the pattern appears or timer expires.

initTab = crt.GetScriptTab()
initScreen = initTab.Screen
    ret = initScreen.WaitForString('Linux', 5)
    if ret == True:
        crt.Dialog.MessageBox('String matched')
    else:
        crt.Dialog.MessageBox('Timeout')

### WaitForStrings(pattren_list, t)
It is used to wait for a list of particular string patterns.
If the timeout value t is not gave, the script will halt until a pattern in the pattern_list appears.
If the timeout value t is gave, the script will halt until the pattern in the pattern_list appears or timer expires.

initTab = crt.GetScriptTab()
initScreen = initTab.Screen
ret = initScreen.WaitForStrings(['pattern 1', 'pattern 2', 'pattern 3'], 5)
if ret == 3:   #pattern 3 matched
    crt.Dialog.MessageBox('pattern 3 matched')
elif ret == 2: #pattern 2 matched
    crt.Dialog.MessageBox('pattern 2 matched')
elif ret == 1: #pattern 1 matched
    crt.Dialog.MessageBox('pattern 1 matched')
elif ret == 0: # timeout
    crt.Dialog.MessageBox('timeout')

## Summary
In these 3 types of events, it will return **FALSE** if it is timeout.
For example,
1. For WaitForCursor, it returns **TRUE** if a cursor is moving.
2. For WaitForKey, it returns **TRUE** if anykey is pressed.
3. For WaitForString, it returns **TRUE** if a string pattern appears.

## Appendix
Below tables are extracted from [official website](https://documentation.help/SecureCRT/Screen_Object.htm#Screen_Object_Methods_WaitForCursor).

> | | WaitForCursor |
> | ----------- | ---------------- |
> | Syntax | [ result = ] object.WaitForCursor([timeout]) |
> | Description | Wait for the cursor to change position.|
> | Remarks | The optional timeout parameter specifies the number of seconds to wait for the change. </br> **- If a change of cursor position is detected WaitForCursor() returns True**. </br> **- If a timeout occurs the function returns False.** </br> - If no timeout is specified then WaitForCursor() will not time out. An error will be returned if there is no connection open.|
>
>| | WaitForKey |
>| -------- | ---------------- |
>| Syntax | [ result = ] object.WaitForKey([timeout]) |
>| Description | Wait for a keypress event. |
>| Remarks | The optional timeout parameter specifies the number of seconds to wait for a key event. </br> **- If key event is detected WaitForKey() returns True.** </br> **- If a timeout occurs the function returns False.** </br> - If no timeout is specified then WaitForKey() will not time out. An error will be returned if there is no connection open. |
>
>| | WaitForString |
>| -------- | ---------------- |
>| Syntax | [ result = ] object.WaitForString(string [, timeout] [, bCaseInsensitive]) |
>| Description | Wait for a string. |
>| Remarks | Wait for the string to appear in the input. The timeout (seconds) parameter is optional. </br> **- When the string is detected in the input WaitForString() returns True.** </br> **- If a timeout occurs the function returns False.** An error will be returned if there is no connection open. |
>| Note | This method takes an optional bCaseInsensitive parameter that defaults to false (case-sensitive wait string matching). It also takes an optional lWaitTimeout parameter, which defaults to "0" if not specified. To specify the bCaseInsensitive parameter, you must also explicitly specify the lWaitTimeout parameter when using this function in a script.|
>
>| | WaitForStrings |
>| -------- | ---------------- |
>| Syntax | [ varname = ] object.WaitForStrings(StringsArray [, timeout] [, bcaseInsensitive]) |
>| Description | Wait for one of several strings to appear in the input. |
>| Remarks | Waits for one of the strings given as arguments to appear in the input. When one of the argument strings is matched in the input, WaitForStrings() returns the argument index of the string that was found (the index of the first string given as an argument to WaitForStrings() is 1). If the optional timeout parameter is specified and a timeout occurs before any of the strings are found, WaitForStrings() returns 0. In the absence of a timeout parameter WaitForStrings() will block without timing out and will not return 0. An error will be returned if there is no connection open. |
>| Notes |If you are using VBScript, WaitForStrings() will accept an array of strings as its first argument followed by an optional timeout. The value returned by WaitForStrings() will be the index of the string found in the array (1st element in the array = 1). A value of 0 will be returned if no strings were found within the timeout period if specified.</br></br>The WaitForString(s) interface works with MBCS languages, and depends only on the "Character Encoding" for the session being able to represent the characters being waited for, not on the characters being displayed correctly on the screen. </br></br> This method takes an optional bCaseInsensitive parameter that defaults to false (case-sensitive wait string matching). It also takes an optional lWaitTimeout parameter, which defaults to "0" if not specified. To specify the bCaseInsensitive parameter, you must also explicitly specify the lWaitTimeout parameter when using this function in a script.|

## Reference
https://forums.vandyke.com/showthread.php?t=10365
https://www.vandyke.com/support/securecrt/python_examples.html
https://documentation.help/SecureCRT/Screen_Object.htm
https://www.cnblogs.com/OnOwnRoad/p/4899660.html
https://github.com/zccing/Ops-notes/blob/master/script/CRT-script-manual.md