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 \| LargeSocketWrite
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 currently 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.
14	UDP local port number
15	Socket type (0 TCP, 1 UDP)
16	UDP destination IP
17	UDP is broadcast flag
18	Structure containing counters and timestamps of bytes transmitted and received.
19	Protocol 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.
20	Will return the current output buffer limit size, in bytes.

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:

Used to determine the size of the output buffer limit on a socket, modify it and obtain the amount of data currently in the output buffers (i.e. not transmitted).

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.

FilterID = "RAW"

Opcode == 0

Data == Maximum size of the output buffer for the socket, in bytes. If more data than this is pending transmission from the output buffer, the socket will be closed and the stream will go Invalid.