Previous | Index | Next

Chapter 7: How to used with 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

ExtraPuTTY's functions :

  1. Using "Connection" function to intialize the connection.
  2. Using "SendRcvData" function to send-received data.
  3. Using "WaitingMessage" function to wait one message on putty terminal.
  4. Using "WaitReConnect" function to wait automatic session ReConnect.
  5. Using "CloseConnexion" function to close the connection.
  6. Using "CloseAllConnexion" function to close all connections.
  7. Using "FtpLoader" function to transferring files.
  8. Using "lua_dofile" function to run lua script.
  9. Using "UploadFiles" function to upload file through xmodem,ymodem or FTP protocols.
  10. Using "RetrieveExistingConnection" function to to retrieve an existing connection and to keep a live a connection.
  11. Using "ForceToClose" function to force the closure of the connection.

7.2 DLL APIs descriptions and examples

7.2.1 Functions with basic parameters

7.2.1.1 "Connexion" function


Function used to establish the connection on remote device.


Syntax

int Connexion(char *TargetName,unsigned long *ConnectionId,char *Login,char *Password,bool ShowPuTTY,long Protocol,unsigned long PortNumber,
              long GenerateReport,int *CallBackRcvData,unsigned long SpecSettings);

Parameters

Parameter Description
TargetName TargetName or PuttySession Name (in this case Protocol must be equalt to 4).
ConnectionId Connection ID.
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,5:Serial Link,6:Cygterm.
PortNumber If the parameter is set to 0, the value of the default settings of putty is used. This field correspond to the speed for serial line protocol.
GenerateReport 1:extraputty report activate,0:Not activate.
CallBackRcvData Optional parameter,callback used to receive data from putty terminal, Syntax :
int CallBackRcvData(unsigned long ConnectionId,char *buf, DWORD size,DWORD ConnectionStatus)
ConnectionStatus :
  • 0 : Connection open
  • 1 : Connection close by host
SpecSettings Specific settings, bit field :
  • 2^0 : Do not wait login prompt, connection has no prompt
  • 2^1 : Dynamically starting putty log
  • 2^2 : SSH V1 otherwise SSH V2
  • 2^3 ....: Reserved

Return Values

Return Value Description
0 Indicates that the function successfully to establish the connection.
<> 0 Indicates that the function was unable to establish the connection.
1 ExtraPutty environment vairable doesn't exist.
2 Wrong value of parameter Protocol (0-6).
3 Putty.exe doesn't exist at the place defined in ExtraPutty environment variable.
4 the path set in ExtraPutty environment vairable doesn't exist.
5 putty is stop before the connection is established.
6 Connection failed with the target (host doesn't exist,timeout on connection,connection refused by the host...)
7 Timeout to send password
8 Internal error (memory allocation etc ....),impossible to perform the function.

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(unsigned long ConnectionId,char *Command,char *Title,char *Comments,int TimeCapture,char **DataRcv,long MaxSizeofData,unsigned long settings);

The old version of "SendRcvData" function is also available, named "SendRcvData_O". The difference is on "DataRcv" parameter type :

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

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
Command Data to send on the target, if the parameter is null the function is configured only in reception way.
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 contains the data received if TimerCapture is > 0.
MaxSizeofData Size of DataRcv Buffer or maximum data size in DataRcv (1 < MaxSizeofData < 20 000 000)
Settings Bit field of settings (2^0 : CRLF (0 send,1 not send),2^1 : Virtual key codes (0 no virtual key codes in command,1 yes)...reserved)
See FAQ page for a description of all virtual keys codes.

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.
1 Connection not established with the target.
2 The field 'RcvTelnetData' is NULL.
3 The field 'MaxSizeofData' is invalid (< 0 or > 20 000 000).
4 The function is used in reception but timeCapture is no set.
5 Internal error (memory allocation etc ....),impossible to perform the function.

7.2.1.3 "WaitingMessage" function


Function used to wait one message on putty terminal.


Syntax

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

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
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 Indicates that the function was unable to Send-Received data or that the timeout is reached.
1 Connection not established with the target.
2 The field "WaitMessage" is not set.
3 The field "TimeCapture" is invalid (shall be > 0).
4 Indicates that the timeout is reached without received corresponding data defined in "WaitMessage" field.
5 Internal error (memory allocation etc ....),impossible to perform the function.

7.2.1.4 "CloseConnexion" function


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


Syntax

int CloseConnexion(unsigned long ConnectionId);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).

Return Values

Return Value Description
0 Indicates that the function successfully to close the connection.
<> 0 Indicates that the function was unable to close the connection.
1 Connection not established with the target.
2 Impossible to stop putty process.
3 Internal error (memory allocation etc ....),impossible to perform the function.

7.2.1.5 "CloseAllConnexion" function


Function used to close all connections.


Syntax

int CloseAllConnexion();

Parameters

