Electronic Team, Inc

• Proto tag
• Connection tag
  • Port section
  • Protocol tag
  • Network tag
  • Security tag
  • Proxy tag
  • Ctrlsconn and ctrldisconn tags
• GETLIST command
• LIST response
• ADD command
• UPDATE command
• GETSTAT command
• STAT response
• DELETE command
• GETMIRRORLIST command (Deprecated)

The SDK license owners can build certain commands to be sent to the Serial to Ethernet Connector Service, which actually manages the work with the drivers. Sending commands to the Service is executed via PIPE:

\\.\pipe\SEC_PIPE6

Note: The previous format of Service management (\\.\pipe\SEC_PIPE) is still supported for the owners of older SDK builds.

SEC_PIPE6 is a channel with a specific name that passes information from one computer process to another. Named pipes can be read from and written to just as if they were ordinary files.

All changes applied (add, remove, modify connections, etc.) are automatically synchronized by the Service with the corresponding registry changes.

Packets

For the Service management via SEC_PIPE6 string XML blocks are used. Each packet has the following structure:

<proto version="6.0">

<operation type="command_name" />

…..................

…..................

</operation>

</proto>

Some tags are used for certain connection types only, otherwise, the Service will ignore them.

proto tag

proto tag - <proto> and </proto> tags indicate the packet's beginning and ending correspondingly. Includes operation tag (one or several) and has the following attributes:

version - the protocol version; 6.0 by default.

operation tag indicates the command to be executed by the Service. Contains obligatory type attribute which indicates the command name.

Here is the list of available commands and their return values:

If the error occurs, all commands return ERROR.

ADD and UPDATE commands should contain the connection inner tag which, in its turn, includes the connection description:

• type - describes connection type. The possible values are: CLIENT, SERVER, UDP
• name - describes connection name, e.g.: <name>Client_COM1</name>
• port - describes COM port settings
• protocol - describes data transmission protocol settings
• network - describes networking settings
• security - describes security settings
• proxy - describes proxy server settings
• ctrlsconn - describes signal lines states when the connection is established
• ctrldisconn - describes signal lines states when the connection is not established
• status - describes connection status (available when the status attribute is set to 1 in GETLIST)

Example:

Sending GETLIST command to the Service:

<proto version="6.0">

    <operation type="GETLIST" />

</proto>

The command returns the following:

<proto version="6.0">

 <operation type="LIST">

<connection>

<type>CLIENT</type>

<name>Client_COM1</name>

<port>

<name>COM1</name>

<buffer enable="1" max="131072" />

<sendmode mode="0" param="0" />

<type>Virtual</type>

</port>

<protocol>

<type>RAW</type>

<access write="2" read="2" />

<reconnect timeout="5000" />

<portopencondition enable="0" />

</protocol>

<network>

<host name="localhost" port="5002" />

<host name="***.***.0.51" port="5002" />

<host name="***.***.0.16" port="5003" />

<keepalive timeout="7000" noreply="1000" units="msec" enable="0" />

<break timeout="10000" enable="0" />

<incomeport port="5001" />

</network>

<security />

<ctrlsconn dtr="1" rts="1" dcd="1" />

<ctrldisconn dtr="1" rts="1" dcd="1" />

</connection>

<connection>

<type>UDP</type>

<name>Udp client_COM2</name>

<port>

<name>COM2</name>

<buffer enable="1" max="131072" />

<sendmode mode="0" param="0" />

<type>Virtual</type>

</port>

<protocol>

<type>RAW</type>

<access write="2" read="2" />

</protocol>

<network>

<host name="localhost" port="5005" />

</network>

<security />

<ctrlsconn dtr="0" rts="0" dcd="0" />

</connection>

</operation>

</proto>

Connection tag 

port section

COM port settings. Includes the following options:

name - COM port name

buffer - controls buffering of data written to the COM port when no connection is established. May have two attributes:

enable - turns buffering on (1) or off (0) 

max - sets the maximum buffer size, in bytes 

sendmode - data transfer parameters. May have two attributes: 

mode - numerical value, the type of packet transfer mode 

param - additional obligatory parameter The list of possible modes and their values:

type - COM port type: virtual or real

stricted - indicates whether a strict baud rate is enabled

Possesses enable attribute which can be either 1 or 0 correspondingly. E.g.: - a strict baud rate is enabled

