using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Text;
+using static System.HexConverter;
namespace System.Net.Http.Headers
{
+ /// <summary>Represents a media type used in a Content-Type header as defined in the RFC 2616.</summary>
+ /// <remarks>
+ /// The <see cref="MediaTypeHeaderValue"/> class provides support for the media type used in a Content-Type header
+ /// as defined in RFC 2616 by the IETF. An example of a media-type would be "text/plain; charset=iso-8859-5".
+ /// </remarks>
public class MediaTypeHeaderValue : ICloneable
{
- private const string charSet = "charset";
+ /// <summary>The name of the charset header value.</summary>
+ private const string CharSetName = "charset";
+ /// <summary>The lazily-initialized parameters of the header value.</summary>
private UnvalidatedObjectCollection<NameValueHeaderValue>? _parameters;
+ /// <summary>The media type.</summary>
private string? _mediaType;
+ /// <summary>Gets or sets the character set.</summary>
+ /// <value>The character set.</value>
public string? CharSet
{
- get
- {
- NameValueHeaderValue? charSetParameter = NameValueHeaderValue.Find(_parameters, charSet);
- if (charSetParameter != null)
- {
- return charSetParameter.Value;
- }
- return null;
- }
+ get => NameValueHeaderValue.Find(_parameters, CharSetName)?.Value;
set
{
// We don't prevent a user from setting whitespace-only charsets. Like we can't prevent a user from
// setting a non-existing charset.
- NameValueHeaderValue? charSetParameter = NameValueHeaderValue.Find(_parameters, charSet);
+ NameValueHeaderValue? charSetParameter = NameValueHeaderValue.Find(_parameters, CharSetName);
if (string.IsNullOrEmpty(value))
{
// Remove charset parameter
}
else
{
- Parameters.Add(new NameValueHeaderValue(charSet, value));
+ Parameters.Add(new NameValueHeaderValue(CharSetName, value));
}
}
}
}
+ /// <summary>Gets the media-type header value parameters.</summary>
+ /// <value>The media-type header value parameters.</value>
public ICollection<NameValueHeaderValue> Parameters => _parameters ??= new UnvalidatedObjectCollection<NameValueHeaderValue>();
+ /// <summary>Gets or sets the media-type header value.</summary>
+ /// <value>The media-type header value.</value>
[DisallowNull]
public string? MediaType
{
}
}
+ /// <summary>Used by the parser to create a new instance of this type.</summary>
internal MediaTypeHeaderValue()
{
- // Used by the parser to create a new instance of this type.
}
+ /// <summary>Initializes a new instance of the <see cref="MediaTypeHeaderValue"/> class.</summary>
+ /// <param name="source">A <see cref="MediaTypeHeaderValue"/> object used to initialize the new instance.</param>
protected MediaTypeHeaderValue(MediaTypeHeaderValue source)
{
Debug.Assert(source != null);
_parameters = source._parameters.Clone();
}
+ /// <summary>Initializes a new instance of the <see cref="MediaTypeHeaderValue"/> class.</summary>
+ /// <param name="mediaType">The source represented as a string to initialize the new instance.</param>
public MediaTypeHeaderValue(string mediaType)
: this(mediaType, charSet: null)
{
}
+ /// <summary>Initializes a new instance of the <see cref="MediaTypeHeaderValue"/> class.</summary>
+ /// <param name="mediaType">The source represented as a string to initialize the new instance.</param>
+ /// <param name="charSet">The value to use for the character set.</param>
public MediaTypeHeaderValue(string mediaType, string? charSet)
{
CheckMediaTypeFormat(mediaType, nameof(mediaType));
}
}
+ /// <summary>Returns a string that represents the current <see cref="MediaTypeHeaderValue"/> object.</summary>
+ /// <returns>A string that represents the current object.</returns>
public override string ToString()
{
if (_parameters is null || _parameters.Count == 0)
return StringBuilderCache.GetStringAndRelease(sb);
}
- public override bool Equals([NotNullWhen(true)] object? obj)
- {
- MediaTypeHeaderValue? other = obj as MediaTypeHeaderValue;
-
- if (other == null)
- {
- return false;
- }
-
- return string.Equals(_mediaType, other._mediaType, StringComparison.OrdinalIgnoreCase) &&
- HeaderUtilities.AreEqualCollections(_parameters, other._parameters);
- }
-
+ /// <summary>Determines whether the specified <see cref="object"/> is equal to the current <see cref="MediaTypeHeaderValue"/> object.</summary>
+ /// <param name="obj">The object to compare with the current object.</param>
+ /// <returns><see langword="true"/> if the specified <see cref="object"/> is equal to the current object; otherwise, <see langword="false"/>.</returns>
+ public override bool Equals([NotNullWhen(true)] object? obj) =>
+ obj is MediaTypeHeaderValue other &&
+ string.Equals(_mediaType, other._mediaType, StringComparison.OrdinalIgnoreCase) &&
+ HeaderUtilities.AreEqualCollections(_parameters, other._parameters);
+
+ /// <summary>Serves as a hash function for an <see cref="MediaTypeHeaderValue"/> object.</summary>
+ /// <returns>A hash code for the current object.</returns>
+ /// <remarks>
+ /// A hash code is a numeric value that is used to identify an object during equality testing. It can also serve as an index for an object in a collection.
+ /// The GetHashCode method is suitable for use in hashing algorithms and data structures such as a hash table.
+ /// </remarks>
public override int GetHashCode()
{
// The media-type string is case-insensitive.
return StringComparer.OrdinalIgnoreCase.GetHashCode(_mediaType!) ^ NameValueHeaderValue.GetHashCode(_parameters);
}
+ /// <summary>Converts a string to an <see cref="MediaTypeHeaderValue"/> instance.</summary>
+ /// <param name="input">A string that represents media type header value information.</param>
+ /// <returns>A <see cref="MediaTypeHeaderValue"/> instance.</returns>
+ /// <exception cref="ArgumentNullException"><paramref name="input"/> is a <see langword="null"/> reference.</exception>
+ /// <exception cref="FormatException"><parmref name="input"/> is not valid media type header value information.</exception>
public static MediaTypeHeaderValue Parse(string? input)
{
int index = 0;
return (MediaTypeHeaderValue)MediaTypeHeaderParser.SingleValueParser.ParseValue(input, null, ref index);
}
+ /// <summary>Determines whether a string is valid <see cref="MediaTypeHeaderValue"/> information.</summary>
+ /// <param name="input">The string to validate.</param>
+ /// <param name="parsedValue">The <see cref="MediaTypeHeaderValue"/> version of the string.</param>
+ /// <returns><see langword="true"/> if input is valid <see cref="MediaTypeHeaderValue"/> information; otherwise, <see langword="false"/>.</returns>
public static bool TryParse([NotNullWhen(true)] string? input, [NotNullWhen(true)] out MediaTypeHeaderValue? parsedValue)
{
int index = 0;
namespace System.Net.Http
{
+ /// <summary>Provides HTTP content based on a string.</summary>
public class StringContent : ByteArrayContent
{
+ /// <summary>The media type to use when none is specified.</summary>
private const string DefaultMediaType = "text/plain";
+ /// <summary>Creates a new instance of the <see cref="StringContent"/> class.</summary>
+ /// <param name="content">The content used to initialize the <see cref="StringContent"/>.</param>
+ /// <remarks>The media type for the <see cref="StringContent"/> created defaults to text/plain.</remarks>
public StringContent(string content)
: this(content, DefaultStringEncoding, DefaultMediaType)
{
}
+ /// <summary>Creates a new instance of the <see cref="StringContent"/> class.</summary>
+ /// <param name="content">The content used to initialize the <see cref="StringContent"/>.</param>
+ /// <param name="mediaType">The media type to use for the content.</param>
public StringContent(string content, MediaTypeHeaderValue mediaType)
: this(content, DefaultStringEncoding, mediaType)
{
}
+ /// <summary>Creates a new instance of the <see cref="StringContent"/> class.</summary>
+ /// <param name="content">The content used to initialize the <see cref="StringContent"/>.</param>
+ /// <param name="encoding">The encoding to use for the content.</param>
+ /// <remarks>The media type for the <see cref="StringContent"/> created defaults to text/plain.</remarks>
public StringContent(string content, Encoding? encoding)
: this(content, encoding, DefaultMediaType)
{
}
+ /// <summary>Creates a new instance of the <see cref="StringContent"/> class.</summary>
+ /// <param name="content">The content used to initialize the <see cref="StringContent"/>.</param>
+ /// <param name="encoding">The encoding to use for the content.</param>
+ /// <param name="mediaType">The media type to use for the content.</param>
public StringContent(string content, Encoding? encoding, string mediaType)
: this(content, encoding, new MediaTypeHeaderValue(mediaType, (encoding ?? DefaultStringEncoding).WebName))
{
}
+ /// <summary>Creates a new instance of the <see cref="StringContent"/> class.</summary>
+ /// <param name="content">The content used to initialize the <see cref="StringContent"/>.</param>
+ /// <param name="encoding">The encoding to use for the content.</param>
+ /// <param name="mediaType">The media type to use for the content.</param>
public StringContent(string content, Encoding? encoding, MediaTypeHeaderValue mediaType)
: base(GetContentByteArray(content, encoding))
{
Headers.ContentType = mediaType;
}
- // A StringContent is essentially a ByteArrayContent. We serialize the string into a byte-array in the
- // constructor using encoding information provided by the caller (if any). When this content is sent, the
- // Content-Length can be retrieved easily (length of the array).
+ /// <summary>Serialize the string into a byte-array using encoding information provided by the caller (if any).</summary>
+ /// <param name="content">The content used to initialize the <see cref="StringContent"/>.</param>
+ /// <param name="encoding">The encoding to use for the content.</param>
+ /// <returns>The serialized byte array.</returns>
private static byte[] GetContentByteArray(string content, Encoding? encoding)
{
ArgumentNullException.ThrowIfNull(content);
- // In this case we treat 'null' strings different from string.Empty in order to be consistent with our
+ // In this case we treat 'null' strings differently from string.Empty in order to be consistent with our
// other *Content constructors: 'null' throws, empty values are allowed.
- encoding ??= HttpContent.DefaultStringEncoding;
-
- return encoding.GetBytes(content);
+ return (encoding ?? DefaultStringEncoding).GetBytes(content);
}
+ /// <summary>Serialize and write the byte array provided in the constructor to an HTTP content stream as an asynchronous operation.</summary>
+ /// <param name="stream">The target stream.</param>
+ /// <param name="context">Information about the transport, like channel binding token. This parameter may be <see langword="null" />.</param>
+ /// <param name="cancellationToken">The cancellation token to cancel the operation.</param>
+ /// <returns>The task object representing the asynchronous operation.</returns>
protected override Task SerializeToStreamAsync(Stream stream, TransportContext? context, CancellationToken cancellationToken) =>
// Only skip the original protected virtual SerializeToStreamAsync if this
// isn't a derived type that may have overridden the behavior.
PingCompleted?.Invoke(this, e);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="hostNameOrAddress">
+ /// A <see cref="string"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// The value specified for this parameter can be a host name or a string representation of an IP address.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="hostNameOrAddress"/> is <see langword="null"/> or is an empty string ("").</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(string hostNameOrAddress)
{
return Send(hostNameOrAddress, DefaultTimeout, DefaultSendBuffer);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="hostNameOrAddress">
+ /// A <see cref="string"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// The value specified for this parameter can be a host name or a string representation of an IP address.
+ /// </param>
+ /// <param name="timeout">
+ /// An <see cref="int"/> value that specifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="hostNameOrAddress"/> is <see langword="null"/> or is an empty string ("").</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than zero.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(string hostNameOrAddress, int timeout)
{
return Send(hostNameOrAddress, timeout, DefaultSendBuffer);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified <see cref="IPAddress"/>,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="address">
+ /// An <see cref="IPAddress"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="address"/> is <see langword="null"/>.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(IPAddress address)
{
return Send(address, DefaultTimeout, DefaultSendBuffer);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified <see cref="IPAddress"/>,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="address">
+ /// An <see cref="IPAddress"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// </param>
+ /// <param name="timeout">
+ /// An <see cref="int"/> value that specifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="address"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than zero.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(IPAddress address, int timeout)
{
return Send(address, timeout, DefaultSendBuffer);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="hostNameOrAddress">
+ /// A <see cref="string"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// The value specified for this parameter can be a host name or a string representation of an IP address.
+ /// </param>
+ /// <param name="timeout">
+ /// An <see cref="int"/> value that specifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <param name="buffer">
+ /// A <see cref="byte"/> array that contains data to be sent with the ICMP echo message and returned in the ICMP echo reply message.
+ /// The array cannot contain more than 65,500 bytes.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="hostNameOrAddress"/> is <see langword="null"/> or is an empty string ("").</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="buffer"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than zero.</exception>
+ /// <exception cref="ArgumentException">The <paramref name="buffer"/>'s size is greater than 65,500 bytes.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(string hostNameOrAddress, int timeout, byte[] buffer)
{
return Send(hostNameOrAddress, timeout, buffer, null);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified <see cref="IPAddress"/>,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="address">
+ /// An <see cref="IPAddress"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// </param>
+ /// <param name="timeout">
+ /// An <see cref="int"/> value that specifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <param name="buffer">
+ /// A <see cref="byte"/> array that contains data to be sent with the ICMP echo message and returned in the ICMP echo reply message.
+ /// The array cannot contain more than 65,500 bytes.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="address"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="buffer"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than zero.</exception>
+ /// <exception cref="ArgumentException">The <paramref name="buffer"/>'s size is greater than 65,500 bytes.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(IPAddress address, int timeout, byte[] buffer)
{
return Send(address, timeout, buffer, null);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="hostNameOrAddress">
+ /// A <see cref="string"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// The value specified for this parameter can be a host name or a string representation of an IP address.
+ /// </param>
+ /// <param name="timeout">
+ /// An <see cref="int"/> value that specifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <param name="buffer">
+ /// A <see cref="byte"/> array that contains data to be sent with the ICMP echo message and returned in the ICMP echo reply message.
+ /// The array cannot contain more than 65,500 bytes.
+ /// </param>
+ /// <param name="options">
+ /// A <see cref="PingOptions"/> object used to control fragmentation and Time-to-Live values for the ICMP echo message packet.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="hostNameOrAddress"/> is <see langword="null"/> or is an empty string ("").</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="buffer"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than zero.</exception>
+ /// <exception cref="ArgumentException">The <paramref name="buffer"/>'s size is greater than 65,500 bytes.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(string hostNameOrAddress, int timeout, byte[] buffer, PingOptions? options)
{
if (string.IsNullOrEmpty(hostNameOrAddress))
return GetAddressAndSend(hostNameOrAddress, timeout, buffer, options);
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified <see cref="IPAddress"/>,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="address">
+ /// An <see cref="IPAddress"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// </param>
+ /// <param name="timeout">
+ /// An <see cref="int"/> value that specifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <param name="buffer">
+ /// A <see cref="byte"/> array that contains data to be sent with the ICMP echo message and returned in the ICMP echo reply message.
+ /// The array cannot contain more than 65,500 bytes.
+ /// </param>
+ /// <param name="options">
+ /// A <see cref="PingOptions"/> object used to control fragmentation and Time-to-Live values for the ICMP echo message packet.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="address"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="buffer"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than zero.</exception>
+ /// <exception cref="ArgumentException">The <paramref name="buffer"/>'s size is greater than 65,500 bytes.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(IPAddress address, int timeout, byte[] buffer, PingOptions? options)
{
CheckArgs(address, timeout, buffer, options);
}
}
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the computer that has the specified <see cref="IPAddress"/>,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="address">
+ /// An <see cref="IPAddress"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// </param>
+ /// <param name="timeout">
+ /// A value that specifies the maximum amount of time (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <param name="buffer">
+ /// A <see cref="byte"/> array that contains data to be sent with the ICMP echo message and returned in the ICMP echo reply message.
+ /// The array cannot contain more than 65,500 bytes.
+ /// </param>
+ /// <param name="options">
+ /// A <see cref="PingOptions"/> object used to control fragmentation and Time-to-Live values for the ICMP echo message packet.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="address"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="buffer"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> represents a time less than zero milliseconds or greater than <see cref="int.MaxValue"/> milliseconds.</exception>
+ /// <exception cref="ArgumentException">The <paramref name="buffer"/>'s size is greater than 65,500 bytes.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(IPAddress address, TimeSpan timeout, byte[]? buffer = null, PingOptions? options = null) =>
Send(address, ToTimeoutMilliseconds(timeout), buffer ?? DefaultSendBuffer, options);
+ /// <summary>
+ /// Attempts to send an Internet Control Message Protocol (ICMP) echo message to the specified computer,
+ /// and receive a corresponding ICMP echo reply message from that computer.
+ /// </summary>
+ /// <param name="hostNameOrAddress">
+ /// A <see cref="string"/> that identifies the computer that is the destination for the ICMP echo message.
+ /// The value specified for this parameter can be a host name or a string representation of an IP address.
+ /// </param>
+ /// <param name="timeout">
+ /// A value that specifies the maximum amount of time (after sending the echo message) to wait for the ICMP echo reply message.
+ /// </param>
+ /// <param name="buffer">
+ /// A <see cref="byte"/> array that contains data to be sent with the ICMP echo message and returned in the ICMP echo reply message.
+ /// The array cannot contain more than 65,500 bytes.
+ /// </param>
+ /// <param name="options">
+ /// A <see cref="PingOptions"/> object used to control fragmentation and Time-to-Live values for the ICMP echo message packet.
+ /// </param>
+ /// <returns>
+ /// A <see cref="PingReply"/> object that provides information about the ICMP echo reply message, if one was received,
+ /// or provides the reason for the failure, if no message was received.
+ /// </returns>
+ /// <exception cref="ArgumentNullException"><paramref name="hostNameOrAddress"/> is <see langword="null"/> or is an empty string ("").</exception>
+ /// <exception cref="ArgumentNullException"><paramref name="buffer"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> represents a time less than zero milliseconds or greater than <see cref="int.MaxValue"/> milliseconds.</exception>
+ /// <exception cref="ArgumentException">The <paramref name="buffer"/>'s size is greater than 65,500 bytes.</exception>
+ /// <exception cref="InvalidOperationException">A call to SendAsync is in progress.</exception>
+ /// <exception cref="PingException">An exception was thrown while sending or receiving the ICMP messages. See the inner exception for the exact exception that was thrown.</exception>
+ /// <exception cref="ObjectDisposedException">This object has been disposed.</exception>
public PingReply Send(string hostNameOrAddress, TimeSpan timeout, byte[]? buffer = null,
PingOptions? options = null) => Send(hostNameOrAddress, ToTimeoutMilliseconds(timeout), buffer ?? DefaultSendBuffer, options);
// The .NET Foundation licenses this file to you under the MIT license.
using System.IO;
+using System.Runtime.InteropServices;
using System.Threading;
using System.Threading.Tasks;
private int _closeTimeout = Socket.DefaultCloseTimeout; // -1 = respect linger options
+ /// <summary>Closes the <see cref="NetworkStream"/> after waiting the specified time to allow data to be sent.</summary>
+ /// <param name="timeout">The number of milliseconds to wait to send any remaining data before closing.</param>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than -1.</exception>
+ /// <remarks>
+ /// The Close method frees both unmanaged and managed resources associated with the <see cref="NetworkStream"/>.
+ /// If the <see cref="NetworkStream"/> owns the underlying <see cref="Socket"/>, it is closed as well.
+ /// If a <see cref="NetworkStream"/> was associated with a <see cref="TcpClient"/>, the <see cref="Close(int)"/> method
+ /// will close the TCP connection, but not dispose of the associated <see cref="TcpClient"/>.
+ /// </remarks>
public void Close(int timeout)
{
if (timeout < -1)
Dispose();
}
+ /// <summary>Closes the <see cref="NetworkStream"/> after waiting the specified time to allow data to be sent.</summary>
+ /// <param name="timeout">The amount of time to wait to send any remaining data before closing.</param>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than -1 milliseconds or greater than <see cref="int.MaxValue"/> milliseconds.</exception>
+ /// <remarks>
+ /// The Close method frees both unmanaged and managed resources associated with the <see cref="NetworkStream"/>.
+ /// If the <see cref="NetworkStream"/> owns the underlying <see cref="Socket"/>, it is closed as well.
+ /// If a <see cref="NetworkStream"/> was associated with a <see cref="TcpClient"/>, the <see cref="Close(int)"/> method
+ /// will close the TCP connection, but not dispose of the associated <see cref="TcpClient"/>.
+ /// </remarks>
public void Close(TimeSpan timeout) => Close(ToTimeoutMilliseconds(timeout));
private static int ToTimeoutMilliseconds(TimeSpan timeout)
}
}
- public override bool IsInvalid
- {
- get
- {
- return IsClosed || base.IsInvalid;
- }
- }
+ /// <summary>Gets a value indicating whether the handle value is invalid.</summary>
+ /// <value><see langword="true"/> if the handle value is invalid; otherwise, <see langword="false"/>.</value>
+ public override bool IsInvalid => IsClosed || base.IsInvalid;
protected override bool ReleaseHandle()
{
}
}
- // Determines the status of the socket.
+ /// <summary>Determines the status of the <see cref="Socket"/>.</summary>
+ /// <param name="microSeconds">The time to wait for a response, in microseconds.</param>
+ /// <param name="mode">One of the <see cref="SelectMode"/> values.</param>
+ /// <returns>
+ /// The status of the <see cref="Socket"/> based on the polling mode value passed in the <paramref name="mode"/> parameter.
+ /// For <see cref="SelectMode.SelectRead"/>, it returns <see langword="true"/> if <see cref="M:Listen"/> has been called and
+ /// a connection is pending, if data is available for reading, or if the connection has been closed, reset, or terminated.
+ /// For <see cref="SelectMode.SelectWrite"/>, it returns <see langword="true"/> if processing a <see cref="M:Connect"/> and
+ /// the connection has succeeded or if data can be sent.
+ /// For <see cref="SelectMode.SelectError"/>, it returns <see langword="true"/> if processing a <see cref="M:Connect"/> that
+ /// does not block and the connection has failed, or if OutOfBandInline is not set and out-of-band data is available.
+ /// Otherwise, it returns <see langword="false"/>.
+ /// </returns>
+ /// <exception cref="SocketException">An error occurred when attempting to access the socket.</exception>
+ /// <exception cref="ObjectDisposedException">The <see cref="Socket"/> has been closed.</exception>
public bool Poll(int microSeconds, SelectMode mode)
{
ThrowIfDisposed();
return status;
}
+ /// <summary>Determines the status of the <see cref="Socket"/>.</summary>
+ /// <param name="timeout">The time to wait for a response.</param>
+ /// <param name="mode">One of the <see cref="SelectMode"/> values.</param>
+ /// <returns>
+ /// The status of the <see cref="Socket"/> based on the polling mode value passed in the <paramref name="mode"/> parameter.
+ /// For <see cref="SelectMode.SelectRead"/>, it returns <see langword="true"/> if <see cref="M:Listen"/> has been called and
+ /// a connection is pending, if data is available for reading, or if the connection has been closed, reset, or terminated.
+ /// For <see cref="SelectMode.SelectWrite"/>, it returns <see langword="true"/> if processing a <see cref="M:Connect"/> and
+ /// the connection has succeeded or if data can be sent.
+ /// For <see cref="SelectMode.SelectError"/>, it returns <see langword="true"/> if processing a <see cref="M:Connect"/> that
+ /// does not block and the connection has failed, or if OutOfBandInline is not set and out-of-band data is available.
+ /// Otherwise, it returns <see langword="false"/>.
+ /// </returns>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than -1 milliseconds or greater than <see cref="int.MaxValue"/> milliseconds.</exception>
+ /// <exception cref="SocketException">An error occurred when attempting to access the socket.</exception>
+ /// <exception cref="ObjectDisposedException">The <see cref="Socket"/> has been closed.</exception>
public bool Poll(TimeSpan timeout, SelectMode mode) =>
Poll(ToTimeoutMicroseconds(timeout), mode);
- // Determines the status of a socket.
+ /// <summary>Determines the status of one or more sockets.</summary>
+ /// <param name="checkRead">An <see cref="IList"/> of <see cref="Socket"/> instances to check for readability.</param>
+ /// <param name="checkWrite">An <see cref="IList"/> of <see cref="Socket"/> instances to check for writability.</param>
+ /// <param name="checkError">An <see cref="IList"/> of <see cref="Socket"/> instances to check for errors.</param>
+ /// <param name="microSeconds">The timeout value, in microseconds. A -1 value indicates an infinite timeout.</param>
+ /// <exception cref="ArgumentNullException">The <paramref name="checkRead"/>, <paramref name="checkWrite"/>, or <paramref name="checkError"/> parameter is <see langword="null"/> or empty.</exception>
+ /// <exception cref="ArgumentOutOfRangeException">The <paramref name="checkRead"/>, <paramref name="checkWrite"/>, or <paramref name="checkError"/> parameter contains too many sockets.</exception>
+ /// <exception cref="SocketException">An error occurred when attempting to access the socket.</exception>
+ /// <exception cref="ObjectDisposedException">One or more sockets was disposed.</exception>
public static void Select(IList? checkRead, IList? checkWrite, IList? checkError, int microSeconds)
{
if ((checkRead == null || checkRead.Count == 0) &&
}
}
- public static void Select(IList? checkRead, IList? checkWrite, IList? checkError, TimeSpan timeout) => Select(checkRead, checkWrite, checkError, ToTimeoutMicroseconds(timeout));
+ /// <summary>Determines the status of one or more sockets.</summary>
+ /// <param name="checkRead">An <see cref="IList"/> of <see cref="Socket"/> instances to check for readability.</param>
+ /// <param name="checkWrite">An <see cref="IList"/> of <see cref="Socket"/> instances to check for writability.</param>
+ /// <param name="checkError">An <see cref="IList"/> of <see cref="Socket"/> instances to check for errors.</param>
+ /// <param name="timeout">The timeout value. A value equal to -1 microseconds indicates an infinite timeout.</param>
+ /// <exception cref="ArgumentNullException">The <paramref name="checkRead"/>, <paramref name="checkWrite"/>, or <paramref name="checkError"/> parameter is <see langword="null"/> or empty.</exception>
+ /// <exception cref="ArgumentOutOfRangeException">The <paramref name="checkRead"/>, <paramref name="checkWrite"/>, or <paramref name="checkError"/> parameter contains too many sockets.</exception>
+ /// <exception cref="ArgumentOutOfRangeException">The <paramref name="timeout"/> was less than -1 microseconds or greater than <see cref="int.MaxValue"/> microseconds</exception>
+ /// <exception cref="SocketException">An error occurred when attempting to access the socket.</exception>
+ /// <exception cref="ObjectDisposedException">One or more sockets was disposed.</exception>
+ public static void Select(IList? checkRead, IList? checkWrite, IList? checkError, TimeSpan timeout) =>
+ Select(checkRead, checkWrite, checkError, ToTimeoutMicroseconds(timeout));
private static int ToTimeoutMicroseconds(TimeSpan timeout)
{
// Tracks the file Socket should delete on Dispose.
internal string? BoundFileName { get; }
+ /// <summary>Initializes a new instance of the <see cref="UnixDomainSocketEndPoint"/> with the file path to connect a unix domain socket over.</summary>
+ /// <param name="path">The path to connect a unix domain socket over.</param>
+ /// <exception cref="ArgumentNullException"><paramref name="path"/> is <see langword="null"/>.</exception>
+ /// <exception cref="ArgumentOutOfRangeException"><paramref name="path"/> is of an invalid length for use with domain sockets on this platform. The length must be between 1 and the allowed native path length.</exception>
+ /// <exception cref="PlatformNotSupportedException">The current OS does not support Unix Domain Sockets.</exception>
public UnixDomainSocketEndPoint(string path)
: this(path, null)
{ }
}
}
+ /// <summary>Serializes endpoint information into a <see cref="SocketAddress"/> instance.</summary>
+ /// <returns>A <see cref="SocketAddress"/> instance that contains the endpoint information.</returns>
public override SocketAddress Serialize()
{
SocketAddress result = CreateSocketAddressForSerialize();
return result;
}
+ /// <summary>Creates an <see cref="EndPoint"/> instance from a <see cref="SocketAddress"/> instance.</summary>
+ /// <param name="socketAddress">The socket address that serves as the endpoint for a connection.</param>
+ /// <returns>A new <see cref="EndPoint"/> instance that is initialized from the specified <see cref="SocketAddress"/> instance.</returns>
public override EndPoint Create(SocketAddress socketAddress) => new UnixDomainSocketEndPoint(socketAddress);
+ /// <summary>Gets the address family to which the endpoint belongs.</summary>
+ /// <value>One of the <see cref="AddressFamily"/> values.</value>
public override AddressFamily AddressFamily => EndPointAddressFamily;
+ /// <summary>Gets the path represented by this <see cref="UnixDomainSocketEndPoint"/> instance.</summary>
+ /// <returns>The path represented by this <see cref="UnixDomainSocketEndPoint"/> instance.</returns>
public override string ToString()
{
bool isAbstract = IsAbstract(_path);
}
}
+ /// <summary>Determines whether the specified <see cref="object"/> is equal to the current <see cref="UnixDomainSocketEndPoint"/>.</summary>
+ /// <param name="obj">The <see cref="object"/> to compare with the current <see cref="UnixDomainSocketEndPoint"/>.</param>
+ /// <returns><see langword="true"/> if the specified <see cref="object"/> is equal to the current <see cref="UnixDomainSocketEndPoint"/>; otherwise, <see langword="false"/>.</returns>
public override bool Equals([NotNullWhen(true)] object? obj)
=> obj is UnixDomainSocketEndPoint ep && _path == ep._path;
+ /// <summary>Returns a hash value for a <see cref="UnixDomainSocketEndPoint"/> instance.</summary>
+ /// <returns>An integer hash value.</returns>
public override int GetHashCode() => _path.GetHashCode();
internal UnixDomainSocketEndPoint CreateBoundEndPoint()
projects / platform / upstream / dotnet / runtime.git / commitdiff