From 259ba8fd2916b10f93044850eefec1c0c81b5725 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 3 Nov 2023 12:26:59 -0700 Subject: [PATCH 1/2] update exceptions --- xml/System.Net.Sockets/Socket.xml | 72 ++++++++++++++++--------------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index a6d07280d31..6e3d244eee9 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -91,12 +91,12 @@ ### Synchronous mode The following example shows how the class can be used to send data to an HTTP server, printing the ASCII response to the standard output. This example blocks the calling thread until the entire page is received. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Overview/socket.cs" id="Snippet1"::: ### Asynchronous mode The second example demonstrates the same HTTP GET scenario, using Task-based asynchronous API-s, while also forwarding a to the asynchronous methods, making the entire operation cancellable. - + > [!TIP] > 's async methods that do not take a typically return a , which is allocated on the heap. > Cancellable overloads are always -returning; using them helps reducing allocations in high-performance code. @@ -3077,7 +3077,7 @@ This method populates the instance with data ga You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. @@ -3170,7 +3170,7 @@ This method populates the instance with data ga You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. @@ -3283,7 +3283,7 @@ This method populates the instance with data ga You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. - The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. + The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. If you are using a connection-oriented protocol, you must first call the , , , or method, or will throw a . will ignore the `remoteEP` parameter and send data to the established in the , , , or method. @@ -4279,10 +4279,10 @@ This method populates the instance with data ga This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . The parameter cannot be null. - is less than . - - -or- - + is less than . + + -or- + is greater than . The is listening. The socket is not in the or families. @@ -4330,10 +4330,10 @@ This method populates the instance with data ga The parameter cannot be null. The parameter cannot be empty array. - is less than . - - -or- - + is less than . + + -or- + is greater than . The is listening. The socket is not in the or families. @@ -4380,10 +4380,10 @@ This method populates the instance with data ga This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . The parameter cannot be null. - is less than . - - -or- - + is less than . + + -or- + is greater than . The is listening. The socket is not in the or families. @@ -4432,10 +4432,10 @@ This method populates the instance with data ga This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . The parameter cannot be null. - is less than . - - -or- - + is less than . + + -or- + is greater than . The is listening. An error occurred when attempting to access the socket. @@ -4485,10 +4485,10 @@ This method populates the instance with data ga The parameter cannot be null. The parameter cannot be empty array. - is less than . - - -or- - + is less than . + + -or- + is greater than . The is listening. The socket is not in the or families. @@ -4632,10 +4632,10 @@ This method populates the instance with data ga This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . The parameter cannot be null. - is less than . - - -or- - + is less than . + + -or- + is greater than . The is listening. The socket is not in the or families. @@ -5325,7 +5325,7 @@ Duplication of the socket reference failed. The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > 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). @@ -5409,7 +5409,7 @@ Duplication of the socket reference failed. The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > 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). @@ -5492,7 +5492,7 @@ Duplication of the socket reference failed. The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > 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). @@ -6281,7 +6281,11 @@ Duplication of the socket reference failed. ]]> - Windows NT is required for this method. + Windows NT is required for this method. + +-or- + +.NET 8+ only: The socket is not connected to a remote host. .NET Framework, .NET Core, and .NET 5-6 only: The has been closed. is empty. @@ -12657,8 +12661,6 @@ This member outputs trace information when you enable network tracing in your ap > [!NOTE] > 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). - - ## Examples The following code example creates and connects a socket and then sends a file to the remote host. The file "test.txt" is located in the root directory of the local machine. From d857054935e4a081c298be3fcb087cde84a78579 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 7 Nov 2023 12:17:58 -0800 Subject: [PATCH 2/2] remove Windows NT exceptions --- xml/System.Net.Sockets/Socket.xml | 28 +++++++++------------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index 6e3d244eee9..2866fd76aaa 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -950,7 +950,6 @@ This method populates the instance with data ga ]]> The object has been closed. - Windows NT is required for this method. The accepting socket is not listening for connections. You must call and before calling . -or- @@ -1055,7 +1054,6 @@ This method populates the instance with data ga ]]> The object has been closed. - Windows NT is required for this method. The accepting socket is not listening for connections. You must call and before calling . -or- @@ -1158,7 +1156,6 @@ This method populates the instance with data ga ]]> The object has been closed. - Windows NT is required for this method. The accepting socket is not listening for connections. You must call and before calling . -or- @@ -5325,14 +5322,13 @@ Duplication of the socket reference failed. The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] -> 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). +> 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). ]]> - Windows NT is required for this method. .NET Framework, .NET Core, and .NET 5-6 only: The has been closed. is empty. @@ -5409,10 +5405,10 @@ Duplication of the socket reference failed. The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] -> 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). +> 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). ]]> @@ -5428,7 +5424,6 @@ Duplication of the socket reference failed. .NET Framework, .NET Core, and .NET 5-6 only: The has been closed. method was previously called. - Windows NT is required for this method. @@ -5492,14 +5487,13 @@ Duplication of the socket reference failed. The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] -> 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). +> 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). ]]> - Windows NT is required for this method. .NET Framework, .NET Core, and .NET 5-6 only: The has been closed. is empty. @@ -6274,18 +6268,14 @@ Duplication of the socket reference failed. If you are using a connectionless protocol, blocks until the datagram is sent. If you are using a connection-oriented protocol, blocks until the entire file is sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!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. > [!NOTE] -> 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). +> 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). ]]> - Windows NT is required for this method. - --or- - -.NET 8+ only: The socket is not connected to a remote host. + .NET 8+ only: The socket is not connected to a remote host. .NET Framework, .NET Core, and .NET 5-6 only: The has been closed. is empty.