Previous | Index | Next

Chapter 7: How to used Telnet,SSH,Rlogin,Raw from TestStand\Win32 applications

This chapter provides a general description of all functions available with ExtraPuTTY.DLL in order to made exchange data with distant target on Telnet,SSH,Rlogin or Raw protocols.

7.1 Getting Started

Procedure

To manage exchange with distant target :

  1. Using "Connexion" function to intialize the connexion.
  2. Using "SendRcvData" function to send-received data.
  3. Using "WaitingMessage" function to wait one message on putty terminal.
  4. Using "CloseConnexion" function to close the connexion.
  5. Using "CloseAllConnexion" function to close all connexions.

7.2 DLL API description

7.2.1 Light functions with basic parameters

7.2.1.1 "Connexion" function


Function used to establish the connexion with the distant target with Telnet,SSH,Rlogin and Raw protocols.


Syntax

int Connexion(char *TargetName,char *Login,char *Password,bool ShowPuTTY,long Protocol,long GenerateReport);

Parameters

Parameter Description
TargetName TargetName or PuttySession Name (in this case Protocol must be equalt to 4).
Login optinonal parameter.
Password optinonal parameter.
ShowPuTTY TRUE: Putty Terminal is display, FALSE: not display.
Protocol 0:Telnet,1:SSH,2:Rlogin,3:Raw,4:LoadPutty Session.
GenerateReport 1:extraputty report activate,0:Not activate.

Return Values

Return Value Description
0 Indicates that the function successfully to establish the connexion.
<> 0 Indicates that the function was unable to establish the connexion.

7.2.1.2 "SendRcvData" function


Function used to send-received data with the distant target on Telnet,SSH,Rlogin and Raw protocols.


Syntax

int SendRcvData(char *TargetName,char *Command,char *Title,char *Comments,int TimeCapture,char *DataRcv,long MaxSizeofData,unsigned long settings);

Parameters

Parameter Description
TargetName The same TargetName or PuttySession Name used with connexion function.
Command Data to send to the target.
Title Title of your command,used only if extraputty report is activate.
Comments Comments of your command,used only if extraputty report is activate.
TimeCapture Time used to capture the reply data in ms.
DataRcv Buffer which contain your data if TimerCapture is > 0.
MaxSizeofData Size of DataRcv Buffer or maximum data size in DataRcv
Settings Bit fields of settings (2^0 : CRLF (0 send,1 not send),...reserved)

Return Values

Return Value Description
0 Indicates that the function successfully to Send-Received data.
<> 0 Indicates that the function was unable to Send-Received data.

7.2.1.3 "WaitingMessage" function


Function used to wait one message on putty terminal.


Syntax

int WaitingMessage(char *TargetName,char *Message,char *Title,char *Comments,long TimeCapture);

Parameters

Parameter Description
TargetName The same TargetName or PuttySession Name used with connexion function.
Message Message to wait on putty terminal.
Title Title of your command,used only if extraputty report is activate.
Comments Comments of your command,used only if extraputty report is activate.
TimeCapture Timeout value of wait in ms.

Return Values

Return Value Description
0 Indicates that the indicate message was displayed on putty terminal.
<> 0 ndicates that the timeout is reached.

7.2.1.4 "CloseConnexion" function


Function used to close the current connexion with the distant target.


Syntax

int CloseConnexion(char *TargetName);

Parameters

Parameter Description
TargetName The same TargetName or PuttySession Name used with connexion function.

Return Values

Return Value Description
0 Indicates that the function successfully to close the connexion.
<> 0 Indicates that the function was unable to close the connexion.

7.2.1.5 "CloseAllConnexion" function


Function used to close all connexions.


Syntax

int CloseAllConnexion();

Parameters

Parameter Description
None NA.

Return Values

Return Value Description
0 Indicates that the function successfully to close all connexions.
<> 0 Indicates that the function was unable to close all connexions.
Note

Sample of using:

7.2.2 Functions with full parameters (design for TestStand using)

7.2.2.1 "Connexion_F" function


Function used to establish the connexion with the distant target with Telnet,SSH,Rlogin and Raw protocols.


Syntax

void Connexion_F(char *TargetName,char *Login,char *Password,bool ShowPuTTY,long Protocol,long GenerateReport,
                long  TypeCRLF,char *NewCRLF,char *ReportFileData, bool &result, char reportText[1024],
                bool &errorOccurred, long &errorCode, char errorMsg[1024]);

Parameters