Parameter Description
None NA.

Return Values

Return Value Description
0 Indicates that the function successfully to close all connections.
<> 0 Indicates that the function was unable to close all connections.
1 Internal error (memory allocation etc ....),impossible to perform the function.

7.2.1.6 "FtpLoader" function


Function is used to transferring files with FTP protocol.


Syntax

void FtpLoader_F(char *TargetName,char *FilePath,char *DestPath,bool Showterm,char *User,char *Pass,unsigned long TransfertMode,bool verbose);

Parameters

Parameters Description
Target Hostname of target.
FilePath path of the files to upload.
DestPath destination of the files on target.
Show Display FTPLoader terminal.
Login login (size 1 - 99).
Password password (size 1 - 99).
TransfertMode transfert mode (BINARY or ASCII).
verbose explain what is being done (verbose) (param show shall be set to TRUE).

Return Values

Return Value Description
0 All files are uploaded on the target.
<> 0 Impossible to transfert the files due to a bad parameters or at least 1 files is KO
1 Bad parameter : TargetName not set.
2 Bad parameter : File path not set.
3 Bad parameter : Destination path not set.
4 Bad parameter : The FTPLoader.exe is not found.
5 Bad parameter : Path of FTPLoader.exe file not found.
6 At least one file has not been correctly transfert.
6 ExtraPuTTY environment variable is missing.

7.2.1.7 "WaitReConnect" function


Function used to wait automatic session ReConnect only when "Close window on exit" parameter of session is configured to "Never,Auto-Connect".
This function can be used after a shutdown command instead of a waiting tempo in order to improve waiting time performance.

Syntax

int WaitReConnect(unsigned long ConnectionId,long TimeOut);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
TimeOut Timeout value of wait in ms.

Return Values

Return Value Description
-1 Indicates that the target has not been reseted.
0 Indicates that the target is restarted.
<> 0 Indicates error or that the timeout is reached.
1 Connection not established with the target.
2 The field "TimeCapture" is invalid (shall be > 0).
3 Internal error (memory allocation etc ....),impossible to perform the function.
4 Indicates that the timeout is reached without before the target has been restarted.
5 Indicates that the parameter "Close window on exit" parameter of session is not configured to "Never,Auto-Connect".

7.2.1.8 "lua_dofile" function


Function used to run lua script (see Lua description to get all ExtraPuTTY lua API available).

Syntax

int lua_dofile(unsigned long ConnectionId,char *PathFile,char *Title,char *Comments);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
PathFile Path and name of lua script file.
Title Title of your command,used only if extraputty report is activate.
Comments Comments of your command,used only if extraputty report is activate.

Return Values

Return Value Description
0 No error.
<> 0 Error.
1 Connection not established with the target.
2 The field "PathFile" is invalid.
3 Internal error (memory allocation etc ....),impossible to perform the function.
4 Lua scripting error.

7.2.1.9 "UploadFiles" function


Function used to upload file through xmodem,ymodem or FTP protocols.

Syntax

int UploadFiles(unsigned long ConnectionId,int ProtocolType,char *PathFile,char *Title,char *Comments);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
ProtocolType Protocol to use for upload (0 : xmodem, 1 : xmodem-1k, 2 : ymodem).
PathFile Path and name of file to upload.
Title Title of your command,used only if extraputty report is activate.
Comments Comments of your command,used only if extraputty report is activate.

Return Values

Return Value Description
0 No error.
<> 0 Error.
1 Connection not established with the target.
2 The field "PathFile" is invalid.
3 The field "protoType" is invalid.
4 Internal error (memory allocation etc ....),impossible to perform the function.

7.2.1.10 "RetrieveExistingConnection" function


Function used to reconnect to a session already open and free AND to keep a live the connection if the DLL is unload or if the Close functions are called. The only way to close an existing session is to call the function ForceToClose.

Syntax

int RetrieveExistingConnection(unsigned char ConnectionHandle);

Parameters

Parameter Description
ConnectionHandle Handle of the connection (value : 1 to 255).
Be careful the connection handle and connection id (used with all other functions) are not the same, the connection handle is used for a global identification of a connection where as the connection id is local at the DLL.

Return Values

Return Value Description
0 Connection establish.
In this case a call of Connexion function is used to get a connection ID and to reconfigure the callback all other field are not taken into account.
1 The Handle point to a connection which is not open or not free (one client by connection).
In this case when the Connexion function is called, a new connection is made with ConnectionHandle.
< 0 Error.
-1 The field "ConnectionHandle" is invalid.

Important notes :

7.2.1.11 "ForceToClose" function


Function used to force the closure of the connection even if extraputty is configured to keep alive the connection (ie.RetrieveExistingConnection has been called).

Syntax

int ForceToClose(unsigned long ConnectionId);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).

Return Values

