diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index 57bb5301b8f..323695c544f 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -247,7 +247,7 @@ This method populates the instance with data ga One of the values. One of the values. - Initializes a new instance of the class using the specified socket type and protocol. + Initializes a new instance of the class using the specified socket type and protocol. If the operating system supports IPv6, this constructor creates a dual-mode socket; otherwise, it creates an IPv4 socket. instance with data ga The `socketType` parameter specifies the type of the class and the `protocolType` parameter specifies the protocol used by . The two parameters are not independent. Often the type is implicit in the protocol. If the combination of type and protocol type results in an invalid , this constructor throws a . > [!NOTE] -> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ]]> @@ -2835,9 +2835,9 @@ This method populates the instance with data ga A string that contains the path and name of the file to be sent. This parameter can be . - A array that contains data to be sent before the file is sent. This parameter can be . - A array that contains data to be sent after the file is sent. This parameter can be . - A bitwise combination of values. + The data to be sent before the file is sent. This parameter can be . + The data to be sent after the file is sent. This parameter can be . + A bitwise combination of the enumeration values. An delegate to be invoked when this operation completes. This parameter can be . A user-defined object that contains state information for this request. This parameter can be . Sends a file and buffers of data asynchronously to a connected object. @@ -2867,9 +2867,7 @@ This method populates the instance with data ga > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). > [!NOTE] -> The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous methods. After the first use of a particular context (a specific asynchronous method, a specific instance, and a specific callback), subsequent uses of that context will see a performance improvement. - - +> The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous methods. After the first use of a particular context (a specific asynchronous method, a specific instance, and a specific callback), subsequent uses of that context will see a performance improvement. ## Examples The following code example creates and connects a socket for asynchronous communication and begins sending the file "text.txt" asynchronously to the remote host. In this example, a `preBuffer` and a `postBuffer` of data is created to send with the file and the default value is used. The callback delegate calls to complete the transmission. @@ -3615,9 +3613,7 @@ This method populates the instance with data ga > If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example connects to a remote endpoint and then verifies the connection. @@ -3632,7 +3628,7 @@ This method populates the instance with data ga The port number is not valid. An error occurred when attempting to access the socket. The has been closed. - This method is valid for sockets in the or families. + The socket is not in the or families. The length of is zero. The has been placed in a listening state by calling . @@ -3683,24 +3679,22 @@ This method populates the instance with data ga method synchronously establishes a network connection between and the specified remote host. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. + If you're using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote host. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you're using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + The method will block, unless you specifically set the property to `false` prior to calling . If you're using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. +> If you're using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. > [!NOTE] > If the socket has been previously disconnected, then you cannot use this method to restore the connection. Use one of the asynchronous methods to reconnect. This is a limitation of the underlying provider. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example connects to a remote endpoint and then verifies the connection. @@ -3715,7 +3709,7 @@ This method populates the instance with data ga The port number is not valid. An error occurred when attempting to access the socket. The has been closed. - This method is valid for sockets in the or families. + The socket is not in the or families. The has been placed in a listening state by calling . @@ -4573,11 +4567,9 @@ This method populates the instance with data ga option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. + Datagrams require fragmentation when their size exceeds the Maximum Transfer Unit (MTU) of the transmission medium. Datagrams may be fragmented by the sending host (all Internet Protocol versions) or an intermediate router (Internet Protocol Version 4 only). If a datagram must be fragmented and the option is set, the datagram is discarded, and an Internet Control Message Protocol (ICMP) error message is sent back to the sender of the datagram. - Setting this property on a Transmission Control Protocol (TCP) socket will have no effect. - - + Setting this property on a Transmission Control Protocol (TCP) socket has no effect. ## Examples The following code example demonstrates the use of the property. @@ -4587,7 +4579,7 @@ This method populates the instance with data ga ]]> - This property can be set only for sockets in the or families. + The socket is not in the family. An error occurred when attempting to access the socket. The has been closed. @@ -4626,10 +4618,11 @@ This method populates the instance with data ga System.Boolean - Gets or sets a value that specifies whether the is a dual-mode socket used for both IPv4 and IPv6. + Gets or sets a value that specifies whether the is a dual-mode socket used for both IPv4 and IPv6. - if the is a dual-mode socket; otherwise, . The default is . + if the is a dual-mode socket; otherwise, . The default is if the socket was created by calling the constructor and the operating system supports IPv6; otherwise, the default is . To be added. + The socket is not in the address family. @@ -6917,9 +6910,7 @@ The maximum length of the pending connections queue is determined automatically. ## Remarks Multicast is a scalable method for many-to-many communication on the Internet. A process subscribes to a multicast address; then, any packets sent by a subscribed process are received by every other process subscribed to the multicast address. - Setting this property on a Transmission Control Protocol (TCP) socket will have no effect. - - + Setting this property on a Transmission Control Protocol (TCP) socket has no effect. ## Examples The following code example demonstrates the use of the property. @@ -6931,6 +6922,7 @@ The maximum length of the pending connections queue is determined automatically. An error occurred when attempting to access the socket. The has been closed. + The is not in the or families. @@ -7209,7 +7201,7 @@ The maximum length of the pending connections queue is determined automatically. method will check the state of the . Specify for the `selectMode` parameter to determine if the is readable. Specify to determine if the is writable. Use to detect an error condition. will block execution until the specified time period, measured in `microseconds`, elapses. Set the `microSeconds` parameter to a negative integer if you would like to wait indefinitely for a response. If you want to check the status of multiple sockets, you might prefer to use the method. + The method checks the state of the . Specify for the `selectMode` parameter to determine if the is readable. Specify to determine if the is writable. Use to detect an error condition. will block execution until the specified time period, measured in `microseconds`, elapses. Set the `microSeconds` parameter to a negative integer if you would like to wait indefinitely for a response. If you want to check the status of multiple sockets, you might prefer to use the method. > [!NOTE] > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -11089,10 +11081,10 @@ This member outputs trace information when you enable network tracing in your ap - A that contains the path and name of the file to be sent. This parameter can be . - A array that contains data to be sent before the file is sent. This parameter can be . - A array that contains data to be sent after the file is sent. This parameter can be . - One or more of values. + The path and name of the file to be sent. This parameter can be . + The data to be sent before the file is sent. This parameter can be . + The data to be sent after the file is sent. This parameter can be . + A bitwise combination of the enumeration values that specifies how the file is transferred. Sends the file and buffers of data to a connected object using the specified value. If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example creates and connects a socket. The file "test.txt" is located in the root directory of the local machine. In this example, we create a prebuffer and postbuffer of data and send them to the remote host with the file. The default are used. @@ -11260,7 +11250,7 @@ This member outputs trace information when you enable network tracing in your ap The file specified in the property was not found. A socket operation was already in progress using the object specified in the parameter. - Windows XP or later is required for this method. This exception also occurs if the is not connected to a remote host. + The is not connected to a remote host. The has been closed. A connectionless is being used and the file being sent exceeds the maximum packet size of the underlying transport. @@ -11311,9 +11301,7 @@ This member outputs trace information when you enable network tracing in your ap calls only. If the time-out period is exceeded, the method will throw a . - - + This option applies to synchronous calls only. If the time-out period is exceeded, the method will throw a . ## Examples The following code example demonstrates the use of the property. @@ -11400,9 +11388,7 @@ This member outputs trace information when you enable network tracing in your ap > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example sends a connectionless datagram to the specified remote host. @@ -11493,9 +11479,7 @@ This member outputs trace information when you enable network tracing in your ap > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example sends a connectionless datagram to the specified remote host. are passed to the method. @@ -11594,9 +11578,7 @@ This member outputs trace information when you enable network tracing in your ap > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example sends a connectionless datagram to the specified remote host. The size and are passed to the method. @@ -11692,9 +11674,7 @@ This member outputs trace information when you enable network tracing in your ap > If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example sends a connectionless datagram to the specified remote host. The offset, size, and are passed to the method. @@ -11954,7 +11934,7 @@ This member outputs trace information when you enable network tracing in your ap The IP protection level to set on this socket. - Set the IP protection level on a socket. + Sets the IP protection level on a socket. - The parameter cannot be . The IP protection level cannot be set to unspecified. - The of the socket must be either or . + The argument is set to . + The socket is not in the or address families. @@ -12133,9 +12113,7 @@ The enumeration. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - +> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples The following code example opens a socket and enables the `DontLinger` and the `OutOfBandInline` socket options. @@ -12204,9 +12182,7 @@ The If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example sets the and time-out values. @@ -12345,9 +12321,7 @@ The If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). ## Examples The following code example sets the and time-out values. @@ -12417,10 +12391,8 @@ The options determine the behavior of the current . Use this overload to set the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to get the current value of any of the options listed above, use the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - - +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + ## Examples The following code example sets the and time out values. @@ -12513,10 +12485,8 @@ The If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] -> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). - - - +> This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). + ## Examples The following code example uses to disable the . @@ -12580,10 +12550,8 @@ The is read-only and is set when the is created. - - - + is read-only and is set when the is created. + ## Examples The following code example displays the , , and to the console. @@ -12816,9 +12784,7 @@ Call IDisposable.Dispose when you are finished using the , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - - + If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples The following code example demonstrates the use of the property. @@ -12828,8 +12794,8 @@ Call IDisposable.Dispose when you are finished using the - The TTL value can't be set to a negative number. - This property can be set only for sockets in the or families. + The TTL value is a negative number. + The socket is not in the or families. An error occurred when attempting to access the socket. This error is also returned when an attempt was made to set TTL to a value higher than 255. The has been closed.