Parameter Description
TargetName TargetName or PuttySession Name (in this case Protocol must be equalt to 4).
Login optinonal parameter.
Password optinonal parameter.
ShowPuTTY TRUE: Putty Terminal is display, FALSE: not display.
Protocol 0:Telnet,1:SSH,2:Rlogin,3:Raw,4:LoadPutty Session.
GenerateReport 1:extraputty report activate,0:Not activate.
CRLF 1:0A0D,2:0DOA,3:0A,4:0D.
NewCRLF String used to replace the CRLF parameter find in data (for example CRLF = 1,NewCRLF : "br")
ReportFileData Parameter already set in step. Name and path of report generate by TestStand in order to generate extraputty report.
result Parameter already set in step. State of the step (Pass or failed).
reportText Parameter already set in step. Step result report.
errorOccurred Parameter already set in step. Error occured during step (True or false).
errorCode Parameter already set in step. Error code.
errorMsg Parameter already set in step. Error Message.

7.2.2.2 "SendRcvData_F" function


Function used to send-received data with the distant target on Telnet,SSH,Rlogin and Raw protocols.


Syntax

void SendRcvData_F(char *TargetName,char *Command,char *Title,char *Comments,long TimeCapture,char DataRcv[],long MaxSizeofData,unsigned long settings,
                  bool &result, char reportText[1024],bool &errorOccurred, long &errorCode, char errorMsg[1024]);

Parameters

Parameter Description
TargetName The same TargetName or PuttySession Name used with connexion function.
Command Data to send to the target.
Title Title of your command,used only if extraputty report is activate.
Comments Comments of your command,used only if extraputty report is activate.
TimeCapture Time used to capture the reply data in ms.
DataRcv Buffer which contain your data if TimerCapture is > 0.
MaxSizeofData Size of DataRcv Buffer or maximum data size in DataRcv
Settings Bit fields of settings (2^0 : CRLF (0 send,1 not send),...reserved)
result Parameter already set in step. State of the step (Pass or failed).
reportText Parameter already set in step. Step result report.
errorOccurred Parameter already set in step. Error occured during step (True or false).
errorCode Parameter already set in step. Error code.
errorMsg Parameter already set in step. Error Message.

7.2.2.3 "WaitingMessage_F" function


Function used to wait one message on putty terminal.


Syntax

void WaitingMessage_F(char *TargetName,char *Message,char *Title,char *Comments,long TimeCapture,
                  bool &result, char reportText[1024],bool &errorOccurred, long &errorCode, char errorMsg[1024]);

Parameters

Parameter Description
TargetName The same TargetName or PuttySession Name used with connexion function.
Message Message to wait on putty terminal.
Title Title of your command,used only if extraputty report is activate.
Comments Comments of your command,used only if extraputty report is activate.
TimeCapture Timeout value of wait in ms.
result State of the step (Pass or failed).
reportText Step result report.
errorOccurred Error occured during step (True or false).
errorCode Error code.
errorMsg Error Message.

7.2.2.4 "CloseConnexion_F" function


Function used to close the current connexion.


Syntax

void CloseConnexion_F(char *TargetName,bool &result, char reportText[1024],bool &errorOccurred, long &errorCode,
                     char errorMsg[1024]);

Parameters

Parameter Description
TargetName The same TargetName or PuttySession Name used with connexion function.
result Parameter already set in step. State of the step (Pass or failed).
reportText Parameter already set in step. Step result report.
errorOccurred Parameter already set in step. Error occured during step (True or false).
errorCode Parameter already set in step. Error code.
errorMsg Parameter already set in step. Error Message.

7.2.2.5 "CloseAllConnexion_F" function


Function used to close all connexions.


Syntax

void CloseAllConnexion_F(bool &result, char reportText[1024],bool &errorOccurred, long &errorCode,char errorMsg[1024]);

Parameters

Parameter Description
result Parameter already set in step. State of the step (Pass or failed).
reportText Parameter already set in step. Step result report.
errorOccurred Parameter already set in step. Error occured during step (True or false).
errorCode Parameter already set in step. Error code.
errorMsg Parameter already set in step. Error Message.

7.3 How to used ExtraPuTTY without ExtraPuTTY installer

The ExtraPuTTY DLL need the path of PuTTY.
In order to do that you must create the environment variable "ExtraPuTTY" with the path of ExtraPuTTY.

7.4 DLL compile options

The DLL is compiled with calling convention "__stdcall" and with struct member alignment "16 bytes"


If you want to provide feedback on this manual or on the ExtraPuTTY tools themselves, see the Feedback page.

[ExtraPuTTY release 0.24 Compile with PuTTY relesase 0.60]