Terminal Server - Simulated Client

1. Overview__________ ______ ____ _____ _______ ______ _______________ 3

How it works__________ ______ ____ _____ _______ ______ ____________ 3

Installation__________ ______ ____ _____ _______ ______ _____________ 3

2. Components__________ ______ ____ _____ _______ ______ ____________ 4

2.1. “Terminal Server Client Simulation”__________ ______ ____ ____ 4

2.2. The scripting language__________ ______ ____ _______________ 5

2.2.1 Connect__________ ______ ____ _____ _______ ______ __________ 5

2.2.2 Logoff__________ ______ ____ _____ _______ ______ ____________ 6

2.2.3 Disconnect__________ ______ ____ _____ _______ ______ ________ 6

2.2.4 Start__________ ______ ____ _____ _______ ______ _____________ 6

2.2.5 Sendoutput__________ ______ ____ _____ _______ ______ _______ 7

2.2.6 Senddata__________ ______ ____ _____ _______ ______ _________ 7

2.2.7 Sendtext__________ ______ ____ _____ _______ ______ _________ 8

2.2.8 Sleep__________ ______ ____ _____ _______ ______ ____________ 8

2.2.9 Clipboard__________ ______ ____ _____ _______ ______ ________ 9

2.2.10 Loop__________ ______ ____ _____ _______ ______ ____________ 9

2.2.11 Check__________ ______ ____ _____ _______ ______ __________ 10

2.2.12 Call__________ ______ ____ _____ _______ ______ ____________ 10

2.2.13 Job__________ ______ ____ _____ _______ ______ ____________ 11

2.2.14 Comments__________ ______ ____ _____ _______ ______ ______ 12

2.2.15 UNICODE Strings__________ ______ ____ ________________ 12

3. Validation__________ ______ ____ _____ _______ ______ _____________ 13

Example 1__________ ______ ____ _____ _______ ______ ____________ 13

Example 2__________ ______ ____ _____ _______ ______ ____________ 13

Check function__________ ______ ____ _____ _______ ______ ________ 14

4. APIs exported from protocol DLLs__________ ______ ____ ________ 15

4.1 SCConnect__________ ______ ____ _____ _______ ______ __________ 15

4.2 SCDisconnect__________ ______ ____ _____ _______ ______ ________ 16

4.3 SCLogoff__________ ______ ____ _____ _______ ______ ____________ 16

4.4 SCStart__________ ______ ____ _____ _______ ______ _____________ 16

4.5 SCSenddata__________ ______ ____ _____ _______ ______ _________ 17

4.6 SCClipboard__________ ______ ____ _____ _______ ______ _________ 17

4.7 SCInit__________ ______ ____ _____ _______ ______ ______________ 18

5. Other APIs__________ ______ ____ _____ _______ ______ _____________ 18

1. Overview

This application works in a Terminal Server system. The main purpose of it is to drive most of the kernel and session manager testing. The program would get installed in the iostress and ntstress mix and would simulate multiple clients exercising a Terminal Server.

How it works

“Terminal Server Client Simulation” application runs as a stand-alone command-line application. The simulation would create a connection with Terminal Server and issue appropriate commands to load/unload remote sessions, run iostress, ntstress or “SpyHydra” application to simulate keyboard/mouse events. (For more information about “SpyHydra” application, see the “SpyHydra” documentation.)

A scripting language controls the Simulated Client. For more information about scripting language see 2.2.

Installation

The Terminal Server Client Simulation facility relies on the version 5.0 Terminal Server Client applications.  To use smclient, you must first install the Terminal Server Client, then copy the smclient files to the same directory with the client.

2. Components

2.1. “Terminal Server Client Simulation”

The Client Simulation runs as a stand-alone application on a regular Win32 box. It creates several threads that run the jobs specified in the script file. This application can be used either in stress mix (ntstress, iostress) or in specific regression tests.

The outputs of the Client Simulation application are sent to the Terminal Server through a protocol specific DLL, ensuring thus an isolation between Client Simulation and protocol.

The following switches are valid for the Client Simulation application:

-f:FileName – specifies the name of the script file that contains the jobs description

-s:ServerName – specifies the exercised server name. If this switch is present then all connections are made with this server. If you omit this switch the application will use servers listed in server.ini file. The server name can be a UNICODE string (see UNICODE strings).

