IScriptPortDevice Interface

This interface is implemented by a script port device.

Declaration

interface IScriptPortDevice extends ${IConfigurableDevice} {
    // Properties
    readonly ${scriptPath}: string;
    readonly ${validationErrors}: string;
    ${logPath}: string;
    ${initializationValue}: string;

    // Methods
    ${setScriptFile}(path: string): boolean;
    ${setScriptText}(scriptBody: string): boolean;
    ${setScriptParam}(name: string, value: string): void;
}

public interface IScriptPortDevice : ${IConfigurableDevice}
{
    // Properties
    string ${scriptPath} { get; }
    string ${validationErrors} { get; }
    string ${logPath} { get; set; }
    string ${initializationValue} { get; set; }

    // Methods
    bool ${setScriptFile}(string path);
    bool ${setScriptText}(string scriptBody);
    void ${setScriptParam}(string name, string value);
}

struct IScriptPortDevice : IConfigurableDevice
{
    // Properties
    _bstr_t ${scriptPath};  // get 
    _bstr_t ${validationErrors};  // get 
    _bstr_t ${logPath};  // get set 
    _bstr_t ${initializationValue};  // get set 

    // Methods
    VARIANT_BOOL ${setScriptFile}(_bstr_t path);
    VARIANT_BOOL ${setScriptText}(_bstr_t scriptBody);
    HRESULT ${setScriptParam}(_bstr_t name, _bstr_t value);
};

IScriptPortDevice Properties

scriptPath

readonly scriptPath: string;

string scriptPath { get; }

_bstr_t scriptPath;  // get

A full path to a script file. This property is read-only. To change the port's script, use the setScriptFile method. If a script has been set with a call to setScriptText method, this property returns an empty string.

validationErrors

readonly validationErrors: string;

string validationErrors { get; }

_bstr_t validationErrors;  // get

This property stores the script validation error, if any. You can query this property after setScriptFile method returns false.

logPath

logPath: string;

string logPath { get; set; }

_bstr_t logPath;  // get set

A full path of a folder used to store script execution logs. By default is set to %TEMP%\vspt_script_logs.

initializationValue

initializationValue: string;

string initializationValue { get; set; }

_bstr_t initializationValue;  // get set

A script initialization parameter. Can be any string. Note that the length of this string is limited to 5,000 characters. An attempt to set longer value will result in exception.

IScriptPortDevice Methods

setScriptFile

setScriptFile(path: string): boolean;

bool setScriptFile(string path);

VARIANT_BOOL setScriptFile(_bstr_t path);

path: The full path to a script file.

Updates the virtual port's script. Library compiles and validates the script and stores its contents internally. The script port will not read the original file after this method returns successfully. This is done for security reasons: an attempt to modify the script after the port has been created will not lead to undesired updated behavior.

The read-only scriptPath property will hold the path to the original script file for reference.

The method returns true on success and false if script compilation and validation fails. In the latter case, more information is available by querying the validationErrors property. This method may also throw an exception if script file does not contain required elements.

setScriptText

setScriptText(scriptBody: string): boolean;

bool setScriptText(string scriptBody);

VARIANT_BOOL setScriptText(_bstr_t scriptBody);

scriptBody: The device script contents.

Updates the virtual port's script. Library compiles and validates the script and stores its contents internally.

The read-only scriptPath property will be set to an empty string after calling this method.

setScriptParam

setScriptParam(name: string, value: string): void;

void setScriptParam(string name, string value);

HRESULT setScriptParam(_bstr_t name, _bstr_t value);

name: Custom parameter name.
value: Custom parameter value.

This method passes a custom parameter (specified by its name and value) to a port's script. The port must be opened by some application in order for this method to succeed. If the port is not opened, an exception is thrown. Otherwise, script's IScriptDevice.setParam method is called. If this method is not defined or throws an exception, setScriptParam method also throws an exception.

It is up to the port's script to interpret the meaning of custom parameter's name and value.

There is an alternative way of setting a custom script parameter: an application that opens a virtual script port may send a custom IOCTL_SCRIPTPORT_SET_PARAM device I/O control request.

IConfigurableDevice