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:


CommandDescriptionReturn value if succeeds
GETLISTGets the list of all connections available together with the settings appliedLIST
ADDAdds connectionSUCCESS
GETSTATGets statistics on all active connectionsSTAT
DELETERemoves connectionSUCCESS
GETMIRRORLISTGets the list of mirror requests. LIST
ACCEPTAccepts the request for mirror connection creationSUCCESS
DECLINEDeclines the request for mirror connection creationSUCCESS
UPDATEUpdates connection settingsSUCCESS 
GETOPTION Gets the Service option---
SETOPTIONSets the Service option SUCCESS
STARTRestarts previously stopped connectionSUCCESS 
STOPStops the given connectionSUCCESS
DISCONNECTBreaks existing network connectionSUCCESS
RESETSTATSets sent/received bytes count for the given network connection to 0SUCCESS


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:


Mode
Transmission algorithm
Attribute meaning
1Add pause between packets
timeout in msec
2Before sending data wait for
timeout in msec
3Send data when the block reached the size of the specified value
buffer size in bytes
4Send data when received char with code
ASCII code of char


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.


Access mode
Value
None of the connected clients can read/write
0
Only the first connected client can read/write
1
Only the last connected client can read/write
2
Only the last active client can read/write
3
All connected clients can read/write
4


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:


Connection Type
Port TypeDescription
Server
Virtual
Start listening for incoming connections only when the local virtual port is open
Server Real
Open local real port only when at least 1 incoming connection is active
Client
Virtual
Connect to the remote end only when the local virtual port is open
Client Real
Open local real port only when the connection is established


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:



Not created. Error.
Created
Closed
Opened 
real COM port
N/A
N/A
32
virtual COM port
0132


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:


Value
State
0Initial state. Disconnected (the server is not listening and does not have active connections)
1Connected and listening (one or more clients are connected).
2The server is listening to incoming connections. No connected clients.
3The maximum number of connections is reached (out of capacity).
4The error occurred on the server.


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: 


Option
Value
Accept all requests and create connections automatically
1
Accept all requests and create connections manually
2
Decline all requests
3


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>