-t:nn – specifies the number of threads created by the application (default value is 1)

-l:nn – specifies the number of loops the script is executed; if “nn” is 0 then jobs are run forever

-p:ProtocolName – specifies the protocol used by this client to connect with Terminal Server (TSHARE or RS232)

-c – the application is used only for verifying the script file

-v – specifies the verbose mode; in this mode the Client Simulation will display lots of information about the current status of the application

-d – specifies that the application has to be run in debug mode, dumping extra information to debugger

Here is a short example of the smclient.ini file:

[servers]

;this section tells the server names used by smclient application

server1=YOURSERVER1

server2=YOURSERVER2

[dlls]

;this section specifies the protocol DLL names and also the check DLL name (see 3.)

;these DLL names are used by SmClient when it wants to load the proper protocol DLL

;according with the -p switch

tshare=tclient.dll

;rs232=sclrs232.dll

check=tclient.dll

[loaddlls]

;this section specifies the DLLs which will be loaded by smclient at the beginning of a script run

;if the DLL is not found smclient continues

dll1=mydll1.dll

dll2=mydll2.dll

Note: all servers name can be UNICODE strings (see UNICODE strings).

2.2. The scripting language

The following identifiers are reserved for use as Client Simulation keywords, and may not be used otherwise:

check

connect

disconnect

job

logoff

loop

senddata

sendoutput

sendtext

sleep

start

call

2.2.1 Connect

A connection between a user and a Terminal Server is done through a connect statement.

connect (<user_name>, <password>, <domain>, <xResolution>, <yResolution>);

where:

“user_name” is the user’s name attempting to connect to the Terminal Server

“password” is the user’s password

“domain” is the user’s domain

“xResolution” * “yResolution” specifies the connection resolution (example: 640 * 480)

Example:

connect (“user1”, “nopass”, “redmond”, 640, 480);

The server to connect to is picked by the application from the server.ini file or from –s switch (if specified).

A connection is closed either by a logoff or by a disconnect command. All connect commands that appear between a connect command and a logoff/disconnect command are ignored.

Example:

connect (“user1”, “user1”, “redmond”, 640, 480);

connect (“user2”, “user2” , “redmond”, 1024, 768);            this command is ignored

logoff

If the domain string is the NULL string (for example: “”) then the server to connect to is used as a domain name.

Example:

If the connect to server is “server”, then the following command:

connect (“user1”, “user1”, “”, 640, 480);

is equivalent with:

connect (“user1”, “user1”, “server”, 640, 480);

Note: User name, password and domain strings can be UNICODE strings (see UNICODE strings).

2.2.2 Logoff

To log off a user from a Terminal Server use the logoff statement. The user is logged off from the last opened connection.

logoff

Example:

logoff

If there is no opened connection, all logoff commands are ignored.

Example:

connect (“user1”, “user1” , “redmond”, 640, 480);

logoff

logoff this command is ignored

2.2.3 Disconnect

To disconnect a user from a Terminal Server use the disconnect statement. The user is disconnected from the last opened connection.

disconnect

Example:

disconnect

If there is no opened connection, all disconnect commands are ignored.

Example:

connect (“user1”, “user1” , “redmond” , 640, 480);

disconnect

disconnect this command is ignored

logoff this command is ignored

connect (“user1”, “user1” , “redmond” , 640, 480);

logoff

disconnect this command is ignored

logoff this command is ignored

2.2.4 Start

To launch an application in the last opened connection, use the start statement.

start (<application_command_line>);

where:

“application_command_line” is the application command line

Example:

start (“hydrasrvstressstress”);

If there is no opened connection, all start commands are ignored.

connect (“user1”, “user1” , “redmond” , 640, 480);

start (“stress”);                       this command is executed

disconnect

start (“spyhydra”);     this command is ignored

Note: The application command line string can be a UNICODE string (see UNICODE strings).

2.2.5 Sendoutput

To send events (keyboard/mouse events) to the Terminal Server, use sendoutput statement. Events are sent through the last opened connection.

sendoutput (<events_file>, <milliseconds>);

where:

“events_file” is the file that contains the keyboard/mouse events to send to the Terminal Server. For a description of this file see the scripting file format in SpyHydra documentation.

