Stream​Socket​Control Stream​Socket​Control Stream​Socket​Control Stream​Socket​Control Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

[Contains prerelease APIs.]
Provides socket control data on a StreamSocket object.

public : sealed class StreamSocketControl : IStreamSocketControl, IStreamSocketControl2, IStreamSocketControl3public sealed class StreamSocketControl : IStreamSocketControl, IStreamSocketControl2, IStreamSocketControl3Public NotInheritable Class StreamSocketControl Implements IStreamSocketControl, IStreamSocketControl2, IStreamSocketControl3// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
bluetooth.rfcomm ID_CAP_NETWORKING [Windows Phone]

Remarks

The StreamSocketControl class provides access to advanced socket control data on a StreamSocket object.

A StreamSocketControl object is automatically created with the parent StreamSocket object. The StreamSocket.Control property provides access to the associated StreamSocketControl object.

Any changes to the property values on the StreamSocketControl must be set before the StreamSocket is connected. As a result if you need to make changes to the ClientCertificate, IgnorableServerCertificateErrors, KeepAlive, NoDelay, OutboundBufferSizeInBytes , OutboundUnicastHopLimit, or QualityOfService properties, then these changes must occur before a successful call to one of the ConnectAsync methods on the StreamSocket.

Use the ClientCertificate to set a client certificate to be used to make secure connections over the associated StreamSocket object.

The following example creates a StreamSocket, and then demonstrates how to set the NoDelay property to false. Other properties may be set in a similar manner. After this is done, the app can connect the StreamSocket.

var clientSocket = new Windows.Networking.Sockets.StreamSocket();

// Get the current setting for this option
// This isn't required, but it shows how to get the current setting
var currentSetting = clientSocket.Control.noDelay; 

// Set noDelay to false so that the Nagle algorithm is not disabled
clientSocket.control.noDelay = false;

// Now you can call the ConnectAsync method to connect the StreamWebSocket.
using Windows.Networking.Sockets;

StreamSocket clientSocket = new StreamSocket();

// Get the current setting for this option
// This isn't required, but it shows how to get the current setting
bool currentSetting = clientSocket.Control.NoDelay;

// Set NoDelay to false so that the Nagle algorithm is not disabled
clientSocket.Control.NoDelay = false;

// Now you can call the ConnectAsync method to connect the StreamSocket.

using namespace Windows::Networking::Sockets;

StreamSocket^ clientSocket = ref new StreamSocket();

// Get the current setting for this option
// This isn't required, but it shows how to get the current setting 
bool currentSetting = clientSocket->Control->NoDelay;

// Set NoDelay to false so that the Nagle algorithm is not disabled
clientSocket->Control->NoDelay = false;

// Now you can call the ConnectAsync method to connect the StreamSocket.

For more information on using StreamSocketControl, see How to use advanced socket controls and How to use advanced socket controls .

Properties

ClientCertificate ClientCertificate ClientCertificate ClientCertificate

Gets or sets the client SSL/TLS certificate that will be sent to the server if the server requests a client certificate.

public : Certificate ClientCertificate { get; set; }public Certificate ClientCertificate { get; set; }Public ReadWrite Property ClientCertificate As Certificate// You can use this property in JavaScript.
Value
Certificate Certificate Certificate Certificate

The client certificate.

IgnorableServerCertificateErrors IgnorableServerCertificateErrors IgnorableServerCertificateErrors IgnorableServerCertificateErrors

Get a vector of SSL server errors to ignore when making an SSL connection with a StreamSocket.

public : IVector<ChainValidationResult> IgnorableServerCertificateErrors { get; }public IList<ChainValidationResult> IgnorableServerCertificateErrors { get; }Public ReadOnly Property IgnorableServerCertificateErrors As IList<ChainValidationResult>// You can use this property in JavaScript.
Value
IVector<ChainValidationResult> IList<ChainValidationResult> IList<ChainValidationResult> IList<ChainValidationResult>

A vector of SSL server errors to ignore.

Remarks

The IgnorableServerCertificateErrors property gets a vector of ChainValidationResult enumeration values for the SSL server errors to ignore.

