SocketAttribs

(Engine-Level Function)

Description: Returns information about a TCP/IP socket's attributes.
Returns: Text or Buffer (see comments)
Usage: Script Only.
Function Groups: Stream and Socket
Related to: ClientSocket | CloseStream | ServerSocket | SocketAttribs | SocketServerEnd | SocketServerStart | SocketWait | SRead | StreamEnd | SWrite |
Format: SocketAttribs(Stream, Option [,FilterID, Opcode , Data])
Parameters:  
Stream
Required. Any stream expression for the socket. If this isn't a socket stream, invalid is returned.
Option
Required. Any numeric expression for the desired attribute:

Option

Attribute

0

Remote (text) workstation name

1

Remote port number

2

Remote workstation IP

3

Local machine name

4

Local machine IP

5

Number of bytes in the output buffer

6

Remote (text) workstation name (buffered)

7

Remote workstation IP (buffered)

8

Local machine name (buffered)

9

Local machine IP (buffered)

10

Remote machine Name (for incoming UDP datagrams)

11

Remote Port (for incoming UDP datagrams)

12

Remote IP (for incoming UDP datagrams)

13

Activate optional filters specified in ClientSocket()

Supported only by TLS/SSL and WebSockets. For WebSockets, use "WSKT" as the protocol filter. No user action is required for TLS/SSL.

14UDP local port number
15Socket type (0 TCP, 1 UDP)
16UDP destination IP
17UDP is broadcast flag
18Structure containing counters and timestamps of bytes transmitted and received.
19Protocol filter control.
With option 19, the FilterID and Opcode must be present. Depending on the FilterID and Opcode, additional Data may need to be provided.
FilterID
Optional text. Set to "WSKT" for WebSockets.
OpCode
Optional numeric. Refer to the list in the comments.
Data
Optional text. Refer to the list in the comments.
Comments:

The return value for options 0 and 6 is the machine name stored as a text value. If the name cannot be found it will return the internet address of the socket as a text string.
Options 6 through 9 differ from options 0 and 2 through 4 only in the fact that they are buffered. This means that an initial inquiry will be made to the operating system and stored in a buffer, and after that, all inquiries will be handed the value stored in the buffer. This makes options 6 through 9 significantly faster than the other options, however, any online changes to the workstation's attributes will be not be discovered by options 6 to 9, only 0 and 2 to 4 would return the new values.

If using option 13 to activate optional filters, note that (as of VTScada version 12.1) TLS/SSL and WebSocket are the only ones supported.

Option 19 provides control operations for protocol filters that support this:

FilterID = "WSKT"

Opcode == 0 (Activate).
Data is ignored, if present.

Opcode == 1 (Max Rx Time).
Data is an integer number of seconds allowed between the start of a WebSocket protocol frame and its end (range 1-65535). This is to prevent a malicious actor from holding the port open. Defaults to 60 seconds.

Opcode == 2 (Ping time).
Data is an integer number of seconds during which if there is no communication on the connection, a WebSocket protocol PING frame will be transmitted (range 0-65535). A value of zero disables the PING. Defaults to zero.

Opcode == 3 (Close time).
Data is an integer number of seconds to wait after issuing a WebSocket protocol CLOSE frame before closing the connection (range 3-65535). This is to allow the remote end to transmit its CLOSE frame in response and is provided to prevent the remote end from refusing to send a CLOSE frame and hold the connection open. Defaults to 3.

Opcode == 4 (Tx Max Frame Size).
Data is an integer number of bytes that will be contained in a transmitted WebSocket protocol frame. Messages to be transmitted that are longer than this will be fragmented into multiple frames. Defaults to 4096. Note: Do not use an excessively large number, even though this is a 32-bit quantity.