“milliseconds” specifies the time, in milliseconds, for which to suspend execution after each command sent from the “events_file” file.

Example:

sendoutput (“data.dat”, 250);

If there is no opened connection, all sendoutput commands are ignored.

connect (“user1”, “user1” , “redmond” , 640, 480);

sendoutput (“data.dat”, 500);                       this command is executed

logoff

sendoutput (“data.dat”, 1000);                     this command is ignored

2.2.6 Senddata

To send a specific event (keyboard or mouse) to the Terminal Server, use senddata statement. The specified event is sent through the last opened connection.

senddata (<message_name>, <wparam>, <lparam>);

where:

“message_name” is the message name to be sent to the Terminal Server. The only supported messages are the mouse and keyboard messages. For a complete reference of the messages supported by this application see SpyHydra documentation.

“wparam” depends on the “message_name” message

“lparam” depends on the “message_name” message

Example:

senddata (“WM_MOUSEMOVE”, 12345678, -2186758);

If there is no opened connection, all senddata commands are ignored.

connect (“user1”, “user1” , “redmond” , 640, 480);

senddata (“WM_KEYDOWN”, 50, 196609);   this command is executed

logoff

senddata (“WM_CHAR”, 51, 262145);                      this command is ignored

2.2.7 Sendtext

To send a string (no special characters) to the Terminal Server, use sendtext statement. The specified string is sent through the last opened connection.

sendtext (<string>, <milliseconds>);

where:

“string” is the string to be sent to the Terminal Server.

“milliseconds” specifies the time, in milliseconds, for which to suspend execution after each character sent from the “string”.

Example:

sendtext (“send this string to the server”, 500);

If there is no opened connection, all sendtext commands are ignored.

connect (“user1”, “user1” , “redmond” , 640, 480);

sendtext (“string”, 250);        this command is executed

logoff

sendtext (“string”, 500);                    this command is ignored

Note: The string to be sent can be a UNICODE string (see UNICODE strings).

2.2.8 Sleep

To suspend the execution of the current job for a specified interval use the sleep keyword.

sleep (<milliseconds>);

where:

“milliseconds” specifies the time, in milliseconds, for which to suspend execution.

Example:

sleep (1000);

Sleep commands are executed whether they are inside or outside of an open connection.

sleep (1000);               this command is executed

connect (“user1”, “user1” , “redmond” , 640, 480);

sleep (1000);               this command is executed

logoff

sleep (1000);               this command is executed

2.2.9 Clipboard

To put/get something into/from the clipboard use the clipboard keyword.

clipboard (<operation>, <file_name>);

where:

“operation” specifies the clipboard operation: copy/paste.

“file_name” is the file that contains what to put/get into/from the clipboard.

Example:

clipboard (copy, “clipboard.dat”);

or

clipboard (paste, “clipboard.dat”);

If there is no opened connection, all clipboard commands are ignored.

connect (“user1”, “user1” , “redmond” , 640, 480);

clipboard (copy, “file.dat”);   this command is executed

logoff

clipboard (paste, “file.dat”);              this command is ignored

2.2.10 Loop

In a loop statement, the statement list is executed until the value of the counter becomes zero. If the initial value of the counter is zero, then the loop is executed forever.

loop (<counter>)

where:

“counter” specifies how many times the loop is run;

<statement_list>:

<statement> |

<statement_list> <statement>

Example:

loop (10)

2.2.11 Check

In order to verify that something worked OK on the Terminal Server use the check statement.

check (<check_function>, <function_params>);

where:

“check_function” is a null-terminated string that contains the check function name. This function should be exported from the Check.dll library.

“function_params” is a null-terminated string that contains the check parameters. Is Check function responsibility to parse this string.

Example:

check (“CheckStart”, “param1 param2”);

If there is no opened connection, all check commands are ignored.

connect (“user1”, “user1” , “redmond” , 640, 480);

check (“Check”, “param1 param2”);             this command is executed

logoff

check (“Check”, “param1 param2”);             this command is ignored

The “Check” function is exported from a test specific DLL (the name of this DLL being specified through the smclient.ini file) and its purpose is to validate the results of a test. For more information see next section Validation.

Note: The function parameters string can be a UNICODE string (see UNICODE strings).