settings - describes or sets COM port parameters in the following format: 

baudrate,databits,parity,stopbits,flowcontrol

E.g.: 9600,8,N,1,P

protocol tag

May contain the following tags:

type - indicates protocol type; can be either RAW or TELNET. E.g.:

<type>RAW</type>

access - used in a RAW protocol. Applicable to both server and client; restricts data transmission over the network. Possesses two numerical values: write and read.

E.g.: <access write="0" read="1">

paired - available only for telnet protocol; indicates "Notify remote host on local port settings change" option state.

enable attribute may have one of the following values:

1=enabled

0 = disabled

telnet - sets response rules when control lines for telnet RFC protocol change.

dtr, rts, and dcd attributes indicate whether control line change is allowed or not by taking a 1 or 0 value correspondingly.

dcd is ignored if a real serial port is used. dtr and rts attributes manage DTR and RTS signal lines.

If the virtual port is used, dtr, rts, and dcd parameters manage DSR, CTS, and DCD signal lines correspondingly.

e.g.: <telnet dtr="0" rts="0" dcd="0"> - changes are not allowed

reconnect - sets "On error retry to establish a connection every" option parameters.

timeout numeric attribute sets reconnection interval in milliseconds.

enable numeric attribute may have one of the following values:

1=enabled

0 = disabled

portopencondition - this option value depends on the connection type as well as on the port type used in the connection. The possible values are the following:

enable attribute is used to enable or disable the portopencondition option with 1 or 0 values respectively.

dynamic - controls Allow changing local port settings option (for real ports only).

Enable attribute is used to enable or disable this option with 1 or 0 values respectively.

maxconnections - the possible maximum number of connections to the server. Applicable only to SERVER connection type.

network tag 

May include:

nagle - enables/disables the Nagle algorithm. Applicable only to CLIENT and SERVER connection types. enable attribute can be set to either 1 or 0.

keepalive - configures "Keep Alive" messages sending:

enable attribute:

1= sending "Keep Alive" messages is on,

0 - off.

timeout - sets the interval of sending "Keep Alive" messages in milliseconds.

noreply - the interval of sending the "Keep Alive" message if the response was not received from the remote computer.

break - sets "Break connection if no activity for" option behavior.

enable attribute indicates whether this option is enabled or not.

timeout attribute indicates the interval in milliseconds after which the connection should be broken

incomeport - applicable to SERVER and UDP connection types. Includes port attribute which indicates a TCP port on which the server listens to incoming connections on.

If this parameter is edited via the UPDATE command, the current connection will be broken.

host - applicable to CLIENT and UDP connection types. Indicates remote host to be connected to. Includes two attributes:

name and port- indicate the hostname (IP address) of the remote computer and the port to connect to.

network may have several tags of such type.

security tag 

auth - sets authorization options. Has the following attributes:

dll - the name of the DLL which sets the password authorization in connections; auth.dll is used by default.

pwd - sets password encryption. The following algorithm is used:

Every password symbol is encrypted with XOR logical operation with -1.

The result is generated into the string in hexadecimal format and is put at the end of the resulting string. So the resulting string contains the set of hexadecimal numbers - the encrypted password.

enable - enables/disables authorization, the latter breaking active current connections.

crypt - encryption of communication data. The following attributes are available:

dll - the name of DLL, which encrypts all the communication data. crypt.dll is used by default.

enable - enabled/disabled encryption:

1 – enabled

0 - disabled

proxy tag 

Configures the proxy server settings for connection of CLIENT type. The following settings are available:

type - sets proxy server's type: HTTP, SOCKS4, SOCKS5

dns - numerical attribute managing "Redirect DNS requests to proxy server" option; has the following values: 0 or 1. E.g.: <proxy type="HTTP" dns="1"/>

host - this tag sets server parameters via name and port attributes which set the name/IP address of the proxy server and TCP port to connect to.

auth - sets proxy server authorization. user and pwd attributes set username and password correspondingly. If the user attribute is not set or is empty, authorization is considered to be disabled. The password is stored encrypted. Every password symbol is encrypted with XOR logical operation with -1. The result is generated into the string in hexadecimal format and is put at the end of the resulting string. So the resulting string contains the set of hexadecimal numbers - the encrypted password.

ctrlsconn and ctrldisconn tags

Manage signal lines states when the connection is (ctrlsconn) or is not established (ctrldisconn).