SSL server errors should only be ignored in advanced scenarios. Disregarding server certificate errors may result in the loss of privacy or integrity of the content passed over the SSL session.

See Also

KeepAlive KeepAlive KeepAlive KeepAlive

A value that indicates whether keep-alive packets are sent to the remote destination on a StreamSocket object.

public : PlatForm::Boolean KeepAlive { get; set; }public bool KeepAlive { get; set; }Public ReadWrite Property KeepAlive As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Whether keep-alive packets are sent to the remote destination.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

When this property is true, the StreamSocket sends keep-alive packets when no data or acknowledgment packets have been received for the TCP connection within an interval. When a StreamSocket is created, the default value for this property is false.

This property may be set before the StreamSocket is connected. After the StreamSocket is connected, setting the property will result in an error.

For more detailed information, see the SO_KEEPALIVE socket option in the Windows Sockets documentation.

See Also

MinProtectionLevel MinProtectionLevel MinProtectionLevel MinProtectionLevel

Prerelease. Constrains the TLS protocol version that will be negotiated when the developer uses the ConnectAsync() or UpgradeToSslAsync() methods that require TLS.

public : SocketProtectionLevel MinProtectionLevel { get; set; }public SocketProtectionLevel MinProtectionLevel { get; set; }Public ReadWrite Property MinProtectionLevel As SocketProtectionLevel// You can use this property in JavaScript.
Value
SocketProtectionLevel SocketProtectionLevel SocketProtectionLevel SocketProtectionLevel

A SocketProtectionLevels enumeration member indicating the socket protection level.

Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16225.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)
Capabilities
bluetooth.rfcomm ID_CAP_NETWORKING [Windows Phone]

Remarks

When the server does not meet the TLS version specified by MinProtectionLevel, the corresponding ConnectAsync() and/or UpgradeToSslAsnc() execution will behave just as if the server does not support SSL or TLS.

See Also

NoDelay NoDelay NoDelay NoDelay

A value that indicates whether the Nagle algorithm is used on a StreamSocket object.

public : PlatForm::Boolean NoDelay { get; set; }public bool NoDelay { get; set; }Public ReadWrite Property NoDelay As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

A value that indicates whether the Nagle algorithm is used on the TCP connection of a StreamSocket object

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

The NoDelay property controls whether Nagle's algorithm is enabled or disabled on a StreamSocket object. The default value for the NoDelay property is true.

Nagle's algorithm is a technique to improving the efficiency of TCP/IP networks by reducing the number of packets that are needed to be sent over the network. The algorithm tries to deal with problems caused by an application that repeatedly emits data in small chunks. A TCP packet has a 40-byte header (20 bytes for IP and 20 bytes for TCP). So if an app sends only 4 bytes in a packet, the overhead on the packet data is very large. This can occur for a remote access protocol (telnet or secure shell, for example) where most key presses may generate only a single byte or two of data that is transmitted immediately. Over a slow link, many of these packets may be in transit over the network at the same time. Nagle's algorithm works by combining a number of small outgoing messages, and sending them all at once. When there is a sent packet for which the sender has received no acknowledgment, the sender keeps buffering output until it has a full packet's worth of output. This allows the output to be sent all at once. The impact of applying Nagle's algorithm is to increase the bandwidth at the expense of latency. A well-written app that buffers sends internally should not need to use Nagle's algorithm.

When this property is true, the StreamSocket will disable Nagle's algorithm on the TCP connection. This setting reduces the potential delays when sending small messages. When a StreamSocket is created, the default value for this property is true.

When this property is false, the StreamSocket will enable Nagle's algorithm on the TCP connection. This setting can increase the bandwidth at the expense of latency, but should only be used with caution. There are some adverse side effects possible when Nagle's algorithm is enabled and certain other TCP optimizations are also used.

This property may be set before the StreamSocket is connected. After the StreamSocket is connected, setting the property will result in an error.

This property sets the value of the TCP_NODELAY socket option on the TCP socket used by the StreamSocket.

See Also

OutboundBufferSizeInBytes OutboundBufferSizeInBytes OutboundBufferSizeInBytes OutboundBufferSizeInBytes

The size, in bytes, of the send buffer to be used for sending data on a StreamSocket object.