2.2.12 Call

Call statement is used to call a function from a DLL not specified in smclient.ini.

call (<DLL_library>, <function_name>, <function_params>);

where:

“DLL_library” is a null-terminated string that contains the DLL name.

“function_name” is a null-terminated string that contains the function name. This function should be exported from the “DLL_library” library.

“function_params” is a null-terminated string that contains the function parameters. Is function responsibility to parse this string.

Example:

call (“c:tempmydll.dll”, “MyFunction”, “param1 param2”);

Call commands are run either there is an opened connection or not.

connect (“user1”, “user1” , “redmond” , 640, 480);

call (“mydll.dll”, “fun”, “param1 param2”);              this command is executed

logoff

call (“mydll.dll”, “fun”, “param1 param2”);              this command is executed

The “Fun” function is exported from “mydll.dll” DLL. For more information see section Other APIs.

2.2.13 Job

Job is like an anonymous function. It contains one or more statements that are executed in sequence. The job keyword is not a statement therefore it cannot be used in a loop or another job.

job

where:

<statement_list>:

<statement> |

<statement_list> <statement>

Example:

job

job

2.2.14 Comments

The characters // start a comment, which terminates at the end of the line on which they occur. The comment characters // have no special meaning within a // comment and are treated just like other characters.

Example:

//this is a comment

2.2.15 UNICODE Strings

A string beginning with “u” followed by the memory dump of a UNICODE string is interpreted as a UNICODE string.  For example, the string “text” has this UNICODE representation: 7400650078007400 and therefore this smclient-UNICODE representation: u7400650078007400. The chgform tool from the smclient directory creates the appropriate UNICODE representation from an ASCII string.

3. Validation

The main purpose of the Client Simulation application is to be run in a stress mix. But taking into account that a script language drives this application, various jobs can be built to help creating regression tests.

Example 1

job

logoff ();

This job opens a connection with a Terminal Server, starts the “SpyHydra” application in Spy mode and after that sends keyboard/mouse events to the Terminal Server. Because “SpyHydra” is started in Spy mode, it verifies that all inputs are received in the right order and none of these inputs are lost, and also it creates a log file on the Terminal Server. This scenario can be used to verify that the client-server connection works OK. Of course this is true if and only if the Client Simulation will use the same code to connect with a Terminal Server as the real Client (Ducati in the T.Share case). BUGBUG: Is this true?

Example 2

This example checks that disconnect works OK:

job

This job opens a connection with a Terminal Server, starts three applications, and disconnects from the server. When you reconnect to the server you should find running all three applications (of course if you started applications that runs forever!). The CheckRun function purpose is to verify this and to create the appropriate log file. This function is dependent on the regression test. To isolate the Client Simulation from a specific test, the CheckRun function has to be in a separate DLL (check.dll for example). The Client Simulation loads this DLL if the check command appears in a job.

Check function

The prototype of the check function exported from the check.dll is:

LPCSTR SCCheck (

void *pConnectData,

LPCSTR lpszFunctionName,

LPCWSTR lpszFunctionParameters)

Parameters

pConnectData – pointer to a connect specific data. The data has been filled by SCConnect function (see APIs exported from protocol DLLs)

lpszFunctionName – points to a null-terminated string containing a check function name. It is the CHECK.DLL duty to call this function and to pass the lpszFunctionParameters to it.

lpszFunctionParameters – points to a null-terminated string containing the function parameters.

Return Value

The return value is a pointer to an error message string if fails and NULL otherwise.

4. APIs exported from protocol DLLs

The protocol DLLs have to export the following functions (APIs):

SCConnect

SCDisconnect

SCLogoff

SCStart

SCSenddata

SCClipboard

The following function is optional:

SCInit

4.1 SCConnect

The SCConnect function tries to establish a connection with a Terminal Server.

LPCSTR SCConnect (

LPCWSTR lpszServerName,

LPCWSTR lpszUserName,

LPCWSTR lpszPassword,

LPCWSTR lpszDomain,

const int xResolution,

const int yResolution,

void **ppConnectData)

Parameters

lpszServerName – points to a null-terminated string containing the Terminal Server name.

lpszServerName – points to a null terminated string containing the user’s name.

lpszPassword – points to a null-terminated string containing the user’s password.