Return Value Description
0 Connection establish.
In this case a call of Connexion function is used to get a connection ID and to reconfigure the callback all other field are not taken into account.
1 The Handle point to a connection which is not open or not free (one client by connection).
In this case when the Connexion function is called, a new connection is made with ConnectionHandle.
< 0 Error.
-1 The field "ConnectionHandle" is invalid.

7.2.1.12 Examples of using (MFC,.NET(VB,C#),VB6,Labview)

Note

Example 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 connection on remote device.


Syntax

void Connexion_F(char *TargetName,unsigned long *ConnectionId,char *Login,char *Password,bool ShowPuTTY,long Protocol,long GenerateReport,
                long  TypeCRLF,char *NewCRLF,char *ReportFileData,unsigned long SpecSettings, 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).
ConnectionId Connection ID.
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,5:Serial Link,6:Cygterm.
PortNumber If the parameter is set to 0, the value of the default settings of putty is used. This field correspond to the speed for serial line protocol.
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.
SpecSettings Specific settings, bit field :
  • 2^0 : Do not wait login prompt, connection has no prompt
  • 2^1 : Dynamically starting putty log
  • 2^2 ....: 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.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(unsigned long ConnectionId,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
ConnectionId ConnectionId set by Connexion function (shall be > 0).
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 contains the data received if TimerCapture is > 0.
MaxSizeofData Size of DataRcv Buffer or maximum data size in DataRcv (1 < MaxSizeofData < 20 000 000)
Settings Bit fields of settings (2^0 : CRLF (0 send,1 not send),2^1 : Virtual key codes (0 no virtual key codes in command,1 yes)...reserved)
See FAQ page for a description of all virtual keys codes.
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(unsigned long ConnectionId,char *Message,char *Title,char *Comments,long TimeCapture,
                  bool &result, char reportText[1024],bool &errorOccurred, long &errorCode, char errorMsg[1024]);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
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 connection.


Syntax

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

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
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 connections.


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.2.2.6 "FtpLoader_F" function


Function is used to transferring files with FTP protocol.


Syntax

void FtpLoader_F(char *TargetName,char *FilePath,char *DestPath,bool Showterm,char *User,char *Pass,unsigned long TransfertMode,bool verbose,
                  bool &result, char reportText[1024],bool &errorOccurred, long &errorCode, char errorMsg[1024]);

Parameters

Parameters Description
Target Hostname of target.
FilePath path of the files to upload.
DestPath destination of the files on target.
Show Display FTPLoader terminal.
Login login (size 1 - 99).
Password password (size 1 - 99).
TransfertMode transfert mode (BINARY or ASCII).
verbose explain what is being done (verbose) (param show shall be set to TRUE).
arg9 State of the step (Pass or failed).
arg10 Step result report.
arg11 Error occured during step (True or false).
arg12 Error code.
arg13 Error Message.

7.2.2.7 "WaitReConnect_F" function


Function used to wait automatic session ReConnect only when "Close window on exit" parameter of session is configured to "Never,Auto-Connect".
This function can be used after a shutdown command instead of a waiting tempo in order to improve waiting time performance.

Syntax

void WaitReConnect_F(unsigned long ConnectionId,long TimeOut,
                  bool &result, char reportText[1024],bool &errorOccurred, long &errorCode, char errorMsg[1024]);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
TimeOut 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.8 "lua_dofile_F" function


Function used to run lua script (see Lua description to get all ExtraPuTTY lua API available).

Syntax

void lua_dofile_F(unsigned long ConnectionId,char *PathFile,bool &result, char reportText[1024],bool &errorOccurred, long &errorCode, 
  char errorMsg[1024]);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
PathFile Path and name of lua script file.
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.9 "RetrieveExistingConnection_F" function


Function used to reconnect to a session already open and free AND to keep a live the connection if the DLL is unload or if the Close functions are called. The only way to close an existing session is to call the function ForceToClose_F.

Syntax

int RetrieveExistingConnection_F(unsigned char ConnectionHandle,bool &result, char reportText[1024],bool &errorOccurred, 
  long &errorCode, char errorMsg[1024]);

Parameters

Parameter Description
ConnectionHandle Handle of the connection (value : 1 to 255).
Be careful the connection handle and connection id (used with all other functions) are not the same, the connection handle is used for a global identification of a connection where as the connection id is local at the DLL.
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.

Important notes :

7.2.2.10 "ForceToClose_F" function


Function used to force the closure of the connection even if extraputty is configured to keep alive the connection (ie.RetrieveExistingConnection_F has been called).

Syntax

int ForceToClose_F(unsigned long ConnectionId,bool &result, char reportText[1024],bool &errorOccurred, 
  long &errorCode, char errorMsg[1024]);

Parameters

Parameter Description
ConnectionId ConnectionId set by Connexion function (shall be > 0).
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.11 Example of using

Note

Example of using:

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.29 Compile with PuTTY release 0.64]