public : unsigned short OutboundBufferSizeInBytes { get; set; }public uint OutboundBufferSizeInBytes { get; set; }Public ReadWrite Property OutboundBufferSizeInBytes As uint// You can use this property in JavaScript.
Value
unsigned short uint uint uint

The size, in bytes, of the send buffer to be used for sending data.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

The OutboundBufferSizeInBytes property sets the value of the SO_SNDBUF socket option on the TCP socket used by the StreamSocket. The default value is the local computer's default send buffer size. This value varies based on the system memory size. For more detailed information, see SOL_SOCKET Socket Options in the Windows Sockets documentation.

For most apps, this property should not be set since this disables TCP send auto-tuning by the system on this StreamSocket object. With TCP send auto-tuning disabled, network throughput is often worse especially on a connections with high latency. So this property should only be used in very specific situations.

The OutboundBufferSizeInBytes property must be set before the StreamSocket is connected. Setting this property after the StreamSocket is connected has no effect.

See Also

OutboundUnicastHopLimit OutboundUnicastHopLimit OutboundUnicastHopLimit OutboundUnicastHopLimit

The hop limit on an outbound packet sent to a unicast IP address by the StreamSocket object.

public : byte OutboundUnicastHopLimit { get; set; }public byte OutboundUnicastHopLimit { get; set; }Public ReadWrite Property OutboundUnicastHopLimit As byte// You can use this property in JavaScript.
Value
byte byte byte byte

The hop limit on an outbound packet sent by the StreamSocket object. The default is 128.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

This value indicates the hop limit that is set on an outbound TCP packet sent to a unicast IP address using the StreamSocket object. This property is used to set the Time to Live (TTL) field in an IPv4 packet header. This property is used to set the Hop Limit field in an IPv6 header. The default value for this property is 128.

This property may be set before the StreamSocket is connected. After the StreamSocket is connected, setting this property will result in an error.

Setting the OutboundUnicastHopLimit may not have an effect if the system doesn't support setting the TTL.

See Also

QualityOfService QualityOfService QualityOfService QualityOfService

The quality of service on a StreamSocket object.

public : SocketQualityOfService QualityOfService { get; set; }public SocketQualityOfService QualityOfService { get; set; }Public ReadWrite Property QualityOfService As SocketQualityOfService// You can use this property in JavaScript.
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

This property indicates the quality of service that StreamSocket object should provide. The default value is normal.

When the property is set to a value other than normal, the socket will follow a policy to provide the specified quality of service. When the property is set to lowLatency, the priority of the thread that handles read completions is increased. The lowLatency value would commonly be used for audio or similar apps that are timing sensitive. This property is not normally set for other apps.

This property may be set before the StreamSocket is connected. After the StreamSocket is connected, setting this property will result in an error.

See Also

SerializeConnectionAttempts SerializeConnectionAttempts SerializeConnectionAttempts SerializeConnectionAttempts

A value that indicates whether, when multiple connection attempts are being made, the attempts are made in parallel or serially.

public : PlatForm::Boolean SerializeConnectionAttempts { get; set; }public bool SerializeConnectionAttempts { get; set; }Public ReadWrite Property SerializeConnectionAttempts As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

When true, at most one connection attempt will be active at one time on this StreamSocket. Default value is false.

Remarks

In certain circumstances, the Windows runtime might attempt to establish a connection using multiple methods in parallel. For example, when StreamSocket attempts a connection and a proxy is detected on the network, it attempts both a direct connection to the specified IP address, and an HTTP CONNECT request (which will connect via the proxy) in parallel. The first connection to succeed is the one that is used by the StreamSocket object. While this works well in most cases, it causes problems with some servers in the case where both connection attempts succeed. If your app is using StreamSocket to connect to a server where the parallel connection method causes problems on the server, you should set SerializeConnectionAttempts to true before connecting. This will ensure that at most one TCP connection attempt is ongoing at any given time, and that only a single connection is used.

Your code must set this property before you call ConnectAsync to attempt to connect. Changing this property value after ConnectAsync has been called results in an exception being thrown.

Note that serializing the connection logic can make establishing the connection take longer.

See Also