lpszDomain – points to a null-terminated string containing the user’s domain

xResolution – horizontal resolution of the connection

yResolution – vertical resolution of the connection

ppConnectData – address of a pointer to a specific connection data. This parameter is filled by the SCConnect function and should be different of NULL in case SCConnect function succeeds.

Return Value

The return value is a pointer to an error message string if fails and NULL otherwise.

Remarks

The lpszServerName server name can hold either a normal server name as “hydrasrv” or a more complex string that specifies for example a serial port name as “COM1”. It’s up to the protocol DLL to interpret this string and extract the proper information.

The pConnectData pointer has to be a valid pointer till either SCDisconnect or SCLogoff function is called.

4.2 SCDisconnect

The SCDisconnect function disconnects a user from a Terminal Server.

LPCSTR SCDisconnect (void *pConnectData)

Parameters

pConnectData – pointer to a connect specific data. The data has been filled by SCConnect function.

Return Value

The return value is a pointer to an error message string if fails and NULL otherwise.

Remarks

The SCDisconnect function has to free the memory pointed by pConnectData parameter.

4.3 SCLogoff

The SCLogoff function logs off a user from a Terminal Server.

LPCSTR SCLogoff (void *pConnectData)

Parameters

pConnectData – pointer to a connect specific data. The data has been filled by SCConnect function.

Return Value

The return value is a pointer to an error message string if fails and NULL otherwise.

Remarks

The SCLogoff function has to free the memory pointed by pConnectData parameter.

4.4 SCStart

The SCStart function launches an application in the given connection.

LPCSTR SCStart (void *pConnectData, LPCWSTR lpszApplicationName)

Parameters

pConnectData – pointer to a connect specific data. The data has been filled by SCConnect function.

LpszApplicationName – points to a null-terminated string containing the application command line

Return Value

The return value is a pointer to an error message string if fails and NULL otherwise.

4.5 SCSenddata

The SCSenddata function sends a specific event (keyboard or mouse) to the Terminal Server through the given connection.

LPCSTR SCSenddata (

void *pConnectData,

const UINT uiMessage,

const WPARAM wParam,

const LPARAM lParam)

Parameters

pConnectData – pointer to a connect specific data. The data has been filled by SCConnect function.

uiMessage – the message ID to be sent to the Terminal Server

wParam – specifies additional information about the message. The exact meaning depends on the value of the uiMessage parameter.

lParam – specifies additional information about the message. The exact meaning depends on the value of the uiMessage parameter.

Return Value

The return value is a pointer to an error message string if fails and NULL otherwise.

4.6 SCClipboard

The SCClipboard function puts/gets data into/from a Terminal Server session clipboard through the given connection.

LPCSTR SCClipboard (

void *pConnectData,

const CLIPBOARDOPS eClipOp,

LPCSTR lpszFileName)

Parameters

pConnectData – pointer to a connect specific data. The data has been filled by SCConnect function.

eClipOp – specifies the clipboard desired operation: copy or paste

lpszFileName – specifies the file that contains the information to put or get into/from the clipboard. In the “paste” case the information can be used for checking purposes.

Return Value

The return value is a pointer to an error message string if fails and NULL otherwise.

4.7 SCInit

The SCInit function is called by SmClient application when the protocol DLL is loaded. This function is optional. If SmClient doesn’t find it in the protocol DLL it will report no error.

void SCInit (SCINITDATA *pInitData)

Parameters

pInitData – pointer to a specific initialization data.

5. Other APIs

This section contains the prototype description for the exported functions used by call commands.

LPCSTR SCCall (

void *pConnectData,

LPCSTR lpszFunctionParameters)

Parameters

pConnectData – pointer to a connect specific data. The data has been filled by SCConnect function (see APIs exported from protocol DLLs). Note: this pointer can be NULL if call statement appears before a SCConnect or after SCLogoff/SCDisconnect.

lpszFunctionParameters – points to a null-terminated string containing the function parameters.

Return Value

The return value is a pointer to a message string smclient will print after SCCall returns..

Feedback

For questions or feedback concerning this tool, please contact rkinput@microsoft.com.

© 1985-2000 Microsoft Corporation. All rights reserved.

This product includes software developed by the University of California, Berkeley and its contributors.