May have the following attributes: dtr, rts, and dcd.

dcd is ignored if a real serial port is used. dtr and rts attributes manage DTR and RTS signal lines.

If the virtual port is used, dtr, rts, and dcd parameters manage DSR, CTS, and DCD signal lines correspondingly.

GETLIST command

Gets the list of connections.

E.g.:

<proto version="6.0">

<operation type=”GETLIST"/>

</proto>

If the command succeeds, it returns LIST. Otherwise ERROR.

status - additional optional attribute which returns additional statistics on the connection. The statistics are placed into the status tag of the corresponding connection.

E.g.:

<proto version="6.0">

<operation type="GETLIST" status="1"/>

</proto>

The attribute returns:

<proto version="6.0">

<operation type="LIST">

<connection>

….............................

<status> …... </status>

</connection>

<connection>

…...............................

<status> …... </status>

</connection>

</operation>

</proto>

LIST response

It is the structure returned by GETLIST and GETMIRRORLIST commands.

An empty list is returned in case there are no connections on the server.

<proto version="6.0">

<operation type="LIST" />

</proto>

If there are one or more connections, each connection parameter will be saved in the connection tag:

<proto version="6.0">

<operation type="LIST">

<connection>

….............................

</connection>

<connection>

…...............................

</connection>

…................................

…..............................

<connection>

…...............................

</connection>

</operation>

</proto>

ADD command

Adds new connection.

If the command succeeds, it returns SUCCESS. Otherwise ERROR.

New connection parameters are set in the connection tag.

For example:

<proto version="6.0">

<operation type="ADD">

<connection>

<type>CLIENT</type>

<name>Client_COM1</name>

<port>

<name>COM11</name>

<buffer enable="1" max="131072" />

<sendmode mode="2" param="0" />

<type>Virtual</type>

</port>

<protocol>

<type>RAW</type>

<access write="0" read="1" />

<reconnect timeout="5000" />

<portopencondition enable="1" />

</protocol>

<network>

<host name="localhost" port="5002" />

<nagle enable="0" />

<keepalive timeout="7000" noreply="1000" units="msec"

enable="1" />

<break timeout="10000" enable="1" />

<incomeport port="5001" />

</network>

<security />

<ctrlsconn dtr="0" rts="0" dcd="0" />

<ctrldisconn dtr="0" rts="0" dcd="0" />

</connection>

</operation>

</proto>

UPDATE command

Updates connection settings.

applyto - additional attribute used to indicate the connection name to which new settings should be applied.

For example, in this XML code, the changes in COM port settings are being requested; the rest of the settings for the current connection will be automatically accepted as well.

<proto version="6.0">

<operation type="UPDATE" applyto="Server_COM1">

<connection>

<port>

<name>COM12</name>

<buffer enable="1" max="131072" />

<settings>9600,N,8,1</settings>

</port>

</connection>

</operation>

</proto>

In case when changes occur to the TCP port on the server, the list of already connected active clients, data transmission protocol (RAW/TELNET), or security settings, the current connections will be broken.

This command does not change the type of connection. To do so, remove and add the connection once again.

For example:

<proto version="6.0">

<operation type="UPDATE" applyto="Server_COM1">

<connection>

<type>SERVER</type>

<name>Server_COM1</name>

<port>

<name>COM1</name>

<buffer enable="1" max="131072" />

<sendmode mode="0" param="0" />

<settings>9600,N,8,1</settings>

</port>

<protocol>

<type>RAW</type>

<access write="2" read="2" />

<maxconnections value="25" />

<portopencondition enable="0" />

</protocol>

<network>

<keepalive timeout="7000" noreply="1000" units="msec" enable="1" />

<break timeout="10000" enable="1" />

<incomeport port="5001" />

</network>

<security />

<ctrlsconn dtr="0" rts="0" dcd="0" />

<ctrldisconn dtr="0" rts="0" dcd="0" />

</connection>

</operation>

</proto>

GETSTAT command

Gets statistics on all connections. STAT structure is returned.

<proto version="6.0">

<operation type="GETSTAT" />

</proto>

applyto attribute is used to set the name of the connection for which statistics is required.

<proto version="6.0">

<operation type="GETSTAT" applyto=”server1” />

</proto>

STAT response

Is returned by GETSTAT command.

STAT response includes a connection tag.

connection tag contains name and status tags:

name - connection name

status - the tag where all connection statistics and statuses are placed in. It contains the following tags:

port - indicates the state of the current COM port.

stat - current statistics of sent and received bytes. Is included in sent and recv attributes accordingly.

remotehost - indicates the state of connection to the remote PC.

serverstate - indicates the state of the listening port for connections of SERVER type.

Also, the status tag has an optional attribute stopped which is set to '1' when the connection is stopped.

port tag has state and settings attributes:

state attribute values are the following:

settings attribute - includes COM port parameters in the following format:

[Baudrate, Parity, Databits, Stopbits, FlowControl]

e.g.: 9600,N,8,1

The example of COM port parameters is the following:

<port state="2" settings="9600,N,8,1" />

Additional tags depend on the connection type:

For connection of CLIENT and UDP type:

remotehost tag - indicates the state of connection to the remote PC. The attributes for the client connection are the following:

id - connection ID/remote host ID

host and port - the name of the remote server and the port to connect to;

sent and recv - the number of sent and received bytes;

state - the current connection state: 0 - disconnected, 1 - connected. For UDP connection state value is always "1" and can be ignored.

For connection of SERVER type:

serverstate tag - describes the state of the network server. This tag has the following attributes:

state attribute - indicates the current server state. May have the following values:

activeconns attribute - indicates the current number of active connections.

remotehost tag - describes the state of connected computers and has the following attributes:

id - ID of the connected client;

host - the name of the connected host;

sent and recv - the number of sent and received bytes.

Statistics example:

<proto version="6.0" >

<operation type="STAT">

<connection>

<name>Client_COM1</name>

<status stopped="1">

<port state="1" settings="" />

<stat sent="0" recv="0" />

<remotehost host="localhost" port="5002" state="0"

sent=”22” recv=”33”/>

</status>

</connection>

<connection>

<name>Server_COM1</name>

<status>

<port state="2" settings="9600,N,8,1" />

<stat sent="0" recv="0" />

<serverstate state="2" activeconns="20" />

<remotehost id="333454" host=”192.168.0.52” sent=”1245”

recv=”33” >

<remotehost id="1234567" host=”192.168.0.152” sent=”1245” recv=”33” >

</status>

</connection>

</operation>

</proto>

DELETE command

Deletes connection. Can delete several connections. Each connection should be specified via connection and name tags.

<proto version="6.0" >

<operation type="DELETE">

<connection>

<name>Server_COM1</name>

</connection>

<connection>

<name>Server_COM2</name>

</connection>

</operation>

</proto>

To delete all connections, the all attribute of the operation tag is used.

<proto version="6.0" >

<operation type="DELETE" all=”1”/>

</proto>

GETMIRRORLIST command

This command is deprecated.

ACCEPT command

This command is deprecated.

DECLINE command

This command is deprecated.

STOP command

Stops a given connection

applyto - additional attribute used to indicate the name of the connection that should be stopped.

Example:

<proto version="6.0">

<operation type="STOP" applyto=”Server COM1” />

</proto>

START command

Restarts previously stopped connection.

applyto - additional attribute used to indicate the name of the connection that should be restarted.

Example:

<proto version="6.0">

<operation type="START" applyto=”Server COM1” />

</proto>

DISCONNECT command

Breaks existing network connection.

applyto - additional attribute used to indicate the name of the connection that should be broken

peer - the remote host ID

You can obtain the peer ID from the id attribute of the corresponding

<remotehost> tag received in the STAT response.

<proto version="6.0">

<operation type="DISCONNECT" applyto=”Server COM1” peer="203043" />

</proto>

RESETSTAT command

Sets sent/received bytes count for given network connection to 0.

applyto - additional attribute used to indicate the name of the connection for which the statistics should be reset.

peer - the remote host ID.

You can obtain the peer ID from the id attribute of the corresponding

<remotehost> tag received in the STAT response.

<proto version="6.0">

<operation type="RESETSTAT" applyto=”Server COM1” peer="203043" />

</proto>

GETOPTION and SETOPTION commands 

on-mirror-request - mode of mirror requests handling. Has the following values: 

Example:

<proto version="6.0" >

<operation type="GETOPTION">

<option name="on-mirror-request" value="1" />

</operation>

</proto>

<proto version="6.0">

<operation type="SETOPTION">

<option name="on-mirror-request" value="1" />

</operation>

</proto>