using System;
using System.Data;
using System.Net.Sockets;
using System.Runtime.InteropServices;
using System.Text;
using Vanara.Extensions;
using Vanara.InteropServices;
namespace Vanara.PInvoke
{
/// Functions, structures and constants from ws2_32.h.
public static partial class Ws2_32
{
/// The __WSAFDIsSet function specifies whether a socket is included in a set of socket descriptors.
/// TBD
///
/// Pointer to an fd_set structure containing the set of socket descriptors. The __WSAFDIsSet function determines whether the
/// socket specified in the fd parameter is a member of that set.
///
/// None
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-__wsafdisset int __WSAFDIsSet( SOCKET , fd_set * );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "ca420136-0b3b-45a1-85ce-83ab6ba1a70a")]
public static extern WSRESULT __WSAFDIsSet(SOCKET arg1, in fd_set arg2);
///
/// The WSAAccept function conditionally accepts a connection based on the return value of a condition function, provides
/// quality of service flow specifications, and allows the transfer of connection data.
///
/// A descriptor that identifies a socket that is listening for connections after a call to the listen function.
///
/// An optional pointer to an sockaddr structure that receives the address of the connecting entity, as known to the communications
/// layer. The exact format of the addr parameter is determined by the address family established when the socket was created.
///
///
/// An optional pointer to an integer that contains the length of the sockaddr structure pointed to by the addr parameter, in bytes.
///
///
/// The address of an optional, application-specified condition function that will make an accept/reject decision based on the
/// caller information passed in as parameters, and optionally create or join a socket group by assigning an appropriate value to
/// the result parameter g of this function. If this parameter is NULL, then no condition function is called.
///
///
/// Callback data passed back to the application-specified condition function as the value of the dwCallbackData parameter passed to
/// the condition function. This parameter is only applicable if the lpfnCondition parameter is not NULL. This parameter is
/// not interpreted by Windows Sockets.
///
///
///
/// If no error occurs, WSAAccept returns a value of type SOCKET that is a descriptor for the accepted socket. Otherwise, a
/// value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.
///
///
/// The integer referred to by addrlen initially contains the amount of space pointed to by addr. On return it will contain the
/// actual length in bytes of the address returned.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEACCES
///
/// An attempt was made to access a socket in a way forbidden by its access permissions. This error is returned if the connection
/// request that was offered has timed out or been withdrawn.
///
///
/// -
/// WSAECONNREFUSED
///
/// No connection could be made because the target machine actively refused it. This error is returned if the connection request was
/// forcefully rejected as indicated in the return value of the condition function (CF_REJECT).
///
///
/// -
/// WSAECONNRESET
///
/// An existing connection was forcibly closed by the remote host. This error is returned of an incoming connection was indicated,
/// but was subsequently terminated by the remote peer prior to accepting the call.
///
///
/// -
/// WSAEFAULT
///
/// The system detected an invalid pointer address in attempting to use a pointer argument in a call. This error is returned of the
/// addrlen parameter is too small or the addr or lpfnCondition is not part of the user address space.
///
///
/// -
/// WSAEINTR
///
/// A blocking operation was interrupted by a call to WSACancelBlockingCall. This error is returned if a blocking Windows Sockets
/// 1.1 call was canceled through WSACancelBlockingCall.
///
///
/// -
/// WSAEINPROGRESS
/// A blocking operation is currently executing. This error is returned if a blocking Windows Sockets 1.1 call is in progress.
///
/// -
/// WSAEINVAL
///
/// An invalid argument was supplied. This error is returned if listen was not invoked prior to WSAAccept, the return value of the
/// condition function is not a valid one, or any case where the specified socket is in an invalid state.
///
///
/// -
/// WSAEMFILE
///
/// Too many open sockets. This error is returned if the queue is nonempty upon entry to WSAAccept and there are no socket
/// descriptors available.
///
///
/// -
/// WSAENETDOWN
/// A socket operation encountered a dead network. This error is returned if the network subsystem has failed.
///
/// -
/// WSAENOBUFS
///
/// An operation on a socket could not be performed because the system lacked sufficient buffer space or because a queue was full.
/// This error is returned if no buffer space is available.
///
///
/// -
/// WSAENOTSOCK
///
/// An operation was attempted on something that is not a socket. This error is returned if the socket descriptor passed in the s
/// parameter is not a socket.
///
///
/// -
/// WSAEOPNOTSUPP
///
/// The protocol family has not been configured into the system or no implementation for it exists. This error is returned if the
/// referenced socket is not a type that supports connection-oriented service.
///
///
/// -
/// WSAEWOULDBLOCK
///
/// A non-blocking socket operation could not be completed immediately. This error is returned if the socket is marked as
/// nonblocking and no connections are present to be accepted.
///
///
/// -
/// WSANOTINITIALISED
///
/// Either the application has not called WSAStartup, or WSAStartup failed. This error is returned of a successful call to the
/// WSAStartup function dit not occur before using this function.
///
///
/// -
/// WSATRY_AGAIN
///
/// This is usually a temporary error during hostname resolution and means that the local server did not receive a response from an
/// authoritative server. This error is returned if the acceptance of the connection request was deferred as indicated in the return
/// value of the condition function (CF_DEFER).
///
///
///
///
///
///
/// The WSAAccept function extracts the first connection on the queue of pending connections on socket s, and checks it
/// against the condition function, provided the condition function is specified (that is, not NULL). If the condition
/// function returns CF_ACCEPT, WSAAccept creates a new socket. The newly created socket has the same properties as socket s
/// including asynchronous events registered with WSAAsyncSelect or with WSAEventSelect. If the condition function returns
/// CF_REJECT, WSAAccept rejects the connection request. The condition function runs in the same thread as this function
/// does, and should return as soon as possible. If the decision cannot be made immediately, the condition function should return
/// CF_DEFER to indicate that no decision has been made, and no action about this connection request should be taken by the service
/// provider. When the application is ready to take action on the connection request, it will invoke WSAAccept again and
/// return either CF_ACCEPT or CF_REJECT as a return value from the condition function.
///
///
/// A socket in default mode (blocking) will block until a connection is present when an application calls WSAAccept and no
/// connections are pending on the queue.
///
///
/// A socket in nonblocking mode (blocking) fails with the error WSAEWOULDBLOCK when an application calls WSAAccept and no
/// connections are pending on the queue. After WSAAccept succeeds and returns a new socket handle, the accepted socket
/// cannot be used to accept any more connections. The original socket remains open and listens for new connection requests.
///
///
/// The addr parameter is a result parameter that is filled in with the address of the connecting entity, as known to the
/// communications layer. The exact format of the addr parameter is determined by the address family in which the communication is
/// occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr. On
/// return, it will contain the actual length (in bytes) of the address returned. This call is used with connection-oriented socket
/// types such as SOCK_STREAM. If addr and/or addrlen are equal to NULL, then no information about the remote address of the
/// accepted socket is returned. Otherwise, these two parameters will be filled in if the connection is successfully accepted.
///
/// A prototype of the condition function is defined in the Winsock2.h header file as the LPCONDITIONPROC as follows:
///
/// The ConditionFunc is a placeholder for the application-specified callback function. The actual condition function must
/// reside in a DLL or application module. It is exported in the module definition file.
///
///
/// The lpCallerId parameter points to a WSABUF structure that contains the address of the connecting entity, where its len
/// parameter is the length of the buffer in bytes, and its buf parameter is a pointer to the buffer. The lpCallerData is a value
/// parameter that contains any user data. The information in these parameters is sent along with the connection request. If no
/// caller identification or caller data is available, the corresponding parameters will be NULL. Many network protocols do
/// not support connect-time caller data. Most conventional network protocols can be expected to support caller identifier
/// information at connection-request time. The buf portion of the WSABUF pointed to by lpCallerId points to a sockaddr. The
/// sockaddr structure is interpreted according to its address family (typically by casting the sockaddr to some type
/// specific to the address family).
///
///
/// The lpSQOS parameter references the FLOWSPEC structures for socket s specified by the caller, one for each direction, followed
/// by any additional provider-specific parameters. The sending or receiving flow specification values will be ignored as
/// appropriate for any unidirectional sockets. A NULL value indicates that there is no caller-supplied quality of service
/// and that no negotiation is possible. A non- NULL lpSQOS pointer indicates that a quality of service negotiation is to
/// occur or that the provider is prepared to accept the quality of service request without negotiation.
///
///
/// The lpGQOS parameter is reserved, and should be NULL. (reserved for future use with socket groups) references the
/// FLOWSPEC structure for the socket group the caller is to create, one for each direction, followed by any additional
/// provider-specific parameters. A NULL value for lpGQOS indicates no caller-specified group quality of service. Quality of
/// service information can be returned if negotiation is to occur.
///
///
/// The lpCalleeId is a parameter that contains the local address of the connected entity. The buf portion of the WSABUF pointed to
/// by lpCalleeId points to a sockaddr structure. The sockaddr structure is interpreted according to its address family
/// (typically by casting the sockaddr to some type specific to the address family such as struct sockaddr_in).
///
///
/// The lpCalleeData is a result parameter used by the condition function to supply user data back to the connecting entity. The
/// lpCalleeData->len initially contains the length of the buffer allocated by the service provider and pointed to by
/// lpCalleeData->buf. A value of zero means passing user data back to the caller is not supported. The condition function should
/// copy up to lpCalleeData->len bytes of data into lpCalleeData->buf, and then update lpCalleeData->len to indicate the
/// actual number of bytes transferred. If no user data is to be passed back to the caller, the condition function should set
/// lpCalleeData->len to zero. The format of all address and user data is specific to the address family to which the socket belongs.
///
/// The g parameter is assigned within the condition function to indicate any of the following actions:
///
/// -
///
/// If g is an existing socket group identifier, add s to this group, provided all the requirements set by this group are met.
///
///
/// -
/// If g = SG_UNCONSTRAINED_GROUP, create an unconstrained socket group and have s as the first member.
///
/// -
/// If g = SG_CONSTRAINED_GROUP, create a constrained socket group and have s as the first member.
///
/// -
/// If g = zero, no group operation is performed.
///
///
///
/// For unconstrained groups, any set of sockets can be grouped together as long as they are supported by a single service provider.
/// A constrained socket group can consist only of connection-oriented sockets, and requires that connections on all grouped sockets
/// be to the same address on the same host. For newly created socket groups, the new group identifier can be retrieved by using
/// getsockopt function with level parameter set to SOL_SOCKET and the optname parameter set to SO_GROUP_ID. A socket group
/// and its associated socket group ID remain valid until the last socket belonging to this socket group is closed. Socket group IDs
/// are unique across all processes for a given service provider. A socket group and its associated identifier remain valid until
/// the last socket belonging to this socket group is closed. Socket group identifiers are unique across all processes for a given
/// service provider. For more information on socket groups, see the Remarks for the WSASocket functions.
///
///
/// The dwCallbackData parameter value passed to the condition function is the value passed as the dwCallbackData parameter in the
/// original WSAAccept call. This value is interpreted only by the Windows Socket version 2 client. This allows a client to
/// pass some context information from the WSAAccept call site through to the condition function. This also provides the
/// condition function with any additional information required to determine whether to accept the connection or not. A typical
/// usage is to pass a (suitably cast) pointer to a data structure containing references to application-defined objects with which
/// this socket is associated.
///
///
/// Note To protect use of the WSAAccept function from SYN attacks, applications must perform full TCP handshakes
/// (SYN-SYNACK-ACK) before reporting the connection request. Protecting against SYN attacks in this manner results in the
/// SO_CONDITIONAL_ACCEPT socket option becoming inoperative; the conditional function is still called, and the WSAAccept
/// function operates properly, but server applications that rely on clients being unable to perform the handshake will not operate properly.
///
///
/// Note When issuing a blocking Winsock call such as WSAAccept, Winsock may need to wait for a network event before
/// the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous
/// procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an
/// ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
///
/// Example Code
/// The following example demonstrates the use of the WSAAccept function.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-wsaaccept SOCKET WSAAPI WSAAccept( SOCKET s, sockaddr
// *addr, LPINT addrlen, LPCONDITIONPROC lpfnCondition, DWORD_PTR dwCallbackData );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "f385f63f-49b2-4eb7-8717-ad4cca1a2252")]
public static extern SOCKET WSAAccept(SOCKET s, SOCKADDR addr, ref int addrlen, [In, Out, Optional] ConditionFunc lpfnCondition, [In, Out, Optional] IntPtr dwCallbackData);
///
///
/// The WSAAddressToString function converts all components of a sockaddr structure into a human-readable string
/// representation of the address.
///
///
/// This is intended to be used mainly for display purposes. If the caller requires that the translation to be performed by a
/// particular provider, it should supply the corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
///
///
/// A pointer to the sockaddr structure to translate into a string.
///
/// The length, in bytes, of the address in the sockaddr structure pointed to by the lpsaAddress parameter. The dwAddressLength
/// parameter may vary in size with different protocols.
///
///
/// A pointer to the WSAPROTOCOL_INFO structure for a particular provider. If this is parameter is NULL, the call is routed
/// to the provider of the first protocol supporting the address family indicated in the lpsaAddress parameter.
///
/// A pointer to the buffer that receives the human-readable address string.
///
/// On input, this parameter specifies the length of the buffer pointed to by the lpszAddressString parameter. The length is
/// represented in bytes for ANSI strings, and in WCHARs for Unicode strings. On output, this parameter returns the length of the
/// string including the NULL terminator actually copied into the buffer pointed to by the lpszAddressString parameter. If
/// the specified buffer is not large enough, the function fails with a specific error of WSAEFAULT and this parameter is updated
/// with the required size.
///
///
///
/// If no error occurs, WSAAddressToString returns a value of zero. Otherwise, the value SOCKET_ERROR is returned, and a
/// specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEFAULT
///
/// The specified lpcsAddress, lpProtocolInfo, and lpszAddressString parameters point to memory that is not all in the address space
/// of the process, or the buffer pointed to by the lpszAddressString parameter is too small. Pass in a larger buffer.
///
///
/// -
/// WSAEINVAL
///
/// An invalid parameter was passed. This error is returned if the lpsaAddress, dwAddressLength, or lpdwAddressStringLength
/// parameter are NULL. This error is also returned if the specified address is not a valid socket address, or no transport provider
/// supports the indicated address family.
///
///
/// -
/// WSAENOBUFS
/// No buffer space is available.
///
/// -
/// WSANOTINITIALISED
///
/// The Winsock 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
///
///
///
///
/// The WSAAddressToString function provides a protocol-independent address-to-string translation. The
/// WSAAddressToString function takes a socket address structure pointed to by the lpsaAddress parameter and returns a
/// pointer to NULL-terminated string that represents the socket address in the lpszAddressString parameter. While the
/// inet_ntoa function works only with IPv4 addresses, the WSAAddressToString function works with any socket address
/// supported by a Winsock provider on the local computer including IPv6 addresses.
///
///
/// If the lpsaAddress parameter points to an IPv4 socket address (the address family is AF_INET), then the address string
/// returned in the buffer pointed to by the lpszAddressString parameter is in dotted-decimal notation as in "192.168.16.0", an
/// example of an IPv4 address in dotted-decimal notation.
///
///
/// If the lpsaAddress parameter points to an IPv6 socket address (the address family is AF_INET6), then the address string
/// returned in the buffer pointed to by the lpszAddressString parameter is in Internet standard format. The basic string
/// representation consists of 8 hexadecimal numbers separated by colons. A string of consecutive zero numbers is replaced with a
/// double-colon. There can only be one double-colon in the string representation of the IPv6 address.
///
///
/// If the length of the buffer pointed to by the lpszAddressString parameter is not large enough to receive the string
/// representation of the socket address, WSAAddressToString returns WSAEFAULT.
///
///
/// Support for IPv6 addresses using the WSAAddressToString function was added on Windows XP with Service Pack 1 (SP1)and
/// later. IPv6 must also be installed on the local computer for the WSAAddressToString function to support IPv6 addresses.
///
///
/// Windows Phone 8: The WSAAddressToStringW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSAAddressToStringW function is supported for Windows Store
/// apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-wsaaddresstostringa INT WSAAPI WSAAddressToStringA(
// LPSOCKADDR lpsaAddress, DWORD dwAddressLength, LPWSAPROTOCOL_INFOA lpProtocolInfo, LPSTR lpszAddressString, LPDWORD
// lpdwAddressStringLength );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "d72e55e6-79a9-4386-9e1a-24a322f13426")]
public static extern WSRESULT WSAAddressToString([In] SOCKADDR lpsaAddress, uint dwAddressLength, in WSAPROTOCOL_INFO lpProtocolInfo, StringBuilder lpszAddressString, ref uint lpdwAddressStringLength);
///
///
/// The WSAAddressToString function converts all components of a sockaddr structure into a human-readable string
/// representation of the address.
///
///
/// This is intended to be used mainly for display purposes. If the caller requires that the translation to be performed by a
/// particular provider, it should supply the corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
///
///
/// A pointer to the sockaddr structure to translate into a string.
///
/// A pointer to the WSAPROTOCOL_INFO structure for a particular provider. If this is parameter is NULL, the call is routed
/// to the provider of the first protocol supporting the address family indicated in the lpsaAddress parameter.
///
/// The human-readable address string.
///
///
/// The WSAAddressToString function provides a protocol-independent address-to-string translation. The
/// WSAAddressToString function takes a socket address structure pointed to by the lpsaAddress parameter and returns a
/// pointer to NULL-terminated string that represents the socket address in the lpszAddressString parameter. While the
/// inet_ntoa function works only with IPv4 addresses, the WSAAddressToString function works with any socket address
/// supported by a Winsock provider on the local computer including IPv6 addresses.
///
///
/// If the lpsaAddress parameter points to an IPv4 socket address (the address family is AF_INET), then the address string
/// returned in the buffer pointed to by the lpszAddressString parameter is in dotted-decimal notation as in "192.168.16.0", an
/// example of an IPv4 address in dotted-decimal notation.
///
///
/// If the lpsaAddress parameter points to an IPv6 socket address (the address family is AF_INET6), then the address string
/// returned in the buffer pointed to by the lpszAddressString parameter is in Internet standard format. The basic string
/// representation consists of 8 hexadecimal numbers separated by colons. A string of consecutive zero numbers is replaced with a
/// double-colon. There can only be one double-colon in the string representation of the IPv6 address.
///
///
/// Support for IPv6 addresses using the WSAAddressToString function was added on Windows XP with Service Pack 1 (SP1)and
/// later. IPv6 must also be installed on the local computer for the WSAAddressToString function to support IPv6 addresses.
///
///
/// Windows Phone 8: The WSAAddressToStringW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSAAddressToStringW function is supported for Windows Store
/// apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-wsaaddresstostringa INT WSAAPI WSAAddressToStringA(
// LPSOCKADDR lpsaAddress, DWORD dwAddressLength, LPWSAPROTOCOL_INFOA lpProtocolInfo, LPSTR lpszAddressString, LPDWORD
// lpdwAddressStringLength );
[PInvokeData("winsock2.h", MSDNShortId = "d72e55e6-79a9-4386-9e1a-24a322f13426")]
public static string WSAAddressToString([In] SOCKADDR lpsaAddress, [In, Optional] WSAPROTOCOL_INFO? lpProtocolInfo)
{
using var pc = lpProtocolInfo.HasValue ? new SafeCoTaskMemStruct(lpProtocolInfo.Value) : SafeCoTaskMemStruct.Null;
var sz = 1024U;
var err = WSAAddressToString(lpsaAddress, (uint)lpsaAddress.Size, pc, null, ref sz);
if (err == WSRESULT.WSAEFAULT && sz > 0)
{
StringBuilder sb = new((int)sz);
err = WSAAddressToString(lpsaAddress, (uint)lpsaAddress.Size, pc, sb, ref sz);
if (err == 0) return sb.ToString();
}
throw err.GetException();
}
///
///
/// The WSAAddressToString function converts all components of a sockaddr structure into a human-readable string
/// representation of the address.
///
///
/// This is intended to be used mainly for display purposes. If the caller requires that the translation to be performed by a
/// particular provider, it should supply the corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
///
///
/// A pointer to the sockaddr structure to translate into a string.
///
/// The length, in bytes, of the address in the sockaddr structure pointed to by the lpsaAddress parameter. The dwAddressLength
/// parameter may vary in size with different protocols.
///
///
/// A pointer to the WSAPROTOCOL_INFO structure for a particular provider. If this is parameter is NULL, the call is routed
/// to the provider of the first protocol supporting the address family indicated in the lpsaAddress parameter.
///
/// A pointer to the buffer that receives the human-readable address string.
///
/// On input, this parameter specifies the length of the buffer pointed to by the lpszAddressString parameter. The length is
/// represented in bytes for ANSI strings, and in WCHARs for Unicode strings. On output, this parameter returns the length of the
/// string including the NULL terminator actually copied into the buffer pointed to by the lpszAddressString parameter. If
/// the specified buffer is not large enough, the function fails with a specific error of WSAEFAULT and this parameter is updated
/// with the required size.
///
///
///
/// If no error occurs, WSAAddressToString returns a value of zero. Otherwise, the value SOCKET_ERROR is returned, and a
/// specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEFAULT
///
/// The specified lpcsAddress, lpProtocolInfo, and lpszAddressString parameters point to memory that is not all in the address space
/// of the process, or the buffer pointed to by the lpszAddressString parameter is too small. Pass in a larger buffer.
///
///
/// -
/// WSAEINVAL
///
/// An invalid parameter was passed. This error is returned if the lpsaAddress, dwAddressLength, or lpdwAddressStringLength
/// parameter are NULL. This error is also returned if the specified address is not a valid socket address, or no transport provider
/// supports the indicated address family.
///
///
/// -
/// WSAENOBUFS
/// No buffer space is available.
///
/// -
/// WSANOTINITIALISED
///
/// The Winsock 2 DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
///
///
///
///
/// The WSAAddressToString function provides a protocol-independent address-to-string translation. The
/// WSAAddressToString function takes a socket address structure pointed to by the lpsaAddress parameter and returns a
/// pointer to NULL-terminated string that represents the socket address in the lpszAddressString parameter. While the
/// inet_ntoa function works only with IPv4 addresses, the WSAAddressToString function works with any socket address
/// supported by a Winsock provider on the local computer including IPv6 addresses.
///
///
/// If the lpsaAddress parameter points to an IPv4 socket address (the address family is AF_INET), then the address string
/// returned in the buffer pointed to by the lpszAddressString parameter is in dotted-decimal notation as in "192.168.16.0", an
/// example of an IPv4 address in dotted-decimal notation.
///
///
/// If the lpsaAddress parameter points to an IPv6 socket address (the address family is AF_INET6), then the address string
/// returned in the buffer pointed to by the lpszAddressString parameter is in Internet standard format. The basic string
/// representation consists of 8 hexadecimal numbers separated by colons. A string of consecutive zero numbers is replaced with a
/// double-colon. There can only be one double-colon in the string representation of the IPv6 address.
///
///
/// If the length of the buffer pointed to by the lpszAddressString parameter is not large enough to receive the string
/// representation of the socket address, WSAAddressToString returns WSAEFAULT.
///
///
/// Support for IPv6 addresses using the WSAAddressToString function was added on Windows XP with Service Pack 1 (SP1)and
/// later. IPv6 must also be installed on the local computer for the WSAAddressToString function to support IPv6 addresses.
///
///
/// Windows Phone 8: The WSAAddressToStringW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSAAddressToStringW function is supported for Windows Store
/// apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-wsaaddresstostringa INT WSAAPI WSAAddressToStringA(
// LPSOCKADDR lpsaAddress, DWORD dwAddressLength, LPWSAPROTOCOL_INFOA lpProtocolInfo, LPSTR lpszAddressString, LPDWORD
// lpdwAddressStringLength );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "d72e55e6-79a9-4386-9e1a-24a322f13426")]
public static extern WSRESULT WSAAddressToString([In] SOCKADDR lpsaAddress, uint dwAddressLength, [Optional] IntPtr lpProtocolInfo, StringBuilder lpszAddressString, ref uint lpdwAddressStringLength);
///
/// The WSAAsyncGetHostByAddr function asynchronously retrieves host information that corresponds to an address.
///
/// Note The WSAAsyncGetHostByAddr function is not designed to provide parallel resolution of several addresses.
/// Therefore, applications that issue several requests should not expect them to be executed concurrently. Alternatively,
/// applications can start another thread and use the getnameinfo function to resolve addresses in an IP-version agnostic manner.
/// Developers creating Windows Sockets 2 applications are urged to use the getnameinfo function to enable smooth transition
/// to IPv6 compatibility.
///
///
/// [in] The handle of the window which should receive a message when the asynchronous request completes.
/// [in] The message to be received when the asynchronous request completes.
/// [in] A pointer to the network address for the host. Host addresses are stored in network byte order.
/// [in] The length of the address.
/// [in] The type of the address.
///
/// [out] A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent
/// structure. This is because the data area supplied is used by Windows Sockets to contain not only a hostent structure but any and
/// all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of
/// MAXGETHOSTSTRUCT bytes.
///
/// [in] The size of data area buf above.
///
///
/// The return value specifies whether or not the asynchronous operation was successfully initiated. It does not imply success or
/// failure of the operation itself.
///
///
/// If no error occurs, WSAAsyncGetHostByAddr returns a nonzero value of type HANDLE that is the asynchronous task handle
/// (not to be confused with a Windows HTASK) for the request. This value can be used in two ways. It can be used to cancel the
/// operation using WSACancelAsyncRequest, or it can be used to match up asynchronous operations and completion messages by
/// examining the wParam message parameter.
///
///
/// If the asynchronous operation could not be initiated, WSAAsyncGetHostByAddr returns a zero value, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
/// The following error codes can be set when an application window receives a message. As described above, they can be extracted
/// from the lParam in the reply message using the WSAGETASYNCERROR macro.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOBUFS
/// Insufficient buffer space is available.
///
/// -
/// WSAEFAULT
/// The addr or buf parameter is not in a valid part of the process address space.
///
/// -
/// WSAHOST_NOT_FOUND
/// Authoritative answer host not found.
///
/// -
/// WSATRY_AGAIN
/// Nonauthoritative host not found, or SERVERFAIL.
///
/// -
/// WSANO_RECOVERY
/// Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
///
/// -
/// WSANO_DATA
/// Valid name, no data record of requested type.
///
///
///
/// The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.
///
///
///
/// Error Code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEWOULDBLOCK
///
/// The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
///
///
///
///
///
///
/// The WSAAsyncGetHostByAddr function is an asynchronous version of gethostbyaddr. It is used to retrieve the host name and
/// address information that corresponds to a network address. Windows Sockets initiates the operation and returns to the caller
/// immediately, passing back an opaque, asynchronous task handle that the application can use to identify the operation. When the
/// operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the
/// application's window.
///
///
/// When the asynchronous operation has completed, the application window indicated by the hWnd parameter receives message in the
/// wMsg parameter. The wParam parameter contains the asynchronous task handle as returned by the original function call. The high
/// 16 bits of lParam contain any error code. The error code can be any error as defined in Winsock2.h. An error code of zero
/// indicates successful completion of the asynchronous operation.
///
///
/// On successful completion, the buffer specified to the original function call contains a hostent structure. To access the members
/// of this structure, the original buffer address is cast to a hostent structure pointer and accessed as appropriate.
///
///
/// If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all
/// the resulting information. In this case, the low 16 bits of lParam contain the size of buffer required to supply all the
/// requisite information. If the application decides that the partial data is inadequate, it can reissue the
/// WSAAsyncGetHostByAddr function call with a buffer large enough to receive all the desired information (that is, no
/// smaller than the low 16 bits of lParam).
///
///
/// The buffer specified to this function is used by Windows Sockets to construct a structure together with the contents of data
/// areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error, the application should provide a
/// buffer of at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h).
///
///
/// The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and
/// WSAGETASYNCBUFLEN, defined in Winsock2.h as:
///
/// The use of these macros will maximize the portability of the source code for the application.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsaasyncgethostbyaddr HANDLE WSAAsyncGetHostByAddr( HWND
// hWnd, u_int wMsg, const char *addr, int len, int type, char *buf, int buflen );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "814cbb2e-8dd2-44b0-b8be-cfc5491bdc49")]
public static extern HANDLE WSAAsyncGetHostByAddr(HWND hWnd, uint wMsg, [In] IntPtr addr, int len, int type, [Out] IntPtr buf, int buflen);
///
/// The WSAAsyncGetHostByName function asynchronously retrieves host information that corresponds to a host name.
///
/// Note The WSAAsyncGetHostByName function is not designed to provide parallel resolution of several names.
/// Therefore, applications that issue several requests should not expect them to be executed concurrently. Alternatively,
/// applications can start another thread and use the getaddrinfo function to resolve names in an IP-version agnostic manner.
/// Developers creating Windows Sockets 2 applications are urged to use the getaddrinfo function to enable smooth transition
/// to IPv6 compatibility.
///
///
/// [in] The handle of the window which should receive a message when the asynchronous request completes.
/// [in] The message to be received when the asynchronous request completes.
/// [in] A pointer to the null terminated name of the host.
///
/// [out] A pointer to the data area to receive the hostent data. Note that this must be larger than the size of a hostent
/// structure. This is because the data area supplied is used by Windows Sockets to contain not only a hostent structure but any and
/// all of the data which is referenced by members of the hostent structure. It is recommended that you supply a buffer of
/// MAXGETHOSTSTRUCT bytes.
///
/// [in] The size of data area buf above.
///
/// The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply
/// success or failure of the operation itself.
///
/// If the operation was successfully initiated, WSAAsyncGetHostByName returns a nonzero value of type HANDLE which is the
/// asynchronous task handle(not to be confused with a Windows HTASK) for the request.This value can be used in two ways. It can be
/// used to cancel the operation using WSACancelAsyncRequest. It can also be used to match up asynchronous operations and completion
/// messages, by examining the wParam message argument.
///
///
/// If the asynchronous operation could not be initiated, WSAAsyncGetHostByName returns a zero value, and a specific error number
/// can be retrieved by calling WSAGetLastError.
///
///
///
///
/// The WSAAsyncGetHostByName function is an asynchronous version of gethostbyname, and is used to retrieve host name and
/// address information corresponding to a host name. Windows Sockets initiates the operation and returns to the caller immediately,
/// passing back an opaque asynchronous task handle that which the application can use to identify the operation. When the operation
/// is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.
///
///
/// When the asynchronous operation has completed, the application window indicated by the hWnd parameter receives message in the
/// wMsg parameter. The wParam parameter contains the asynchronous task handle as returned by the original function call. The high
/// 16 bits of lParam contain any error code. The error code can be any error as defined in Winsock2.h. An error code of zero
/// indicates successful completion of the asynchronous operation.
///
///
/// On successful completion, the buffer specified to the original function call contains a hostent structure. To access the
/// elements of this structure, the original buffer address should be cast to a hostent structure pointer and accessed as appropriate.
///
///
/// If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all
/// the resulting information. In this case, the low 16 bits of lParam contain the size of buffer required to supply all the
/// requisite information. If the application decides that the partial data is inadequate, it can reissue the
/// WSAAsyncGetHostByName function call with a buffer large enough to receive all the desired information (that is, no
/// smaller than the low 16 bits of lParam).
///
///
/// The buffer specified to this function is used by Windows Sockets to construct a hostent structure together with the contents of
/// data areas referenced by members of the same hostent structure. To avoid the WSAENOBUFS error, the application should
/// provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h).
///
///
/// The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and
/// WSAGETASYNCBUFLEN, defined in Winsock2.h as:
///
/// The use of these macros will maximize the portability of the source code for the application.
/// WSAAsyncGetHostByName is guaranteed to resolve the string returned by a successful call to gethostname.
///
// https://docs.microsoft.com/en-us/windows/win32/api/wsipv6ok/nf-wsipv6ok-wsaasyncgethostbyname HANDLE WSAAsyncGetHostByName( _In_
// HWND hWnd, _In_ u_int wMsg, _In_z_ const char FAR * name, _Out_writes_bytes_(buflen) char FAR * buf, _In_ int buflen );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Ansi)]
[PInvokeData("wsipv6ok.h", MSDNShortId = "1a2b9c76-6e84-4ac2-b5c1-a2268edd0c49")]
public static extern HANDLE WSAAsyncGetHostByName(HWND hWnd, uint wMsg, [In] string name, [Out] IntPtr buf, int buflen);
///
/// The WSAAsyncGetProtoByName function asynchronously retrieves protocol information that corresponds to a protocol name.
///
/// Handle of the window that will receive a message when the asynchronous request completes.
/// Message to be received when the asynchronous request completes.
/// Pointer to the null-terminated protocol name to be resolved.
///
/// Pointer to the data area to receive the protoent data. The data area must be larger than the size of a protoent structure
/// because the data area is used by Windows Sockets to contain a protoent structure and all of the data that is referenced
/// by members of the protoent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
///
/// Size of data area for the buf parameter, in bytes.
///
///
/// The return value specifies whether or not the asynchronous operation was successfully initiated. It does not imply success or
/// failure of the operation itself.
///
///
/// If no error occurs, WSAAsyncGetProtoByName returns a nonzero value of type HANDLE that is the asynchronous task handle
/// for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel the
/// operation using WSACancelAsyncRequest, or it can be used to match up asynchronous operations and completion messages, by
/// examining the wParam message parameter.
///
///
/// If the asynchronous operation could not be initiated, WSAAsyncGetProtoByName returns a zero value, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
/// The following error codes can be set when an application window receives a message. As described above, they can be extracted
/// from the lParam in the reply message using the WSAGETASYNCERROR macro.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOBUFS
/// Insufficient buffer space is available.
///
/// -
/// WSAEFAULT
/// The name or buf parameter is not in a valid part of the process address space.
///
/// -
/// WSAHOST_NOT_FOUND
/// Authoritative answer protocol not found.
///
/// -
/// WSATRY_AGAIN
/// A nonauthoritative protocol not found, or server failure.
///
/// -
/// WSANO_RECOVERY
/// Nonrecoverable errors, the protocols database is not accessible.
///
/// -
/// WSANO_DATA
/// Valid name, no data record of requested type.
///
///
///
/// The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEWOULDBLOCK
///
/// The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
///
///
///
///
///
///
/// The WSAAsyncGetProtoByName function is an asynchronous version of getprotobyname. It is used to retrieve the protocol
/// name and number from the Windows Sockets database corresponding to a given protocol name. Windows Sockets initiates the
/// operation and returns to the caller immediately, passing back an opaque, asynchronous task handle that the application can use
/// to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the
/// caller and a message is sent to the application's window.
///
///
/// When the asynchronous operation has completed, the application window indicated by the hWnd parameter receives message in the
/// wMsg parameter. The wParam parameter contains the asynchronous task handle as returned by the original function call. The high
/// 16 bits of lParam contain any error code. The error code can be any error as defined in Winsock2.h. An error code of zero
/// indicates successful completion of the asynchronous operation.
///
///
/// On successful completion, the buffer specified to the original function call contains a protoent structure. To access the
/// members of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.
///
///
/// If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all
/// the resulting information. In this case, the low 16 bits of lParam contain the size of buffer required to supply all the
/// requisite information. If the application decides that the partial data is inadequate, it can reissue the
/// WSAAsyncGetProtoByName function call with a buffer large enough to receive all the desired information (that is, no
/// smaller than the low 16 bits of lParam).
///
///
/// The buffer specified to this function is used by Windows Sockets to construct a protoent structure together with the contents of
/// data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the
/// application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h).
///
///
/// The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and
/// WSAGETASYNCBUFLEN, defined in Winsock2.h as:
///
/// The use of these macros will maximize the portability of the source code for the application.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsaasyncgetprotobyname HANDLE WSAAsyncGetProtoByName( HWND
// hWnd, u_int wMsg, const char *name, char *buf, int buflen );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Ansi)]
[PInvokeData("winsock.h", MSDNShortId = "747c40fd-5dc1-4533-896e-bc1c4368d7bd")]
public static extern HANDLE WSAAsyncGetProtoByName(HWND hWnd, uint wMsg, [In] string name, [Out] IntPtr buf, int buflen);
///
/// The WSAAsyncGetProtoByNumber function asynchronously retrieves protocol information that corresponds to a protocol number.
///
/// Handle of the window that will receive a message when the asynchronous request completes.
/// Message to be received when the asynchronous request completes.
/// Protocol number to be resolved, in host byte order.
///
/// Pointer to the data area to receive the protoent data. The data area must be larger than the size of a protoent structure
/// because the data area is used by Windows Sockets to contain a protoent structure and all of the data that is referenced
/// by members of the protoent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
///
/// Size of data area for the buf parameter, in bytes.
///
///
/// The return value specifies whether or not the asynchronous operation was successfully initiated. It does not imply success or
/// failure of the operation itself.
///
///
/// If no error occurs, WSAAsyncGetProtoByNumber returns a nonzero value of type HANDLE that is the asynchronous task
/// handle for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel
/// the operation using WSACancelAsyncRequest, or it can be used to match up asynchronous operations and completion messages, by
/// examining the wParam message parameter.
///
///
/// If the asynchronous operation could not be initiated, WSAAsyncGetProtoByNumber returns a zero value, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
/// The following error codes can be set when an application window receives a message. As described above, they can be extracted
/// from the lParam in the reply message using the WSAGETASYNCERROR macro.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOBUFS
/// Insufficient buffer space is available.
///
/// -
/// WSAEFAULT
/// The buf parameter is not in a valid part of the process address space.
///
/// -
/// WSAHOST_NOT_FOUND
/// Authoritative answer protocol not found.
///
/// -
/// WSATRY_AGAIN
/// Nonauthoritative protocol not found, or server failure.
///
/// -
/// WSANO_RECOVERY
/// Nonrecoverable errors, the protocols database is not accessible.
///
/// -
/// WSANO_DATA
/// Valid name, no data record of requested type.
///
///
///
/// The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEWOULDBLOCK
///
/// The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
///
///
///
///
///
///
/// The WSAAsyncGetProtoByNumber function is an asynchronous version of getprotobynumber, and is used to retrieve the
/// protocol name and number corresponding to a protocol number. Windows Sockets initiates the operation and returns to the caller
/// immediately, passing back an opaque, asynchronous task handle that the application can use to identify the operation. When the
/// operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the
/// application's window.
///
///
/// When the asynchronous operation has completed, the application window indicated by the hWnd parameter receives message in the
/// wMsg parameter. The wParam parameter contains the asynchronous task handle as returned by the original function call. The high
/// 16 bits of lParam contain any error code. The error code can be any error as defined in Winsock2.h. An error code of zero
/// indicates successful completion of the asynchronous operation.
///
///
/// On successful completion, the buffer specified to the original function call contains a protoent structure. To access the
/// members of this structure, the original buffer address is cast to a protoent structure pointer and accessed as appropriate.
///
///
/// If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all
/// the resulting information. In this case, the low 16 bits of lParam contain the size of buffer required to supply all the
/// requisite information. If the application decides that the partial data is inadequate, it can reissue the
/// WSAAsyncGetProtoByNumber function call with a buffer large enough to receive all the desired information (that is, no
/// smaller than the low 16 bits of lParam).
///
///
/// The buffer specified to this function is used by Windows Sockets to construct a protoent structure together with the contents of
/// data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the
/// application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h).
///
///
/// The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and
/// WSAGETASYNCBUFLEN, defined in Winsock2.h as:
///
/// The use of these macros will maximize the portability of the source code for the application.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsaasyncgetprotobynumber HANDLE WSAAsyncGetProtoByNumber(
// HWND hWnd, u_int wMsg, int number, char *buf, int buflen );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "10f28345-c178-47c0-9d0f-87f6743131d9")]
public static extern HANDLE WSAAsyncGetProtoByNumber(HWND hWnd, uint wMsg, int number, [Out] IntPtr buf, int buflen);
///
/// The WSAAsyncGetServByName function asynchronously retrieves service information that corresponds to a service name and port.
///
/// Handle of the window that should receive a message when the asynchronous request completes.
/// Message to be received when the asynchronous request completes.
/// Pointer to a null-terminated service name.
///
/// Pointer to a protocol name. This can be NULL, in which case WSAAsyncGetServByName will search for the first
/// service entry for which s_name or one of the s_aliases matches the given name. Otherwise, WSAAsyncGetServByName matches
/// both name and proto.
///
///
/// Pointer to the data area to receive the servent data. The data area must be larger than the size of a servent structure
/// because the data area is used by Windows Sockets to contain a servent structure and all of the data that is referenced by
/// members of the servent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
///
/// Size of data area for the buf parameter, in bytes.
///
///
/// The return value specifies whether or not the asynchronous operation was successfully initiated. It does not imply success or
/// failure of the operation itself.
///
///
/// If no error occurs, WSAAsyncGetServByName returns a nonzero value of type HANDLE that is the asynchronous task
/// handle for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel
/// the operation using WSACancelAsyncRequest, or it can be used to match up asynchronous operations and completion messages, by
/// examining the wParam message parameter.
///
///
/// If the asynchronous operation could not be initiated, WSAAsyncServByName returns a zero value, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
/// The following error codes can be set when an application window receives a message. As described above, they can be extracted
/// from the lParam in the reply message using the WSAGETASYNCERROR macro.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOBUFS
/// Insufficient buffer space is available.
///
/// -
/// WSAEFAULT
/// The buf parameter is not in a valid part of the process address space.
///
/// -
/// WSAHOST_NOT_FOUND
/// Authoritative answer host not found.
///
/// -
/// WSATRY_AGAIN
/// Nonauthoritative service not found, or server failure.
///
/// -
/// WSANO_RECOVERY
/// Nonrecoverable errors, the services database is not accessible.
///
/// -
/// WSANO_DATA
/// Valid name, no data record of requested type.
///
///
///
/// The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEWOULDBLOCK
///
/// The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
///
///
///
///
///
///
/// The WSAAsyncGetServByName function is an asynchronous version of getservbyname and is used to retrieve service
/// information corresponding to a service name. Windows Sockets initiates the operation and returns to the caller immediately,
/// passing back an opaque, asynchronous task handle that the application can use to identify the operation. When the operation is
/// completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.
///
///
/// When the asynchronous operation has completed, the application window indicated by the hWnd parameter receives message in the
/// wMsg parameter. The wParam parameter contains the asynchronous task handle as returned by the original function call. The high
/// 16 bits of lParam contain any error code. The error code can be any error as defined in Winsock2.h. An error code of zero
/// indicates successful completion of the asynchronous operation.
///
///
/// On successful completion, the buffer specified to the original function call contains a servent structure. To access the members
/// of this structure, the original buffer address should be cast to a servent structure pointer and accessed as appropriate.
///
///
/// If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all
/// the resulting information. In this case, the low 16 bits of lParam contain the size of buffer required to supply all the
/// requisite information. If the application decides that the partial data is inadequate, it can reissue the
/// WSAAsyncGetServByName function call with a buffer large enough to receive all the desired information (that is, no
/// smaller than the low 16 bits of lParam).
///
///
/// The buffer specified to this function is used by Windows Sockets to construct a servent structure together with the contents of
/// data areas referenced by members of the same servent structure. To avoid the WSAENOBUFS error, the application should
/// provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h).
///
///
/// The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and
/// WSAGETASYNCBUFLEN, defined in Winsock2.h as:
///
/// The use of these macros will maximize the portability of the source code for the application.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsaasyncgetservbyname HANDLE WSAAsyncGetServByName( HWND
// hWnd, u_int wMsg, const char *name, const char *proto, char *buf, int buflen );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true, CharSet = CharSet.Ansi)]
[PInvokeData("winsock.h", MSDNShortId = "d3524197-cd7a-4863-8fbb-a05e6f5d38e0")]
public static extern HANDLE WSAAsyncGetServByName(HWND hWnd, uint wMsg, [In] string name, [In, Optional] string proto, [Out] IntPtr buf, int buflen);
///
/// The WSAAsyncGetServByPort function asynchronously retrieves service information that corresponds to a port and protocol.
///
/// Handle of the window that should receive a message when the asynchronous request completes.
/// Message to be received when the asynchronous request completes.
/// Port for the service, in network byte order.
///
/// Pointer to a protocol name. This can be NULL, in which case WSAAsyncGetServByPort will search for the first
/// service entry for which s_port match the given port. Otherwise, WSAAsyncGetServByPort matches both port and proto.
///
///
/// Pointer to the data area to receive the servent data. The data area must be larger than the size of a servent structure
/// because the data area is used by Windows Sockets to contain a servent structure and all of the data that is referenced by
/// members of the servent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.
///
/// Size of data area for the buf parameter, in bytes.
///
///
/// The return value specifies whether or not the asynchronous operation was successfully initiated. It does not imply success or
/// failure of the operation itself.
///
///
/// If no error occurs, WSAAsyncGetServByPort returns a nonzero value of type HANDLE that is the asynchronous task
/// handle for the request (not to be confused with a Windows HTASK). This value can be used in two ways. It can be used to cancel
/// the operation using WSACancelAsyncRequest, or it can be used to match up asynchronous operations and completion messages, by
/// examining the wParam message parameter.
///
///
/// If the asynchronous operation could not be initiated, WSAAsyncGetServByPort returns a zero value, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
/// The following error codes can be set when an application window receives a message. As described above, they can be extracted
/// from the lParam in the reply message using the WSAGETASYNCERROR macro.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOBUFS
/// Insufficient buffer space is available.
///
/// -
/// WSAEFAULT
/// The proto or buf parameter is not in a valid part of the process address space.
///
/// -
/// WSAHOST_NOT_FOUND
/// Authoritative answer port not found.
///
/// -
/// WSATRY_AGAIN
/// Nonauthoritative port not found, or server failure.
///
/// -
/// WSANO_RECOVERY
/// Nonrecoverable errors, the services database is not accessible.
///
/// -
/// WSANO_DATA
/// Valid name, no data record of requested type.
///
///
///
/// The following errors can occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEWOULDBLOCK
///
/// The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
///
///
///
///
///
///
/// The WSAAsyncGetServByPort function is an asynchronous version of getservbyport, and is used to retrieve service
/// information corresponding to a port number. Windows Sockets initiates the operation and returns to the caller immediately,
/// passing back an opaque, asynchronous task handle that the application can use to identify the operation. When the operation is
/// completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window.
///
///
/// When the asynchronous operation has completed, the application window indicated by the hWnd parameter receives message in the
/// wMsg parameter. The wParam parameter contains the asynchronous task handle as returned by the original function call. The high
/// 16 bits of lParam contain any error code. The error code can be any error as defined in Winsock2.h. An error code of zero
/// indicates successful completion of the asynchronous operation.
///
///
/// On successful completion, the buffer specified to the original function call contains a servent structure. To access the members
/// of this structure, the original buffer address should be cast to a servent structure pointer and accessed as appropriate.
///
///
/// If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all
/// the resulting information. In this case, the low 16 bits of lParam contain the size of buffer required to supply all the
/// requisite information. If the application decides that the partial data is inadequate, it can reissue the
/// WSAAsyncGetServByPort function call with a buffer large enough to receive all the desired information (that is, no
/// smaller than the low 16 bits of lParam).
///
///
/// The buffer specified to this function is used by Windows Sockets to construct a servent structure together with the contents of
/// data areas referenced by members of the same servent structure. To avoid the WSAENOBUFS error, the application should
/// provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in Winsock2.h).
///
///
/// The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and
/// WSAGETASYNCBUFLEN, defined in Winsock2.h as:
///
/// The use of these macros will maximize the portability of the source code for the application.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaasyncgetservbyport HANDLE WSAAPI
// WSAAsyncGetServByPort( HWND hWnd, u_int wMsg, int port, const char *proto, char *buf, int buflen );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "0d0bd09c-ea97-46fb-b7b0-6e3e0a41dbc1")]
public static extern HANDLE WSAAsyncGetServByPort(HWND hWnd, uint wMsg, int port, [In, Optional] string proto, [Out] IntPtr buf, int buflen);
///
///
/// [The WSAAsyncSelect function is available for use in the operating systems specified in the Requirements section. It may
/// be altered or unavailable in subsequent versions. Rather than use Select-style I/O, use Overlapped I/O and Event Objects with WinSock2.]
///
/// The WSAAsyncSelect function requests Windows message-based notification of network events for a socket.
///
/// A descriptor that identifies the socket for which event notification is required.
/// A handle that identifies the window that will receive a message when a network event occurs.
/// A message to be received when a network event occurs.
/// A bitmask that specifies a combination of network events in which the application is interested.
///
///
/// If the WSAAsyncSelect function succeeds, the return value is zero, provided that the application's declaration of
/// interest in the network event set was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can
/// be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem failed.
///
/// -
/// WSAEINVAL
///
/// One of the specified parameters was invalid, such as the window handle not referring to an existing window, or the specified
/// socket is in an invalid state.
///
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
///
///
/// Additional error codes can be set when an application window receives a message. This error code is extracted from the lParam in
/// the reply message using the WSAGETSELECTERROR macro. Possible error codes for each network event are listed in the
/// following table.
///
/// Event: FD_CONNECT
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEAFNOSUPPORT
/// Addresses in the specified family cannot be used with this socket.
///
/// -
/// WSAECONNREFUSED
/// The attempt to connect was rejected.
///
/// -
/// WSAENETUNREACH
/// The network cannot be reached from this host at this time.
///
/// -
/// WSAEFAULT
/// The namelen parameter is invalid.
///
/// -
/// WSAEINVAL
/// The socket is already bound to an address.
///
/// -
/// WSAEISCONN
/// The socket is already connected.
///
/// -
/// WSAEMFILE
/// No more file descriptors are available.
///
/// -
/// WSAENOBUFS
/// No buffer space is available. The socket cannot be connected.
///
/// -
/// WSAENOTCONN
/// The socket is not connected.
///
/// -
/// WSAETIMEDOUT
/// Attempt to connect timed out without establishing a connection.
///
///
/// Event: FD_CLOSE
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem failed.
///
/// -
/// WSAECONNRESET
/// The connection was reset by the remote side.
///
/// -
/// WSAECONNABORTED
/// The connection was terminated due to a time-out or other failure.
///
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem failed.
///
///
/// Event: FD_ROUTING_INTERFACE_CHANGE
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETUNREACH
/// The specified destination is no longer reachable.
///
/// -
/// WSAENETDOWN
/// The network subsystem failed.
///
///
///
///
///
/// The WSAAsyncSelect function is used to request that WS2_32.DLL should send a message to the window hWnd when it detects
/// any network event specified by the lEvent parameter. The message that should be sent is specified by the wMsg parameter. The
/// socket for which notification is required is identified by the s parameter.
///
///
/// The WSAAsyncSelect function automatically sets socket s to nonblocking mode, regardless of the value of lEvent. To set
/// socket s back to blocking mode, it is first necessary to clear the event record associated with socket s via a call to
/// WSAAsyncSelect with lEvent set to zero. You can then call ioctlsocket or WSAIoctl to set the socket back to blocking
/// mode. For more information about how to set the nonblocking socket back to blocking mode, see the ioctlsocket and
/// WSAIoctl functions.
///
/// The lEvent parameter is constructed by using the bitwise OR operator with any value listed in the following table.
///
///
/// Value
/// Meaning
///
/// -
/// FD_READ
/// Set to receive notification of readiness for reading.
///
/// -
/// FD_WRITE
/// Wants to receive notification of readiness for writing.
///
/// -
/// FD_OOB
/// Wants to receive notification of the arrival of OOB data.
///
/// -
/// FD_ACCEPT
/// Wants to receive notification of incoming connections.
///
/// -
/// FD_CONNECT
/// Wants to receive notification of completed connection or multipoint join operation.
///
/// -
/// FD_CLOSE
/// Wants to receive notification of socket closure.
///
/// -
/// FD_QOS
/// Wants to receive notification of socket Quality of Service (QoS) changes.
///
/// -
/// FD_GROUP_QOS
///
/// Wants to receive notification of socket group Quality of Service (QoS) changes (reserved for future use with socket groups). Reserved.
///
///
/// -
/// FD_ROUTING_INTERFACE_CHANGE
/// Wants to receive notification of routing interface changes for the specified destination(s).
///
/// -
/// FD_ADDRESS_LIST_CHANGE
/// Wants to receive notification of local address list changes for the socket protocol family.
///
///
///
/// Issuing a WSAAsyncSelect for a socket cancels any previous WSAAsyncSelect or WSAEventSelect for the same socket.
/// For example, to receive notification for both reading and writing, the application must call WSAAsyncSelect with both
/// FD_READ and FD_WRITE, as follows:
///
///
/// It is not possible to specify different messages for different events. The following code will not work; the second call will
/// cancel the effects of the first, and only FD_WRITE events will be reported with message wMsg2:
///
///
/// To cancel all notification indicating that Windows Sockets should send no further messages related to network events on the
/// socket, lEvent is set to zero.
///
///
/// Although WSAAsyncSelect immediately disables event message posting for the socket in this instance, it is possible that
/// messages could be waiting in the application message queue. Therefore, the application must be prepared to receive network event
/// messages even after cancellation. Closing a socket with closesocket also cancels WSAAsyncSelect message sending, but the
/// same caveat about messages in the queue still applies.
///
///
/// The socket created by the accept function has the same properties as the listening socket used to accept it. Consequently,
/// WSAAsyncSelect events set for the listening socket also apply to the accepted socket. For example, if a listening socket
/// has WSAAsyncSelect events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that
/// listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same wMsg value used for
/// messages. If a different wMsg or events are desired, the application should call WSAAsyncSelect, passing the accepted
/// socket and the desired new data.
///
///
/// When one of the nominated network events occurs on the specified socket s, the application window hWnd receives message wMsg.
/// The wParam parameter identifies the socket on which a network event has occurred. The low word of lParam specifies the network
/// event that has occurred. The high word of lParam contains any error code. The error code be any error as defined in Winsock2.h.
///
///
/// Note Upon receipt of an event notification message, the WSAGetLastError function cannot be used to check the error value
/// because the error value returned can differ from the value in the high word of lParam.
///
///
/// The error and event codes can be extracted from the lParam using the macros WSAGETSELECTERROR and
/// WSAGETSELECTEVENT, defined in Winsock2.h as:
///
/// The use of these macros will maximize the portability of the source code for the application.
/// The possible network event codes that can be returned are listed in the following table.
///
///
/// Value
/// Meaning
///
/// -
/// FD_READ
/// Socket s ready for reading.
///
/// -
/// FD_WRITE
/// Socket s ready for writing.
///
/// -
/// FD_OOB
/// OOB data ready for reading on socket s
///
/// -
/// FD_ACCEPT
/// Socket s ready for accepting a new incoming connection.
///
/// -
/// FD_CONNECT
/// Connection or multipoint join operation initiated on socket s completed.
///
/// -
/// FD_CLOSE
/// Connection identified by socket s has been closed.
///
/// -
/// FD_QOS
/// Quality of Service associated with socket s has changed.
///
/// -
/// FD_GROUP_QOS
///
/// Reserved. Quality of Service associated with the socket group to which s belongs has changed (reserved for future use with
/// socket groups).
///
///
/// -
/// FD_ROUTING_INTERFACE_CHANGE
/// Local interface that should be used to send to the specified destination has changed.
///
/// -
/// FD_ADDRESS_LIST_CHANGE
/// The list of addresses of the socket protocol family to which the application client can bind has changed.
///
///
///
/// Although WSAAsyncSelect can be called with interest in multiple events, the application window will receive a single
/// message for each network event.
///
///
/// As in the case of the select function, WSAAsyncSelect will frequently be used to determine when a data transfer operation
/// (send or recv) can be issued with the expectation of immediate success. Nevertheless, a robust application must be prepared for
/// the possibility that it can receive a message and issue a Windows Sockets 2 call that returns WSAEWOULDBLOCK immediately. For
/// example, the following sequence of events is possible:
///
///
/// -
/// Data arrives on socket s; Windows Sockets 2 posts WSAAsyncSelect message
///
/// -
/// Application processes some other message
///
/// -
/// While processing, application issues an and notices that there is data ready to be read
///
/// -
/// Application issues a to read the data
///
/// -
///
/// Application loops to process next message, eventually reaching the WSAAsyncSelect message indicating that data is ready
/// to read
///
///
/// -
/// Application issues , which fails with the error WSAEWOULDBLOCK.
///
///
/// Other sequences are also possible.
///
/// The WS2_32.DLL will not continually flood an application with messages for a particular network event. Having successfully
/// posted notification of a particular event to an application window, no further message(s) for that network event will be posted
/// to the application window until the application makes the function call that implicitly reenables notification of that network event.
///
///
///
/// Event
/// Reenabling function
///
/// -
/// FD_READ
/// recv, recvfrom, WSARecv, or WSARecvFrom.
///
/// -
/// FD_WRITE
/// send, sendto, WSASend, or WSASendTo.
///
/// -
/// FD_OOB
/// recv, recvfrom, WSARecv, or WSARecvFrom.
///
/// -
/// FD_ACCEPT
/// accept or WSAAccept unless the error code is WSATRY_AGAIN indicating that the condition function returned CF_DEFER.
///
/// -
/// FD_CONNECT
/// None.
///
/// -
/// FD_CLOSE
/// None.
///
/// -
/// FD_QOS
/// WSAIoctl with command SIO_GET_QOS.
///
/// -
/// FD_GROUP_QOS
/// Reserved. WSAIoctl with command SIO_GET_GROUP_QOS (reserved for future use with socket groups).
///
/// -
/// FD_ROUTING_INTERFACE_CHANGE
/// WSAIoctl with command SIO_ROUTING_INTERFACE_CHANGE.
///
/// -
/// FD_ADDRESS_LIST_CHANGE
/// WSAIoctl with command SIO_ADDRESS_LIST_CHANGE.
///
///
/// Any call to the reenabling routine, even one that fails, results in reenabling of message posting for the relevant event.
///
/// For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is level-triggered. This means that if the
/// reenabling routine is called and the relevant condition is still met after the call, a WSAAsyncSelect message is posted
/// to the application. This allows an application to be event-driven and not be concerned with the amount of data that arrives at
/// any one time. Consider the following sequence:
///
///
/// -
///
/// Network transport stack receives 100 bytes of data on socket s and causes Windows Sockets 2 to post an FD_READ message.
///
///
/// -
/// The application issues recv( s, buffptr, 50, 0) to read 50 bytes.
///
/// -
/// Another FD_READ message is posted because there is still data to be read.
///
///
///
/// With these semantics, an application need not read all available data in response to an FD_READ message—a single recv in
/// response to each FD_READ message is appropriate. If an application issues multiple recv calls in response to a
/// single FD_READ, it can receive multiple FD_READ messages. Such an application can require disabling FD_READ
/// messages before starting the recv calls by calling WSAAsyncSelect with the FD_READ event not set.
///
///
/// The FD_QOS and FD_GROUP_QOS events are considered edge triggered. A message will be posted exactly once when a
/// quality of service change occurs. Further messages will not be forthcoming until either the provider detects a further change in
/// quality of service or the application renegotiates the quality of service for the socket.
///
///
/// The FD_ROUTING_INTERFACE_CHANGE message is posted when the local interface that should be used to reach the destination
/// specified in WSAIoctl with SIO_ROUTING_INTERFACE_CHANGE changes after such IOCTL has been issued.
///
///
/// The FD_ADDRESS_LIST_CHANGE message is posted when the list of addresses to which the application can bind changes after
/// WSAIoctl with SIO_ADDRESS_LIST_CHANGE has been issued.
///
///
/// If any event has occurred when the application calls WSAAsyncSelect or when the reenabling function is called, then a
/// message is posted as appropriate. For example, consider the following sequence:
///
///
/// -
/// An application calls listen.
///
/// -
/// A connect request is received, but not yet accepted.
///
/// -
///
/// The application calls WSAAsyncSelect specifying that it requires receiving FD_ACCEPT messages for the socket. Due
/// to the persistence of events, Windows Sockets 2 posts an FD_ACCEPT message immediately.
///
///
///
///
/// The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected
/// with connect or WSAConnect (after FD_CONNECT, if also registered) or accepted with accept or WSAAccept, and then after a send
/// operation fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are
/// possible starting from the first FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such a failure
/// the application will be notified that sends are again possible with an FD_WRITE message.
///
///
/// The FD_OOB event is used only when a socket is configured to receive OOB data separately. If the socket is configured to
/// receive OOB data inline, the OOB (expedited) data is treated as normal data and the application should register an interest in,
/// and will receive, FD_READ events, not FD_OOB events. An application can set or inspect the way in which OOB data
/// is to be handled by using setsockopt or getsockopt for the SO_OOBINLINE option.
///
///
/// The error code in an FD_CLOSE message indicates whether the socket close was graceful or abortive. If the error code is
/// zero, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual circuit was reset. This only
/// applies to connection-oriented sockets such as SOCK_STREAM.
///
///
/// The FD_CLOSE message is posted when a close indication is received for the virtual circuit corresponding to the socket.
/// In TCP terms, this means that the FD_CLOSE is posted when the connection goes into the TIME WAIT or CLOSE WAIT states.
/// This results from the remote end performing a shutdown on the send side or a closesocket. FD_CLOSE should only be posted
/// after all data is read from a socket, but an application should check for remaining data upon receipt of FD_CLOSE to
/// avoid any possibility of losing data.
///
///
/// Be aware that the application will only receive an FD_CLOSE message to indicate closure of a virtual circuit, and only
/// when all the received data has been read if this is a graceful close. It will not receive an FD_READ message to indicate
/// this condition.
///
///
/// The FD_QOS or FD_GROUP_QOS message is posted when any parameter in the flow specification associated with socket s
/// or the socket group that s belongs to has changed, respectively. Applications should use WSAIoctl with command SIO_GET_QOS or
/// SIO_GET_GROUP_QOS to get the current quality of service for socket s or for the socket group s belongs to, respectively.
///
///
/// The FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events are considered edge triggered as well. A message
/// will be posted exactly once when a change occurs after the application has requested the notification by issuing WSAIoctl with
/// SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE correspondingly. Further messages will not be forthcoming until the
/// application reissues the IOCTL and another change is detected because the IOCTL has been issued.
///
/// Here is a summary of events and conditions for each asynchronous notification message.
///
/// -
/// FD_READ:
///
/// -
/// FD_WRITE:
///
/// -
/// FD_OOB: Only valid when setsockopt SO_OOBINLINE is disabled (default).
///
/// -
/// FD_ACCEPT:
///
/// -
/// FD_CONNECT:
///
/// -
/// FD_CLOSE: Only valid on connection-oriented sockets (for example, SOCK_STREAM)
///
/// -
/// FD_QOS:
///
/// -
/// FD_GROUP_QOS: Reserved.
///
/// -
/// FD_ROUTING_INTERFACE_CHANGE:
///
/// -
/// FD_ADDRESS_LIST_CHANGE:
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsaasyncselect int WSAAsyncSelect( SOCKET s, HWND hWnd,
// u_int wMsg, long lEvent );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "a4d3f599-358c-4a94-91eb-7e1c80244250")]
public static extern WSRESULT WSAAsyncSelect(SOCKET s, HWND hWnd, uint wMsg, int lEvent);
/// The WSACancelAsyncRequest function cancels an incomplete asynchronous operation.
/// Handle that specifies the asynchronous operation to be canceled.
///
///
/// The value returned by WSACancelAsyncRequest is zero if the operation was successfully canceled. Otherwise, the value
/// SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINVAL
/// Indicates that the specified asynchronous task handle was invalid.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEALREADY
/// The asynchronous routine being canceled has already completed.
///
///
///
/// Note It is unclear whether the application can usefully distinguish between WSAEINVAL and WSAEALREADY, since in both
/// cases the error indicates that there is no asynchronous operation in progress with the indicated handle. (Trivial exception:
/// zero is always an invalid asynchronous task handle.) The Windows Sockets specification does not prescribe how a conformant
/// Windows Sockets provider should distinguish between the two cases. For maximum portability, a Windows Sockets application should
/// treat the two errors as equivalent.
///
///
///
///
/// The WSACancelAsyncRequest function is used to cancel an asynchronous operation that was initiated by one of the
/// WSAAsyncGetXByY functions such as WSAAsyncGetHostByName. The operation to be canceled is identified by the
/// hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as returned by the initiating
/// WSAAsyncGetXByY function.
///
///
/// An attempt to cancel an existing asynchronous WSAAsyncGetXByY operation can fail with an error code of WSAEALREADY for
/// two reasons. First, the original operation has already completed and the application has dealt with the resultant message.
/// Second, the original operation has already completed but the resultant message is still waiting in the application window queue.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsacancelasyncrequest int WSACancelAsyncRequest( HANDLE
// hAsyncTaskHandle );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "0e53eccf-ef85-43ec-a02c-12896471a7a9")]
public static extern WSRESULT WSACancelAsyncRequest(HANDLE hAsyncTaskHandle);
/// The WSACleanup function terminates use of the Winsock 2 DLL (Ws2_32.dll).
///
///
/// The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
/// In a multithreaded environment, WSACleanup terminates Windows Sockets operations for all threads.
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
///
///
///
///
/// An application or DLL is required to perform a successful WSAStartup call before it can use Windows Sockets services. When it
/// has completed the use of Windows Sockets, the application or DLL must call WSACleanup to deregister itself from a Windows
/// Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL.
///
///
/// When WSACleanup is called, any pending blocking or asynchronous Windows Sockets calls issued by any thread in this
/// process are canceled without posting any notification messages or without signaling any event objects. Any pending overlapped
/// send or receive operations (WSASend, WSASendTo, WSARecv, or WSARecvFrom with an overlapped socket, for example) issued by any
/// thread in this process are also canceled without setting the event object or invoking the completion routine, if one was
/// specified. In this case, the pending overlapped operations fail with the error status WSA_OPERATION_ABORTED.
///
///
/// Sockets that were open when WSACleanup was called are reset and automatically deallocated as if closesocket were called.
/// Sockets that have been closed with closesocket but that still have pending data to be sent can be affected when
/// WSACleanup is called. In this case, the pending data can be lost if the WS2_32.DLL is unloaded from memory as the
/// application exits. To ensure that all pending data is sent, an application should use shutdown to close the connection, then
/// wait until the close completes before calling closesocket and WSACleanup. All resources and internal state, such
/// as queued unposted or posted messages, must be deallocated so as to be available to the next user.
///
///
/// There must be a call to WSACleanup for each successful call to WSAStartup. Only the final WSACleanup function call
/// performs the actual cleanup. The preceding calls simply decrement an internal reference count in the WS2_32.DLL.
///
///
/// NoteWSACleanup does not unregister names (peer names, for example) that may have been registered with a Windows
/// Sockets namespace provider such as Peer Name Resolution Protocol (PNRP) namespace provider.
///
///
/// In Windows Sockets 1.1, attempting to call WSACleanup from within a blocking hook and then failing to check the return
/// code was a common programming error. If a Winsock 1.1 application needs to quit while a blocking call is outstanding, the
/// application has to first cancel the blocking call with WSACancelBlockingCall then issue the WSACleanup call once control
/// has been returned to the application. In Windows Sockets 2, this issue does not exist and the WSACancelBlockingCall
/// function has been removed.
///
///
/// The WSACleanup function typically leads to protocol-specific helper DLLs being unloaded. As a result, the
/// WSACleanup function should not be called from the DllMain function in a application DLL. This can potentially cause
/// deadlocks. For more information, please see the DLL Main Function.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock/nf-winsock-wsacleanup int WSACleanup( );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "72b7cc3e-be34-41e7-acbf-61742149ec8b")]
public static extern WSRESULT WSACleanup();
/// The WSACloseEvent function closes an open event object handle.
/// Object handle identifying the open event.
///
/// If the function succeeds, the return value is TRUE.
/// If the function fails, the return value is FALSE. To get extended error information, call WSAGetLastError.
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSA_INVALID_HANDLE
/// The hEvent is not a valid event object handle.
///
///
///
///
///
/// The WSACloseEvent function closes the handle to an event object and frees resources associated with the event object.
/// This function is used to close a handle created by the WSACreateEventfunction. Once the handle to the event object is closed,
/// further references to this handle will fail with the error WSA_INVALID_HANDLE.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsacloseevent BOOL WSAAPI WSACloseEvent( WSAEVENT hEvent );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "40cefe46-10a3-4b6a-8c89-3e16237fc685")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WSACloseEvent(WSAEVENT hEvent);
///
/// The WSAConnect function establishes a connection to another socket application, exchanges connect data, and specifies
/// required quality of service based on the specified FLOWSPEC structure.
///
/// A descriptor identifying an unconnected socket.
///
/// A pointer to a sockaddr structure that specifies the address to which to connect. For IPv4, the sockaddr contains
/// AF_INET for the address family, the destination IPv4 address, and the destination port. For IPv6, the sockaddr
/// structure contains AF_INET6 for the address family, the destination IPv6 address, the destination port, and may contain
/// additional flow and scope-id information.
///
/// The length, in bytes, of the sockaddr structure pointed to by the name parameter.
///
/// A pointer to the user data that is to be transferred to the other socket during connection establishment. See Remarks.
///
///
/// A pointer to the user data that is to be transferred back from the other socket during connection establishment. See Remarks.
///
/// A pointer to the FLOWSPEC structures for socket s, one for each direction.
///
/// Reserved for future use with socket groups. A pointer to the FLOWSPEC structures for the socket group (if applicable). This
/// parameter should be NULL.
///
///
///
/// If no error occurs, WSAConnect returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code can be
/// retrieved by calling WSAGetLastError. On a blocking socket, the return value indicates success or failure of the connection attempt.
///
///
/// With a nonblocking socket, the connection attempt cannot be completed immediately. In this case, WSAConnect will return
/// SOCKET_ERROR, and WSAGetLastError will return WSAEWOULDBLOCK; the application could therefore:
///
///
/// -
/// Use select to determine the completion of the connection request by checking if the socket is writeable.
///
/// -
///
/// If your application is using WSAAsyncSelect to indicate interest in connection events, then your application will receive an
/// FD_CONNECT notification when the connect operation is complete(successful or not).
///
///
/// -
///
/// If your application is using WSAEventSelect to indicate interest in connection events, then the associated event object will be
/// signaled when the connect operation is complete (successful or not).
///
///
///
///
/// For a nonblocking socket, until the connection attempt completes all subsequent calls to WSAConnect on the same socket
/// will fail with the error code WSAEALREADY.
///
///
/// If the return error code indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the
/// application can call WSAConnect again for the same socket.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEADDRINUSE
///
/// The local address of the socket is already in use and the socket was not marked to allow address reuse with SO_REUSEADDR. This
/// error usually occurs during the execution of bind, but could be delayed until this function if the bind function operates on a
/// partially wildcard address (involving ADDR_ANY) and if a specific address needs to be "committed" at the time of this function.
///
///
/// -
/// WSAEINTR
/// The (blocking) Windows Socket 1.1 call was canceled through WSACancelBlockingCall.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEALREADY
/// A nonblocking connect or WSAConnect call is in progress on the specified socket.
///
/// -
/// WSAEADDRNOTAVAIL
/// The remote address is not a valid address (such as ADDR_ANY).
///
/// -
/// WSAEAFNOSUPPORT
/// Addresses in the specified family cannot be used with this socket.
///
/// -
/// WSAECONNREFUSED
/// The attempt to connect was rejected.
///
/// -
/// WSAEFAULT
///
/// The name or the namelen parameter is not a valid part of the user address space, the namelen parameter is too small, the buffer
/// length for lpCalleeData, lpSQOS, and lpGQOS are too small, or the buffer length for lpCallerData is too large.
///
///
/// -
/// WSAEINVAL
///
/// The parameter s is a listening socket, or the destination address specified is not consistent with that of the constrained group
/// to which the socket belongs, or the lpGQOS parameter is not NULL.
///
///
/// -
/// WSAEISCONN
/// The socket is already connected (connection-oriented sockets only).
///
/// -
/// WSAENETUNREACH
/// The network cannot be reached from this host at this time.
///
/// -
/// WSAEHOSTUNREACH
/// A socket operation was attempted to an unreachable host.
///
/// -
/// WSAENOBUFS
/// No buffer space is available. The socket cannot be connected.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEOPNOTSUPP
/// The FLOWSPEC structures specified in lpSQOS and lpGQOS cannot be satisfied.
///
/// -
/// WSAEPROTONOSUPPORT
/// The lpCallerData parameter is not supported by the service provider.
///
/// -
/// WSAETIMEDOUT
/// Attempt to connect timed out without establishing a connection.
///
/// -
/// WSAEWOULDBLOCK
/// The socket is marked as nonblocking and the connection cannot be completed immediately.
///
/// -
/// WSAEACCES
/// Attempt to connect datagram socket to broadcast address failed because setsockopt SO_BROADCAST is not enabled.
///
///
///
///
///
/// The WSAConnect function is used to create a connection to the specified destination, and to perform a number of other
/// ancillary operations that occur at connect time. If the socket, s, is unbound, unique values are assigned to the local
/// association by the system, and the socket is marked as bound.
///
///
/// For applications targeted to Windows Vista and later, consider using the WSAConnectByList or WSAConnectByName function which
/// greatly simplify client application design.
///
///
/// For connection-oriented sockets (for example, type SOCK_STREAM), an active connection is initiated to the foreign host using
/// name (an address in the namespace of the socket; for a detailed description, please see bind). When this call completes
/// successfully, the socket is ready to send/receive data. If the address parameter of the name structure is all zeroes,
/// WSAConnect will return the error WSAEADDRNOTAVAIL. Any attempt to reconnect an active connection will fail with the error
/// code WSAEISCONN.
///
///
/// Note If a socket is opened, a setsockopt call is made, and then a sendto call is made, Windows Sockets performs an
/// implicit bind function call.
///
///
/// For connection-oriented, nonblocking sockets, it is often not possible to complete the connection immediately. In such cases,
/// this function returns the error WSAEWOULDBLOCK. However, the operation proceeds. When the success or failure outcome becomes
/// known, it may be reported in one of several ways depending on how the client registers for notification. If the client uses
/// select, success is reported in the writefds set and failure is reported in the exceptfds set. If the client uses WSAAsyncSelect
/// or WSAEventSelect, the notification is announced with FD_CONNECT and the error code associated with the FD_CONNECT indicates
/// either success or a specific reason for failure.
///
///
/// For a connectionless socket (for example, type SOCK_DGRAM), the operation performed by WSAConnect is merely to establish
/// a default destination address so that the socket can be used on subsequent connection-oriented send and receive operations
/// (send, WSASend, recv, and WSARecv). Any datagrams received from an address other than the destination address specified will be
/// discarded. If the entire name structure is all zeros (not just the address parameter of the name structure), then the socket
/// will be disconnected. Then, the default remote address will be indeterminate, so send, WSASend, recv, and
/// WSARecv calls will return the error code WSAENOTCONN. However, sendto, WSASendTo, recvfrom, and WSARecvFrom can still be
/// used. The default destination can be changed by simply calling WSAConnect again, even if the socket is already connected.
/// Any datagrams queued for receipt are discarded if name is different from the previous WSAConnect.
///
///
/// For connectionless sockets, name can indicate any valid address, including a broadcast address. However, to connect to a
/// broadcast address, a socket must have setsockopt SO_BROADCAST enabled. Otherwise, WSAConnect will fail with the error
/// code WSAEACCES.
///
///
/// On connectionless sockets, exchange of user-to-user data is not possible and the corresponding parameters will be silently ignored.
///
///
/// The application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.
///
///
/// The lpCallerData parameter contains a pointer to any user data that is to be sent along with the connection request (called
/// connect data). This is additional data, not in the normal network data stream, that is sent with network requests to establish a
/// connection. This option is used by legacy protocols such as DECNet, OSI TP4, and others.
///
///
/// If lpCallerData is NULL, no user data will be passed to the peer. The lpCalleeData is a result parameter that will
/// contain any user data passed back from the other socket as part of the connection establishment in a WSABUF structure. The
/// len member of the WSABUF structure pointed to by the lpCalleeData parameter initially contains the length of the
/// buffer allocated by the application for the buf member of the WSABUF structure. The len member of the
/// WSABUF structure pointed to by the lpCalleeData parameter will be set to zero if no user data has been passed back. The
/// lpCalleeData information will be valid when the connection operation is complete. For blocking sockets, the connection operation
/// completes when the WSAConnect function returns. For nonblocking sockets, completion will be after the FD_CONNECT
/// notification has occurred. If lpCalleeData is NULL, no user data will be passed back. The exact format of the user data
/// is specific to the address family to which the socket belongs.
///
///
/// At connect time, an application can use the lpSQOS and lpGQOS parameter to override any previous quality of service
/// specification made for the socket through WSAIoctl with either the SIO_SET_QOS or SIO_SET_GROUP_QOS opcode.
///
///
/// The lpSQOS parameter specifies the FLOWSPEC structures for socket s, one for each direction, followed by any additional
/// provider-specific parameters. If either the associated transport provider in general or the specific type of socket in
/// particular cannot honor the quality of service request, an error will be returned as indicated in the following. The sending or
/// receiving flow specification values will be ignored, respectively, for any unidirectional sockets. If no provider-specific
/// parameters are specified, the buf and len members of the WSABUF structure pointed to by the lpCalleeData parameter
/// should be set to NULL and zero, respectively. A NULL value for lpSQOS parameter indicates no application-supplied
/// quality of service.
///
///
/// Reserved for future use with socket groups lpGQOS specifies the FLOWSPEC structures for the socket group (if applicable), one
/// for each direction, followed by any additional provider-specific parameters. If no provider-specific parameters are specified,
/// the buf and len members of the WSABUF structure pointed to by the lpCalleeData parameter should be set to
/// NULL and zero, respectively. A NULL value for lpGQOS indicates no application-supplied group quality of service.
/// This parameter will be ignored if s is not the creator of the socket group.
///
///
/// When connected sockets become closed for whatever reason, they should be discarded and recreated. It is safest to assume that
/// when things go awry for any reason on a connected socket, the application must discard and recreate the needed sockets in order
/// to return to a stable point.
///
///
/// Note When issuing a blocking Winsock call such as WSAConnect, Winsock may need to wait for a network event before
/// the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous
/// procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an
/// ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaconnect int WSAAPI WSAConnect( SOCKET s, const
// sockaddr *name, int namelen, LPWSABUF lpCallerData, LPWSABUF lpCalleeData, LPQOS lpSQOS, LPQOS lpGQOS );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "3b32cc6e-3df7-4104-a0d4-317fd445c7b2")]
public static extern WSRESULT WSAConnect(SOCKET s, [In] SOCKADDR name, int namelen, [In, Optional] IntPtr lpCallerData,
[Out, Optional] IntPtr lpCalleeData, [Optional] IntPtr lpSQOS, [Optional] IntPtr lpGQOS);
///
///
/// The WSAConnectByList function establishes a connection to one out of a collection of possible endpoints represented by a
/// set of destination addresses (host names and ports). This function takes all the destination addresses passed to it and all of
/// the local computer's source addresses, and tries connecting using all possible address combinations before giving up.
///
/// This function supports both IPv4 and IPv6 addresses.
///
///
/// A descriptor that identifies an unbound and unconnected socket. Note that unlike other Winsock calls to establish a connection
/// (for example, WSAConnect), the WSAConnectByList function requires an unbound socket.
///
///
/// A pointer to a SOCKET_ADDRESS_LIST structure that represents the possible destination address and port pairs to connect to a
/// peer. It is the application's responsibility to fill in the port number in the each SOCKET_ADDRESS structure in the SOCKET_ADDRESS_LIST.
///
///
/// On input, a pointer to the size, in bytes, of the LocalAddress buffer provided by the caller. On output, a pointer to the size,
/// in bytes, of the SOCKADDR for the local address stored in the LocalAddress buffer filled in by the system upon successful
/// completion of the call.
///
///
/// A pointer to the SOCKADDR structure that receives the local address of the connection. The size of the parameter is
/// exactly the size returned in LocalAddressLength. This is the same information that would be returned by the getsockname
/// function. This parameter can be NULL, in which case, the LocalAddressLength parameter is ignored.
///
///
/// On input, a pointer to the size, in bytes, of the RemoteAddress buffer provided by the caller. On output, a pointer to the size,
/// in bytes, of the SOCKADDR for the remote address stored in RemoteAddress buffer filled-in by the system upon successful
/// completion of the call.
///
///
/// A pointer to the SOCKADDR structure that receives the remote address of the connection. This is the same information that
/// would be returned by the getpeername function. This parameter can be NULL, in which case, the RemoteAddressLength
/// is ignored.
///
///
/// The time, in milliseconds, to wait for a response from the remote application before aborting the call. This parameter can be
/// NULL in which case WSAConnectByList will complete after either the connection is successfully established or after
/// a connection was attempted and failed on all possible local-remote address pairs.
///
/// Reserved for future implementation. This parameter must be set to NULL.
///
///
/// If a connection is established, WSAConnectByList returns TRUE and LocalAddress and RemoteAddress parameters are
/// filled in if these buffers were supplied by the caller.
///
/// If the call fails, FALSE is returned. WSAGetLastError can then be called to get extended error information.
///
///
/// Return code
/// Description
///
/// -
/// WSAEHOSTUNREACH
/// The host passed as the nodename parameter was unreachable.
///
/// -
/// WSAEINVAL
/// An invalid parameter was passed to the function. The Reserved parameter must be NULL.
///
/// -
/// WSAENOBUFS
/// Sufficient memory could not be allocated.
///
/// -
/// WSAENOTSOCK
/// An invalid socket was passed to the function. The s parameter must not be INVALID_SOCKET or NULL.
///
/// -
/// WSAETIMEDOUT
/// A response from the remote application was not received before the timeout parameter was exceeded.
///
///
///
///
///
/// WSAConnectByList is similar to the WSAConnectByName function. Instead of taking a single host name and service name
/// (port), WSAConnectByList takes a list of addresses (host addresses and ports) and connects to one of the addresses. The
/// WSAConnectByList function is designed to support peer-to-peer collaboration scenarios where an application needs to
/// connect to any available node out of a list of potential nodes. WSAConnectByList is compatible with both IPv6 and IPv4 versions.
///
///
/// The set of possible destinations, represented by a list of addresses, is provided by the caller. WSAConnectByList does
/// more than simply attempt to connect to one of possibly many destination addresses. Specifically, the function takes all remote
/// addresses passed in by the caller, all local addresses, and then attempts a connection first using address pairs with the
/// highest chance of success. As such, WSAConnectByList not only ensures that connection will be established if a connection
/// is at all possible, but also minimizes the time to establish the connection.
///
///
/// The caller can specify the LocalAddress and RemoteAddress buffers and lengths to determine the local and remote addresses for
/// which the connection was successfully established.
///
///
/// The timeout parameter allows the caller to limit the time spent by the function in establishing a connection. Internally,
/// WSAConnectByList performs multiple operations (connection attempts). In between each operation, the timeout parameter is
/// checked to see if the timeout has been exceeded and, if so, the call is aborted. Note that an individual operation (connect)
/// will not be interrupted once the timeout is exceeded, so the WSAConnectByList call can take longer to time out than the
/// value specified in the timeout parameter.
///
///
/// WSAConnectByList has limitations: It works only for connection-oriented sockets, such as those of type SOCK_STREAM. The
/// function does not support overlapped I/O or non-blocking behavior. WSAConnectByList will block even if the socket is in
/// non-blocking mode. WSAConnectByList will try connecting (one-by-one) to the various addresses provided by the caller.
/// Potentially, each of these connection attempts may fail with a different error code. Since only a single error code can be
/// returned, the value returned is the error code from the last connection attempt.
///
///
/// To enable both IPv6 and IPv4 addresses to be passed in the single address list accepted by the function, the following steps
/// must be performed prior to calling the function:
///
///
/// -
///
/// The setsockopt function must be called on a socket created for the AF_INET6 address family to disable the IPV6_V6ONLY
/// socket option before calling WSAConnectByList. This is accomplished by calling the setsockopt function on the
/// socket with the level parameter set to IPPROTO_IPV6 (see IPPROTO_IPV6 Socket Options), the optname parameter set to
/// IPV6_V6ONLY, and the optvalue parameter value set to zero .
///
///
/// -
///
/// Any IPv4 addresses must be represented in the IPv4-mapped IPv6 address format which enables an IPv6 only application to
/// communicate with an IPv4 node. The IPv4-mapped IPv6 address format allows the IPv4 address of an IPv4 node to be represented as
/// an IPv6 address. The IPv4 address is encoded into the low-order 32 bits of the IPv6 address, and the high-order 96 bits hold the
/// fixed prefix 0:0:0:0:0:FFFF. The IPv4-mapped IPv6 address format is specified in RFC 4291. For more information, see
/// www.ietf.org/rfc/rfc4291.txt. The IN6ADDR_SETV4MAPPED macro in Mstcpip.h can be used to convert an IPv4 address to the required
/// IPv4-mapped IPv6 address format.
///
///
///
///
/// The arrays of pointers passed in the SocketAddressList parameter point to an array of SOCKET_ADDRESS structures, which are a
/// generic data type. The RemoteAddress and the LocalAddress parameters also point to SOCKADDR structures. When
/// WSAConnectByList is called, it is expected that a socket address type specific to the network protocol or address family
/// being used will actually be passed in these parameters. So for IPv4 addresses, a pointer to a sockaddr_in structure would
/// be cast to a pointer to SOCKADDR when passed as a parameter. For IPv6 addresses, a pointer to a sockaddr_in6
/// structure would be cast to a pointer to SOCKADDR when passed as a parameter. The SocketAddressList parameter can contain
/// pointers to a mixture of IPv4 and IPv6 addresses. So some SOCKET_ADDRESS pointers can be to sockaddr_in structures
/// and others can be to sockaddr_in6 structures. If it is expected that IPv6 addresses can be used, then the RemoteAddress
/// and LocalAddress parameters should point to sockaddr_in6 structures and be cast to SOCKADDR structures. The
/// RemoteAddressLength and the LocalAddressLength parameters must represent the length of these larger structures.
///
///
/// When the WSAConnectByList function returns TRUE, the socket s is in the default state for a connected socket. The socket
/// s does not enable previously set properties or options until SO_UPDATE_CONNECT_CONTEXT is set on the socket. Use the setsockopt
/// function to set the SO_UPDATE_CONNECT_CONTEXT option.
///
/// For example:
///
/// Note When issuing a blocking Winsock call such as WSAConnectByList with the timeout parameter set to NULL, Winsock
/// may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which
/// can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call
/// inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must
/// never be attempted by Winsock clients.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
/// Examples
/// Establish a connection using WSAConnectByList.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaconnectbylist BOOL WSAConnectByList( SOCKET s,
// PSOCKET_ADDRESS_LIST SocketAddress, LPDWORD LocalAddressLength, LPSOCKADDR LocalAddress, LPDWORD RemoteAddressLength, LPSOCKADDR
// RemoteAddress, const timeval *timeout, LPWSAOVERLAPPED Reserved );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "7323d814-e96e-44b9-8ade-a9317e4fbf17")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WSAConnectByList(SOCKET s, in SOCKET_ADDRESS_LIST SocketAddress, ref uint LocalAddressLength, [Out] SOCKADDR LocalAddress,
ref uint RemoteAddressLength, [Out] SOCKADDR RemoteAddress, [In, Optional] IntPtr timeout, IntPtr Reserved = default);
///
///
/// The WSAConnectByName function establishes a connection to a specified host and port. This function is provided to allow a
/// quick connection to a network endpoint given a host name and port.
///
/// This function supports both IPv4 and IPv6 addresses.
///
///
/// A descriptor that identifies an unconnected socket.
///
/// Note On Windows 7, Windows Server 2008 R2, and earlier, the WSAConnectByName function requires an unbound and
/// unconnected socket. This differs from other Winsock calls to establish a connection (for example, WSAConnect).
///
///
///
/// A NULL-terminated string that contains the name of the host or the IP address of the host on which to connect for IPv4 or IPv6.
///
///
///
/// A NULL-terminated string that contains the service name or destination port of the host on which to connect for IPv4 or IPv6.
///
///
/// A service name is a string alias for a port number. For example, “http” is an alias for port 80 defined by the Internet
/// Engineering Task Force (IETF) as the default port used by web servers for the HTTP protocol. Possible values for the servicename
/// parameter when a port number is not specified are listed in the following file:
///
/// %WINDIR%\system32\drivers\etc\services
///
///
/// On input, a pointer to the size, in bytes, of the LocalAddress buffer provided by the caller. On output, a pointer to the size,
/// in bytes, of the SOCKADDR for the local address stored in the LocalAddress buffer filled in by the system upon successful
/// completion of the call.
///
///
/// A pointer to the SOCKADDR structure that receives the local address of the connection. The size of the parameter is
/// exactly the size returned in LocalAddressLength. This is the same information that would be returned by the getsockname
/// function. This parameter can be NULL, in which case, the LocalAddressLength parameter is ignored.
///
///
/// On input, a pointer to the size, in bytes, of the RemoteAddress buffer provided by the caller. On output, a pointer to the size,
/// in bytes, of the SOCKADDR for the remote address stored in RemoteAddress buffer filled-in by the system upon successful
/// completion of the call.
///
///
/// A pointer to the SOCKADDR structure that receives the remote address of the connection. This is the same information that
/// would be returned by the getpeername function. This parameter can be NULL, in which case, the RemoteAddressLength
/// is ignored.
///
/// The time, in milliseconds, to wait for a response from the remote application before aborting the call.
/// Reserved for future implementation. This parameter must be set to NULL.
///
///
/// If a connection is established, WSAConnectByName returns TRUE and LocalAddress and RemoteAddress parameters are
/// filled in if these buffers were supplied by the caller.
///
/// If the call fails, FALSE is returned. WSAGetLastError can then be called to get extended error information.
///
///
/// Return code
/// Description
///
/// -
/// WSAEHOSTUNREACH
/// The host passed as the nodename parameter was unreachable.
///
/// -
/// WSAEINVAL
///
/// An invalid parameter was passed to the function. The nodename or the servicename parameter must not be NULL. The Reserved
/// parameter must be NULL.
///
///
/// -
/// WSAENOBUFS
/// Sufficient memory could not be allocated.
///
/// -
/// WSAENOTSOCK
/// An invalid socket was passed to the function. The s parameter must not be INVALID_SOCKET or NULL.
///
/// -
/// WSAETIMEDOUT
/// A response from the remote application was not received before the timeout parameter was exceeded.
///
///
///
///
///
/// WSAConnectByName is provided to enable quick and transparent connections to remote hosts on specific ports. It is
/// compatible with both IPv6 and IPv4 versions.
///
/// To enable both IPv6 and IPv4 communications, use the following method:
///
/// -
///
/// The setsockopt function must be called on a socket created for the AF_INET6 address family to disable the IPV6_V6ONLY
/// socket option before calling WSAConnectByName. This is accomplished by calling the setsockopt function on the
/// socket with the level parameter set to IPPROTO_IPV6 (see IPPROTO_IPV6 Socket Options), the optname parameter set to
/// IPV6_V6ONLY, and the optvalue parameter value set to zero .
///
///
///
///
/// WSAConnectByName has limitations: It works only for connection-oriented sockets, such as those of type SOCK_STREAM. The
/// function does not support overlapped I/O or non-blocking behavior. WSAConnectByName will block even if the socket is in
/// non-blocking mode.
///
///
/// WSAConnectByName does not support user-provided data during the establishment of a connection. This call does not support
/// FLOWSPEC structures, either. In cases where these features are required, WSAConnect must be used instead.
///
///
/// In versions before Windows 10, if an application needs to bind to a specific local address or port, then WSAConnectByName
/// cannot be used since the socket parameter to WSAConnectByName must be an unbound socket.
///
/// This restriction was removed Windows 10.
///
/// The RemoteAddress and the LocalAddress parameters point to a SOCKADDR structure, which is a generic data type. When
/// WSAConnectByName is called, it is expected that a socket address type specific to the network protocol or address family
/// being used will actually be passed in these parameters. So for IPv4 addresses, a pointer to a sockaddr_in structure would
/// be cast to a pointer to SOCKADDR as the RemoteAddress and LocalAddressparameters. For IPv6 addresses, a pointer to a
/// sockaddr_in6 structure would be cast to a pointer to SOCKADDR as the RemoteAddress and LocalAddressparameters.
///
///
/// When the WSAConnectByName function returns TRUE, the socket s is in the default state for a connected socket. The
/// socket s does not enable previously set properties or options until SO_UPDATE_CONNECT_CONTEXT is set on the socket. Use the
/// setsockopt function to set the SO_UPDATE_CONNECT_CONTEXT option.
///
/// For example:
///
/// Note When issuing a blocking Winsock call such as WSAConnectByName with the timeout parameter set to NULL,
/// Winsock may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation,
/// which can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock
/// call inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and
/// must never be attempted by Winsock clients.
///
///
/// Windows Phone 8: The WSAConnectByNameW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSAConnectByNameW function is supported for Windows Store apps
/// on Windows 8.1, Windows Server 2012 R2, and later.
///
/// Examples
/// Establish a connection using WSAConnectByName.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaconnectbynamea BOOL WSAConnectByNameA( SOCKET s,
// LPCSTR nodename, LPCSTR servicename, LPDWORD LocalAddressLength, LPSOCKADDR LocalAddress, LPDWORD RemoteAddressLength, LPSOCKADDR
// RemoteAddress, const timeval *timeout, LPWSAOVERLAPPED Reserved );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "6d87699f-03bd-4579-9907-ae3c29b7332b")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WSAConnectByName(SOCKET s, [MarshalAs(UnmanagedType.LPTStr)] string nodename, [MarshalAs(UnmanagedType.LPTStr)] string servicename, ref uint LocalAddressLength,
[Out] SOCKADDR LocalAddress, ref uint RemoteAddressLength, [Out] SOCKADDR RemoteAddress, [In, Optional] IntPtr timeout, IntPtr Reserved = default);
/// The WSACreateEvent function creates a new event object.
///
///
/// If no error occurs, WSACreateEvent returns the handle of the event object. Otherwise, the return value is
/// WSA_INVALID_EVENT. To get extended error information, call WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// Not enough free memory available to create the event object.
///
///
///
///
///
/// The WSACreateEvent function creates a manual-reset event object with an initial state of nonsignaled. The handle of the
/// event object returned cannot be inherited by child processes. The event object is unnamed.
///
///
/// The WSASetEvent function can be called to set the state of the event object to signaled. The WSAResetEvent function can be
/// called to set the state of the event object to nonsignaled. When an event object is no longer needed, the WSACloseEvent function
/// should be called to free the resources associated with the event object.
///
///
/// Windows Sockets 2 event objects are system objects in Windows environments. Therefore, if a Windows application wants to use an
/// auto-reset event rather than a manual-reset event, the application can call the CreateEvent function directly. The scope of an
/// event object is limited to the process in which it is created.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsacreateevent WSAEVENT WSAAPI WSACreateEvent();
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "cff3bc31-f34c-4bb2-9004-5ec31d0a704a")]
public static extern SafeWSAEVENT WSACreateEvent();
///
/// The WSADuplicateSocket function returns a WSAPROTOCOL_INFO structure that can be used to create a new socket descriptor
/// for a shared socket. The WSADuplicateSocket function cannot be used on a QOS-enabled socket.
///
/// Descriptor identifying the local socket.
/// Process identifier of the target process in which the duplicated socket will be used.
///
/// Pointer to a buffer, allocated by the client, that is large enough to contain a WSAPROTOCOL_INFO structure. The service provider
/// copies the protocol information structure contents to this buffer.
///
///
///
/// If no error occurs, WSADuplicateSocket returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error
/// code can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINVAL
/// Indicates that one of the specified parameters was invalid.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEMFILE
/// No more socket descriptors are available.
///
/// -
/// WSAENOBUFS
/// No buffer space is available. The socket cannot be created.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
/// The lpProtocolInfo parameter is not a valid part of the user address space.
///
///
///
///
///
/// The WSADuplicateSocket function is used to enable socket sharing between processes. A source process calls
/// WSADuplicateSocket to obtain a special WSAPROTOCOL_INFO structure. It uses some interprocess communications (IPC)
/// mechanism to pass the contents of this structure to a target process, which in turn uses it in a call to WSASocket to obtain a
/// descriptor for the duplicated socket. The special WSAPROTOCOL_INFO structure can only be used once by the target process.
///
///
/// Sockets can be shared among threads in a given process without using the WSADuplicateSocket function because a socket
/// descriptor is valid in all threads of a process.
///
/// One possible scenario for establishing and handing off a shared socket is illustrated in the following table.
///
///
/// Source process
/// IPC
/// Destination process
///
/// -
/// 1) WSASocket, WSAConnect
///
///
///
/// -
/// 2) Request target process identifier
/// ==>
///
///
/// -
///
///
/// 3) Receive process identifier request and respond
///
/// -
/// 4) Receive process identifier
/// <==
///
///
/// -
/// 5) Call WSADuplicateSocket to get a special WSAPROTOCOL_INFO structure
///
///
///
/// -
/// 6) Send WSAPROTOCOL_INFO structure to target
///
///
///
/// -
///
/// ==>
/// 7) Receive WSAPROTOCOL_INFO structure
///
/// -
///
///
/// 8) Call WSASocket to create shared socket descriptor.
///
/// -
///
///
/// 9) Use shared socket for data exchange
///
/// -
/// 10) closesocket
/// <==
///
///
///
///
/// The descriptors that reference a shared socket can be used independently for I/O. However, the Windows Sockets interface does
/// not implement any type of access control, so it is up to the processes involved to coordinate their operations on a shared
/// socket. Shared sockets are typically used to having one process that is responsible for creating sockets and establishing
/// connections, and other processes that are responsible for information exchange.
///
///
/// All of the state information associated with a socket is held in common across all the descriptors because the socket
/// descriptors are duplicated and not the actual socket. For example, a setsockopt operation performed using one descriptor is
/// subsequently visible using a getsockopt from any or all descriptors. Both the source process and the destination process should
/// pass the same flags to their respective WSASocket function calls. If the source process uses the socket function to create the
/// socket, the destination process must pass the WSA_FLAG_OVERLAPPED flag to its WSASocket function call. A process
/// can call closesocket on a duplicated socket and the descriptor will become deallocated. The underlying socket, however, will
/// remain open until closesocket is called by the last remaining descriptor.
///
///
/// Notification on shared sockets is subject to the usual constraints of WSAAsyncSelect and WSAEventSelect. Issuing either of these
/// calls using any of the shared descriptors cancels any previous event registration for the socket, regardless of which descriptor
/// was used to make that registration. Thus, a shared socket cannot deliver FD_READ events to process A and FD_WRITE events to
/// process B. For situations when such tight coordination is required, developers would be advised to use threads instead of
/// separate processes.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSADuplicateSocketW function is supported for Windows Store
/// apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaduplicatesocketa int WSAAPI WSADuplicateSocketA(
// SOCKET s, DWORD dwProcessId, LPWSAPROTOCOL_INFOA lpProtocolInfo );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "d4028461-bfa6-4074-9460-5d1371790d41")]
public static extern WSRESULT WSADuplicateSocket(SOCKET s, uint dwProcessId, out WSAPROTOCOL_INFO lpProtocolInfo);
/// The WSAEnumNameSpaceProviders function retrieves information on available namespace providers.
///
/// On input, the number of bytes contained in the buffer pointed to by lpnspBuffer. On output (if the function fails, and the error
/// is WSAEFAULT), the minimum number of bytes to pass for the lpnspBuffer to retrieve all the requested information. The buffer
/// passed to WSAEnumNameSpaceProviders must be sufficient to hold all of the namespace information.
///
///
/// A buffer that is filled with WSANAMESPACE_INFO structures. The returned structures are located consecutively at the head of the
/// buffer. Variable sized information referenced by pointers in the structures point to locations within the buffer located between
/// the end of the fixed sized structures and the end of the buffer. The number of structures filled in is the return value of WSAEnumNameSpaceProviders.
///
///
///
/// The WSAEnumNameSpaceProviders function returns the number of WSANAMESPACE_INFO structures copied into lpnspBuffer.
/// Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEFAULT
///
/// The lpnspBuffer parameter was a NULL pointer or the buffer length, lpdwBufferLength, was too small to receive all the relevant
/// WSANAMESPACE_INFO structures and associated information. When this error is returned, the buffer length required is returned in
/// the lpdwBufferLength parameter.
///
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
///
/// The WSAEnumNameSpaceProviders function returns information on available namespace providers in the buffer pointed to by
/// the lpnspBuffer parameter. The returned buffer contains an array of WSANAMESPACE_INFO structures located consecutively at the
/// head of the buffer. Variable sized information referenced by pointers in the WSANAMESPACE_INFO structures point to
/// locations within the buffer located between the end of the fixed WSANAMESPACE_INFO structures and the end of the buffer.
/// The number of WSANAMESPACE_INFO structures filled in is returned by the WSAEnumNameSpaceProviders function.
///
///
/// Each WSANAMESPACE_INFO structure entry contains the provider-specific information on the namespace entry passed to the
/// WSCInstallNameSpace and WSCInstallNameSpace32 functions when the namespace provider was installed.
///
///
/// The WSAEnumNameSpaceProvidersEx function is an enhanced version of the WSAEnumNameSpaceProviders function. The
/// WSCEnumNameSpaceProvidersEx32 function is an enhanced version of the WSAEnumNameSpaceProviders function that returns
/// information on available 32-bit namespace providers for use on 64-bit platforms.
///
/// Example Code
///
/// The following example demonstrates the use of the WSAEnumNameSpaceProviders function to retrieve information on available
/// namespace providers.
///
///
/// Windows Phone 8: The WSAEnumNameSpaceProvidersW function is supported for Windows Phone Store apps on Windows
/// Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSAEnumNameSpaceProvidersW function is supported for Windows
/// Store apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaenumnamespaceprovidersw INT WSAAPI
// WSAEnumNameSpaceProvidersW( LPDWORD lpdwBufferLength, LPWSANAMESPACE_INFOW lpnspBuffer );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Unicode)]
[PInvokeData("winsock2.h", MSDNShortId = "f5b6cd42-c5cb-43b6-bb96-fd260217e252")]
public static extern WSRESULT WSAEnumNameSpaceProviders(ref uint lpdwBufferLength, [Out] IntPtr lpnspBuffer);
/// The WSAEnumNameSpaceProvidersEx function retrieves information on available namespace providers.
///
/// On input, the number of bytes contained in the buffer pointed to by lpnspBuffer. On output (if the function fails, and the error
/// is WSAEFAULT), the minimum number of bytes to allocate for the lpnspBuffer buffer to allow it to retrieve all the requested
/// information. The buffer passed to WSAEnumNameSpaceProvidersEx must be sufficient to hold all of the namespace information.
///
///
/// A buffer that is filled with WSANAMESPACE_INFOEX structures. The returned structures are located consecutively at the head of
/// the buffer. Variable sized information referenced by pointers in the structures point to locations within the buffer located
/// between the end of the fixed sized structures and the end of the buffer. The number of structures filled in is the return value
/// of WSAEnumNameSpaceProvidersEx.
///
///
///
/// The WSAEnumNameSpaceProvidersEx function returns the number of WSANAMESPACE_INFOEX structures copied into lpnspBuffer.
/// Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEFAULT
///
/// The lpnspBuffer parameter was a NULL pointer or the buffer length, lpdwBufferLength, was too small to receive all the relevant
/// WSANAMESPACE_INFOEX structures and associated information. When this error is returned, the buffer length required is returned
/// in the lpdwBufferLength parameter.
///
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
///
/// The WSAEnumNameSpaceProvidersEx function is an enhanced version of the WSAEnumNameSpaceProviders function. The
/// provider-specific data blob associated with the namespace entry passed in the lpProviderInfo parameter to the
/// WSCInstallNameSpaceEx function can be queried using WSAEnumNameSpaceProvidersEx function.
///
///
/// Currently, the only namespace provider included with Windows that sets information in the ProviderSpecific member of the
/// WSANAMESPACE_INFOEX structure is the NS_EMAIL provider. The format of the ProviderSpecific member for an NS_EMAIL
/// namespace provider is a NAPI_PROVIDER_INSTALLATION_BLOB structure.
///
///
/// When UNICODE or _UNICODE is defined, WSAEnumNameSpaceProvidersEx is defined to WSAEnumNameSpaceProvidersExW, the
/// Unicode version of this function. The lpnspBuffer parameter is defined to the LPSAWSANAMESPACE_INFOEXW data type and
/// WSANAMESPACE_INFOEXW structures are returned on success.
///
///
/// When UNICODE or _UNICODE is not defined, WSAEnumNameSpaceProvidersEx is defined to WSAEnumNameSpaceProvidersExA,
/// the ANSI version of this function. The lpnspBuffer parameter is defined to the LPSAWSANAMESPACE_INFOEXA data type and
/// WSANAMESPACE_INFOEXA structures are returned on success.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSAEnumNameSpaceProvidersExW function is supported for Windows
/// Store apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaenumnamespaceprovidersexa INT WSAAPI
// WSAEnumNameSpaceProvidersExA( LPDWORD lpdwBufferLength, LPWSANAMESPACE_INFOEXA lpnspBuffer );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Unicode)]
[PInvokeData("winsock2.h", MSDNShortId = "34bc96aa-63f7-4ab8-9376-6f4b979225ca")]
public static extern WSRESULT WSAEnumNameSpaceProvidersEx(ref uint lpdwBufferLength, [Out] IntPtr lpnspBuffer);
///
/// The WSAEnumNetworkEvents function discovers occurrences of network events for the indicated socket, clear internal
/// network event records, and reset event objects (optional).
///
/// A descriptor identifying the socket.
/// An optional handle identifying an associated event object to be reset.
///
/// A pointer to a WSANETWORKEVENTS structure that is filled with a record of network events that occurred and any associated error codes.
///
///
///
/// The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINVAL
/// One of the specified parameters was invalid.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
/// The lpNetworkEvents parameter is not a valid part of the user address space.
///
///
///
///
///
/// The WSAEnumNetworkEvents function is used to discover which network events have occurred for the indicated socket since
/// the last invocation of this function. It is intended for use in conjunction with WSAEventSelect, which associates an event
/// object with one or more network events. The recording of network events commences when WSAEventSelect is called with a
/// nonzero lNetworkEvents parameter and remains in effect until another call is made to WSAEventSelect with the
/// lNetworkEvents parameter set to zero, or until a call is made to WSAAsyncSelect.
///
///
/// WSAEnumNetworkEvents only reports network activity and errors nominated through WSAEventSelect. See the descriptions of
/// select and WSAAsyncSelect to find out how those functions report network activity and errors.
///
///
/// The socket's internal record of network events is copied to the structure referenced by lpNetworkEvents, after which the
/// internal network events record is cleared. If the hEventObject parameter is not NULL, the indicated event object is also
/// reset. The Windows Sockets provider guarantees that the operations of copying the network event record, clearing it and
/// resetting any associated event object are atomic, such that the next occurrence of a nominated network event will cause the
/// event object to become set. In the case of this function returning SOCKET_ERROR, the associated event object is not reset and
/// the record of network events is not cleared.
///
///
/// The lNetworkEvents member of the WSANETWORKEVENTS structure indicates which of the FD_XXX network events have occurred.
/// The iErrorCode array is used to contain any associated error codes with the array index corresponding to the position of
/// event bits in lNetworkEvents. Identifiers such as FD_READ_BIT and FD_WRITE_BIT can be used to index the iErrorCode
/// array. Note that only those elements of the iErrorCode array are set that correspond to the bits set in lNetworkEvents
/// parameter. Other parameters are not modified (this is important for backward compatibility with the applications that are not
/// aware of new FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events).
///
/// The following error codes can be returned along with the corresponding network event.
/// Event: FD_CONNECT
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEAFNOSUPPORT
/// Addresses in the specified family cannot be used with this socket.
///
/// -
/// WSAECONNREFUSED
/// The attempt to connect was forcefully rejected.
///
/// -
/// WSAENETUNREACH
/// The network cannot be reached from this host at this time.
///
/// -
/// WSAENOBUFS
/// No buffer space is available. The socket cannot be connected.
///
/// -
/// WSAETIMEDOUT
/// An attempt to connect timed out without establishing a connection
///
///
/// Event: FD_CLOSE
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAECONNRESET
/// The connection was reset by the remote side.
///
/// -
/// WSAECONNABORTED
/// The connection was terminated due to a time-out or other failure.
///
///
/// Event: FD_ACCEPT
/// Event: FD_ADDRESS_LIST_CHANGE
/// Event: FD_GROUP_QOS
/// Event: FD_QOS
/// Event: FD_OOB
/// Event: FD_READ
/// Event: FD_WRITE
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
///
/// Event: FD_ROUTING_INTERFACE_CHANGE
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETUNREACH
/// The specified destination is no longer reachable.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
///
/// Example Code
/// The following example demonstrates the use of the WSAEnumNetworkEvents function.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaenumnetworkevents int WSAAPI WSAEnumNetworkEvents(
// SOCKET s, WSAEVENT hEventObject, LPWSANETWORKEVENTS lpNetworkEvents );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "2e6abccd-c82c-4a6b-8720-259986ac9984")]
public static extern WSRESULT WSAEnumNetworkEvents(SOCKET s, [Optional] WSAEVENT hEventObject, out WSANETWORKEVENTS lpNetworkEvents);
/// The WSAEnumProtocols function retrieves information about available transport protocols.
///
/// A NULLl-terminated array of iProtocol values. This parameter is optional; if lpiProtocols is NULL, information on
/// all available protocols is returned. Otherwise, information is retrieved only for those protocols listed in the array.
///
/// A pointer to a buffer that is filled with WSAPROTOCOL_INFO structures.
///
/// On input, number of bytes in the lpProtocolBuffer buffer passed to WSAEnumProtocols. On output, the minimum buffer size
/// that can be passed to WSAEnumProtocols to retrieve all the requested information. This routine has no ability to
/// enumerate over multiple calls; the passed-in buffer must be large enough to hold all entries in order for the routine to
/// succeed. This reduces the complexity of the API and should not pose a problem because the number of protocols loaded on a
/// computer is typically small.
///
///
///
/// If no error occurs, WSAEnumProtocols returns the number of protocols to be reported. Otherwise, a value of SOCKET_ERROR
/// is returned and a specific error code can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress.
///
/// -
/// WSAEINVAL
/// Indicates that one of the specified parameters was invalid.
///
/// -
/// WSAENOBUFS
///
/// The buffer length was too small to receive all the relevant WSAPROTOCOL_INFO structures and associated information. Pass in a
/// buffer at least as large as the value returned in lpdwBufferLength.
///
///
/// -
/// WSAEFAULT
///
/// One or more of the lpiProtocols, lpProtocolBuffer, or lpdwBufferLength parameters are not a valid part of the user address space.
///
///
///
///
///
///
/// The WSAEnumProtocols function is used to discover information about the collection of transport protocols installed on
/// the local computer. Layered protocols are only usable by applications when installed in protocol chains. Information on layered
/// protocols is not returned except for any dummy layered service providers (LSPs) installed with a chain length of zero in the lpProtocolBuffer.
///
///
/// Note Layered Service Providers are deprecated. Starting with Windows 8 and Windows Server 2012, use Windows Filtering Platform.
///
///
/// The lpiProtocols parameter can be used as a filter to constrain the amount of information provided. Often, lpiProtocols will be
/// specified as a NULL pointer that will cause the function to return information on all available transport protocols and
/// protocol chains.
///
///
/// The WSAEnumProtocols function differs from the WSCEnumProtocols and WSCEnumProtocols32 functions in that the
/// WSAEnumProtocols function doesn't return WSAPROTOCOL_INFO structures for all installed protocols. The
/// WSAEnumProtocols function excludes protocols that the service provider has set with the PFL_HIDDEN flag in the
/// dwProviderFlags member of the WSAPROTOCOL_INFO structure to indicate to the Ws2_32.dll that this protocol should not be
/// returned in the result buffer generated by WSAEnumProtocols function. In addition, the WSAEnumProtocols function
/// does not return data for WSAPROTOCOL_INFO structures that have a chain length of one or greater (an LSP provider). The
/// WSAEnumProtocols only returns information on base protocols and protocol chains that lack the PFL_HIDDEN flag and
/// don't have a protocol chain length of zero.
///
///
/// A WSAPROTOCOL_INFO structure is provided in the buffer pointed to by lpProtocolBuffer for each requested protocol. If the
/// specified buffer is not large enough (as indicated by the input value of lpdwBufferLength ), the value pointed to by
/// lpdwBufferLength will be updated to indicate the required buffer size. The application should then obtain a large enough buffer
/// and call WSAEnumProtocols again.
///
///
/// The order in which the WSAPROTOCOL_INFO structures appear in the buffer coincides with the order in which the protocol entries
/// were registered by the service provider using the WS2_32.DLL, or with any subsequent reordering that occurred through the
/// Windows Sockets application or DLL supplied for establishing default TCP/IP providers.
///
///
/// Windows Phone 8: The WSAEnumProtocolsW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSAEnumProtocolsW function is supported for Windows Store apps
/// on Windows 8.1, Windows Server 2012 R2, and later.
///
/// Examples
///
/// The following example demonstrates the use of the WSAEnumProtocols function to retrieve an array of WSAPROTOCOL_INFO
/// structures for available transport protocols.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaenumprotocolsa int WSAAPI WSAEnumProtocolsA( LPINT
// lpiProtocols, LPWSAPROTOCOL_INFOA lpProtocolBuffer, LPDWORD lpdwBufferLength );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "928b6937-41a3-4268-a3bc-14c9e04870e4")]
public static extern WSRESULT WSAEnumProtocols([Optional, MarshalAs(UnmanagedType.LPArray)] int[] lpiProtocols, [Out] IntPtr lpProtocolBuffer, ref uint lpdwBufferLength);
///
/// The WSAEventSelect function specifies an event object to be associated with the specified set of FD_XXX network events.
///
/// A descriptor identifying the socket.
///
/// A handle identifying the event object to be associated with the specified set of FD_XXX network events.
///
///
/// A bitmask that specifies the combination of FD_XXX network events in which the application has interest.
///
///
///
/// The return value is zero if the application's specification of the network events and the associated event object was
/// successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
/// As in the case of the select and WSAAsyncSelect functions, WSAEventSelect will frequently be used to determine when a
/// data transfer operation (send or recv) can be issued with the expectation of immediate success. Nevertheless, a robust
/// application must be prepared for the possibility that the event object is set and it issues a Windows Sockets call that returns
/// WSAEWOULDBLOCK immediately. For example, the following sequence of operations is possible:
///
///
/// -
/// Data arrives on socket s; Windows Sockets sets the WSAEventSelect event object.
///
/// -
/// The application does some other processing.
///
/// -
/// While processing, the application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read.
///
/// -
/// The application issues a recv(s,...) to read the data.
///
/// -
///
/// The application eventually waits on the event object specified in WSAEventSelect, which returns immediately indicating
/// that data is ready to read.
///
///
/// -
/// The application issues recv(s,...), which fails with the error WSAEWOULDBLOCK.
///
///
///
/// Having successfully recorded the occurrence of the network event (by setting the corresponding bit in the internal network event
/// record) and signaled the associated event object, no further actions are taken for that network event until the application
/// makes the function call that implicitly reenables the setting of that network event and signaling of the associated event object.
///
///
///
/// Network event
/// Re-enabling function
///
/// -
/// FD_READ
/// The recv, recvfrom, WSARecv, WSARecvEx, or WSARecvFrom function.
///
/// -
/// FD_WRITE
/// The send, sendto, WSASend, or WSASendTo function.
///
/// -
/// FD_OOB
/// The recv, recvfrom, WSARecv, WSARecvEx, or WSARecvFrom function.
///
/// -
/// FD_ACCEPT
///
/// The accept, AcceptEx, or WSAAccept function unless the error code returned is WSATRY_AGAIN indicating that the condition
/// function returned CF_DEFER.
///
///
/// -
/// FD_CONNECT
/// None.
///
/// -
/// FD_CLOSE
/// None.
///
/// -
/// FD_QOS
/// The WSAIoctl function with command SIO_GET_QOS.
///
/// -
/// FD_GROUP_QOS
/// Reserved.
///
/// -
/// FD_ROUTING_ INTERFACE_CHANGE
/// The WSAIoctl function with command SIO_ROUTING_INTERFACE_CHANGE.
///
/// -
/// FD_ADDRESS_ LIST_CHANGE
/// The WSAIoctl function with command SIO_ADDRESS_LIST_CHANGE.
///
///
///
/// Any call to the reenabling routine, even one that fails, results in reenabling of recording and signaling for the relevant
/// network event and event object.
///
///
/// For FD_READ, FD_OOB, and FD_ACCEPT network events, network event recording and event object signaling are level-triggered. This
/// means that if the reenabling routine is called and the relevant network condition is still valid after the call, the network
/// event is recorded and the associated event object is set. This allows an application to be event-driven and not be concerned
/// with the amount of data that arrives at any one time. Consider the following sequence:
///
///
/// -
///
/// The transport provider receives 100 bytes of data on socket s and causes WS2_32.DLL to record the FD_READ network event and set
/// the associated event object.
///
///
/// -
/// The application issues recv(s, buffptr, 50, 0) to read 50 bytes.
///
/// -
///
/// The transport provider causes WS2_32.DLL to record the FD_READ network event and sets the associated event object again since
/// there is still data to be read.
///
///
///
///
/// With these semantics, an application need not read all available data in response to an FD_READ network event—a single recv in
/// response to each FD_READ network event is appropriate.
///
///
/// The FD_QOS event is considered edge triggered. A message will be posted exactly once when a quality of service change occurs.
/// Further messages will not be forthcoming until either the provider detects a further change in quality of service or the
/// application renegotiates the quality of service for the socket.
///
///
/// The FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events are considered edge triggered as well. A message will be
/// posted exactly once when a change occurs after the application has requested the notification by issuing WSAIoctl with
/// SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE correspondingly. Other messages will not be forthcoming
/// until the application reissues the IOCTL and another change is detected since the IOCTL has been issued.
///
///
/// If a network event has already happened when the application calls WSAEventSelect or when the reenabling function is
/// called, then a network event is recorded and the associated event object is set as appropriate. For example, consider the
/// following sequence:
///
///
/// -
/// An application calls listen.
///
/// -
/// A connect request is received but not yet accepted.
///
/// -
///
/// The application calls WSAEventSelect specifying that it is interested in the FD_ACCEPT network event for the socket. Due
/// to the persistence of network events, Windows Sockets records the FD_ACCEPT network event and sets the associated event object immediately.
///
///
///
///
/// The FD_WRITE network event is handled slightly differently. An FD_WRITE network event is recorded when a socket is first
/// connected with a call to the connect, ConnectEx, WSAConnect, WSAConnectByList, or WSAConnectByName function or when a socket is
/// accepted with accept, AcceptEx, or WSAAccept function and then after a send fails with WSAEWOULDBLOCK and buffer space becomes
/// available. Therefore, an application can assume that sends are possible starting from the first FD_WRITE network event setting
/// and lasting until a send returns WSAEWOULDBLOCK. After such a failure the application will find out that sends are again
/// possible when an FD_WRITE network event is recorded and the associated event object is set.
///
///
/// The FD_OOB network event is used only when a socket is configured to receive OOB data separately. If the socket is configured to
/// receive OOB data inline, the OOB (expedited) data is treated as normal data and the application should register an interest in,
/// and will get FD_READ network event, not FD_OOB network event. An application can set or inspect the way in which OOB data is to
/// be handled by using setsockopt or getsockopt for the SO_OOBINLINE option.
///
///
/// The error code in an FD_CLOSE network event indicates whether the socket close was graceful or abortive. If the error code is
/// zero, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual circuit was reset. This only
/// applies to connection-oriented sockets such as SOCK_STREAM.
///
///
/// The FD_CLOSE network event is recorded when a close indication is received for the virtual circuit corresponding to the socket.
/// In TCP terms, this means that the FD_CLOSE is recorded when the connection goes into the TIME WAIT or CLOSE WAIT states. This
/// results from the remote end performing a shutdown on the send side or a closesocket. FD_CLOSE being posted after all data is
/// read from a socket. An application should check for remaining data upon receipt of FD_CLOSE to avoid any possibility of losing
/// data. For more information, see the section on Graceful Shutdown, Linger Options, and Socket Closure and the shutdown function.
///
///
/// Note that Windows Sockets will record only an FD_CLOSE network event to indicate closure of a virtual circuit. It will not
/// record an FD_READ network event to indicate this condition.
///
///
/// The FD_QOS or FD_GROUP_QOS network event is recorded when any parameter in the flow specification associated with socket s.
/// Applications should use WSAIoctl with command SIO_GET_QOS to get the current quality of service for socket s.
///
///
/// The FD_ROUTING_INTERFACE_CHANGE network event is recorded when the local interface that should be used to reach the destination
/// specified in WSAIoctl with SIO_ROUTING_INTERFACE_CHANGE changes after such IOCTL has been issued.
///
///
/// The FD_ADDRESS_LIST_CHANGE network event is recorded when the list of addresses of protocol family for the socket to which the
/// application can bind changes after WSAIoctl with SIO_ADDRESS_LIST_CHANGE has been issued.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINVAL
/// One of the specified parameters was invalid, or the specified socket is in an invalid state.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
///
///
///
///
/// The WSAEventSelect function is used to specify an event object, hEventObject, to be associated with the selected FD_XXX
/// network events, lNetworkEvents. The socket for which an event object is specified is identified by the s parameter. The event
/// object is set when any of the nominated network events occur.
///
///
/// The WSAEventSelect function operates very similarly to WSAAsyncSelect, the difference being the actions taken when a
/// nominated network event occurs. The WSAAsyncSelect function causes an application-specified Windows message to be posted.
/// The WSAEventSelect sets the associated event object and records the occurrence of this event in an internal network event
/// record. An application can use WSAWaitForMultipleEvents to wait or poll on the event object, and use WSAEnumNetworkEvents to
/// retrieve the contents of the internal network event record and thus determine which of the nominated network events have occurred.
///
///
/// The proper way to reset the state of an event object used with the WSAEventSelect function is to pass the handle of the
/// event object to the WSAEnumNetworkEvents function in the hEventObject parameter. This will reset the event object and adjust the
/// status of active FD events on the socket in an atomic fashion.
///
///
/// WSAEventSelect is the only function that causes network activity and errors to be recorded and retrievable through
/// WSAEnumNetworkEvents. See the descriptions of select and WSAAsyncSelect to find out how those functions report network activity
/// and errors.
///
///
/// The WSAEventSelect function automatically sets socket s to nonblocking mode, regardless of the value of lNetworkEvents.
/// To set socket s back to blocking mode, it is first necessary to clear the event record associated with socket s via a call to
/// WSAEventSelect with lNetworkEvents set to zero and the hEventObject parameter set to NULL. You can then call
/// ioctlsocket or WSAIoctl to set the socket back to blocking mode.
///
///
/// The lNetworkEvents parameter is constructed by using the bitwise OR operator with any of the values specified in the following list.
///
///
///
/// Value
/// Meaning
///
/// -
/// FD_READ
/// Wants to receive notification of readiness for reading.
///
/// -
/// FD_WRITE
/// Wants to receive notification of readiness for writing.
///
/// -
/// FD_OOB
/// Wants to receive notification of the arrival of OOB data.
///
/// -
/// FD_ACCEPT
/// Wants to receive notification of incoming connections.
///
/// -
/// FD_CONNECT
/// Wants to receive notification of completed connection or multipoint join operation.
///
/// -
/// FD_CLOSE
/// Wants to receive notification of socket closure.
///
/// -
/// FD_QOS
/// Wants to receive notification of socket (QoS changes.
///
/// -
/// FD_GROUP_QOS
/// Reserved for future use with socket groups. Want to receive notification of socket group QoS changes.
///
/// -
/// FD_ROUTING_ INTERFACE_CHANGE
/// Wants to receive notification of routing interface changes for the specified destination.
///
/// -
/// FD_ADDRESS_ LIST_CHANGE
/// Wants to receive notification of local address list changes for the address family of the socket.
///
///
///
/// Issuing a WSAEventSelect for a socket cancels any previous WSAAsyncSelect or WSAEventSelect for the same socket
/// and clears the internal network event record. For example, to associate an event object with both reading and writing network
/// events, the application must call WSAEventSelect with both FD_READ and FD_WRITE, as follows:
///
///
/// It is not possible to specify different event objects for different network events. The following code will not work; the second
/// call will cancel the effects of the first, and only the FD_WRITE network event will be associated with hEventObject2:
///
///
/// To cancel the association and selection of network events on a socket, lNetworkEvents should be set to zero, in which case the
/// hEventObject parameter will be ignored.
///
///
/// Closing a socket with closesocket also cancels the association and selection of network events specified in
/// WSAEventSelect for the socket. The application, however, still must call WSACloseEvent to explicitly close the event
/// object and free any resources.
///
///
/// The socket created when the accept function is called has the same properties as the listening socket used to accept it. Any
/// WSAEventSelect association and network events selection set for the listening socket apply to the accepted socket. For
/// example, if a listening socket has WSAEventSelect association of hEventObject with FD_ACCEPT, FD_READ, and FD_WRITE, then
/// any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE network events associated with the
/// same hEventObject. If a different hEventObject or network events are desired, the application should call WSAEventSelect,
/// passing the accepted socket and the desired new information.
///
/// Example Code
/// The following example demonstrates the use of the WSAEventSelect function.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaeventselect int WSAAPI WSAEventSelect( SOCKET s,
// WSAEVENT hEventObject, long lNetworkEvents );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "f98a71e4-47fb-47a4-b37e-e4cc801a8f98")]
public static extern WSRESULT WSAEventSelect(SOCKET s, WSAEVENT hEventObject, FD lNetworkEvents);
/// The WSAGetLastError function returns the error status for the last Windows Sockets operation that failed.
/// The return value indicates the error code for this thread's last Windows Sockets operation that failed.
///
///
/// The WSAGetLastError function returns the last error that occurred for the calling thread. When a particular Windows
/// Sockets function indicates an error has occurred, this function should be called immediately to retrieve the extended error code
/// for the failing function call. This extended error code can be different from the error code obtained from getsockopt when
/// called with an optname parameter of SO_ERROR, which is socket-specific since WSAGetLastError is for all
/// thread-specific sockets.
///
///
/// If a function call's return value indicates that error or other relevant data was returned in the error code,
/// WSAGetLastError should be called immediately. This is necessary because some functions may reset the last extended error
/// code to 0 if they succeed, overwriting the extended error code returned by a previously failed function. To specifically reset
/// the extended error code, use the WSASetLastError function call with the iError parameter set to zero. A getsockopt function when
/// called with an optname parameter of SO_ERROR also resets the extended error code to zero.
///
///
/// The WSAGetLastError function should not be used to check for an extended error value on receipt of an asynchronous
/// message. In this case, the extended error value is passed in the lParam parameter of the message, and this can differ from the
/// value returned by WSAGetLastError.
///
///
/// Note An application can call the WSAGetLastError function to determine the extended error code for other Windows
/// sockets functions as is normally done in Windows Sockets even if the WSAStartup function fails or the WSAStartup function
/// was not called to properly initialize Windows Sockets before calling a Windows Sockets function. The WSAGetLastError
/// function is one of the only functions in the Winsock 2.2 DLL that can be called in the case of a WSAStartup failure.
///
///
/// The Windows Sockets extended error codes returned by this function and the text description of the error are listed under
/// Windows Sockets Error Codes. These error codes and a short text description associated with an error code are defined in the
/// Winerror.h header file. The FormatMessage function can be used to obtain the message string for the returned error.
///
///
/// For information on how to handle error codes when porting socket applications to Winsock, see Error Codes - errno, h_errno and WSAGetLastError.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock/nf-winsock-wsagetlasterror int WSAGetLastError( );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "39e41b66-44ed-46dc-bfc2-65228b669992")]
public static extern WSRESULT WSAGetLastError();
/// The WSAGetOverlappedResult function retrieves the results of an overlapped operation on the specified socket.
///
/// A descriptor identifying the socket.
///
/// This is the same socket that was specified when the overlapped operation was started by a call to any of the Winsock functions
/// that supports overlappped operations. These functions include AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets,
/// WSARecv, WSARecvFrom, WSARecvMsg, WSASend, WSASendMsg, WSASendTo, and WSAIoctl.
///
///
///
/// A pointer to a WSAOVERLAPPED structure that was specified when the overlapped operation was started. This parameter must not be
/// a NULL pointer.
///
///
/// A pointer to a 32-bit variable that receives the number of bytes that were actually transferred by a send or receive operation,
/// or by the WSAIoctl function. This parameter must not be a NULL pointer.
///
///
/// A flag that specifies whether the function should wait for the pending overlapped operation to complete. If TRUE, the
/// function does not return until the operation has been completed. If FALSE and the operation is still pending, the
/// function returns FALSE and the WSAGetLastError function returns WSA_IO_INCOMPLETE. The fWait parameter may be set to
/// TRUE only if the overlapped operation selected the event-based completion notification.
///
///
/// A pointer to a 32-bit variable that will receive one or more flags that supplement the completion status. If the overlapped
/// operation was initiated through WSARecv or WSARecvFrom, this parameter will contain the results value for lpFlags parameter.
/// This parameter must not be a NULL pointer.
///
///
///
/// If WSAGetOverlappedResult succeeds, the return value is TRUE. This means that the overlapped operation has
/// completed successfully and that the value pointed to by lpcbTransfer has been updated.
///
///
/// If WSAGetOverlappedResult returns FALSE, this means that either the overlapped operation has not completed, the
/// overlapped operation completed but with errors, or the overlapped operation's completion status could not be determined due to
/// errors in one or more parameters to WSAGetOverlappedResult. On failure, the value pointed to by lpcbTransfer will not be
/// updated. Use WSAGetLastError to determine the cause of the failure (either by the WSAGetOverlappedResult function or by
/// the associated overlapped operation).
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSA_INVALID_HANDLE
/// The hEvent parameter of the WSAOVERLAPPED structure does not contain a valid event object handle.
///
/// -
/// WSA_INVALID_PARAMETER
/// One of the parameters is unacceptable.
///
/// -
/// WSA_IO_INCOMPLETE
/// The fWait parameter is FALSE and the I/O operation has not yet completed.
///
/// -
/// WSAEFAULT
///
/// One or more of the lpOverlapped, lpcbTransfer, or lpdwFlags parameters are not in a valid part of the user address space. This
/// error is returned if the lpOverlapped, lpcbTransfer, or lpdwFlags parameter was a NULL pointer on Windows Server 2003 and earlier.
///
///
///
///
///
///
/// The WSAGetOverlappedResult function reports the results of the overlapped operation specified in the lpOverlapped
/// parameter for the socket specified in the s parameter. The WSAGetOverlappedResult function is passed the socket
/// descriptor and the WSAOVERLAPPED structure that was specified when the overlapped function was called. A pending operation is
/// indicated when the function that started the operation returns FALSE and the WSAGetLastError function returns
/// WSA_IO_PENDING. When an I/O operation such as WSARecv is pending, the function that started the operation resets the hEvent
/// member of the WSAOVERLAPPED structure to the nonsignaled state. Then, when the pending operation has completed, the
/// system sets the event object to the signaled state.
///
///
/// If the fWait parameter is TRUE, WSAGetOverlappedResult determines whether the pending operation has been completed
/// by waiting for the event object to be in the signaled state. A client may set the fWait parameter to TRUE, but only if it
/// selected event-based completion notification when the I/O operation was requested. If another form of notification was selected,
/// the usage of the hEvent parameter of the WSAOVERLAPPED structure is different, and setting fWait to TRUE causes
/// unpredictable results.
///
///
/// If the WSAGetOverlappedResult function is called with the lpOverlapped, lpcbTransfer, or lpdwFlags parameter set to a
/// NULL pointer on Windows Vista, this will result in an access violation. If the WSAGetOverlappedResult function is
/// called with the lpOverlapped, lpcbTransfer, or lpdwFlags parameter set to a NULL pointer on Windows Server 2003 and
/// earlier, this will result in the WSAEFAULT error code being returned.
///
///
/// Note All I/O is canceled when a thread exits. For overlapped sockets, pending asynchronous operations can fail if the
/// thread is closed before the operations complete. See ExitThread for more information.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsagetoverlappedresult BOOL WSAAPI
// WSAGetOverlappedResult( SOCKET s, LPWSAOVERLAPPED lpOverlapped, LPDWORD lpcbTransfer, BOOL fWait, LPDWORD lpdwFlags );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "3c43ccfd-0fe7-4ecc-9517-e0a1c448f7e4")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WSAGetOverlappedResult(SOCKET s, in WSAOVERLAPPED lpOverlapped, out uint lpcbTransfer, [MarshalAs(UnmanagedType.Bool)] bool fWait, out uint lpdwFlags);
///
/// The WSAGetQOSByName function initializes a QOS structure based on a named template, or it supplies a buffer to retrieve
/// an enumeration of the available template names.
///
/// A descriptor identifying a socket.
/// A pointer to a specific quality of service template.
/// A pointer to the QOS structure to be filled.
///
///
/// If WSAGetQOSByName succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To
/// get extended error information, call WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
///
/// The lpQOSName or lpQOS parameter are not a valid part of the user address space, or the buffer length for lpQOS is too small.
///
///
///
///
///
///
/// The WSAGetQOSByName function is used by applications to initialize a QOS structure to a set of known values appropriate
/// for a particular service class or media type. These values are stored in a template that is referenced by a well-known name. The
/// client may retrieve these values by setting the buf parameter of the WSABUF structure indicated by lpQOSName, which points to a
/// string of nonzero length specifying a template name. In this case, the usage of lpQOSName is IN only, and results are returned
/// through lpQOS.
///
///
/// Alternatively, the client may use this function to retrieve an enumeration of available template names. The client may do this
/// by setting the buf parameter of the WSABUF indicated by lpQOSName to a zero-length null-terminated string. In this case the
/// buffer indicated by buf is overwritten with a sequence of as many available, null-terminated template names up to the number of
/// bytes available in buf as indicated by the len parameter of the WSABUF indicated by lpQOSName. The list of names itself
/// is terminated by a zero-length name. When the WSAGetQOSByName function is used to retrieve template names, the lpQOS
/// parameter is ignored.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsagetqosbyname BOOL WSAAPI WSAGetQOSByName( SOCKET s,
// LPWSABUF lpQOSName, LPQOS lpQOS );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "9b586856-5441-414b-8b91-298c952c351b")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WSAGetQOSByName(SOCKET s, in WSABUF lpQOSName, out QOS lpQOS);
///
/// The WSAGetServiceClassInfo function retrieves the class information (schema) pertaining to a specified service class from
/// a specified namespace provider.
///
/// A pointer to a GUID that identifies a specific namespace provider.
/// A pointer to a GUID identifying the service class.
///
/// On input, the number of bytes contained in the buffer pointed to by the lpServiceClassInfo parameter.
///
/// On output, if the function fails and the error is WSAEFAULT, this parameter specifies the minimum size, in bytes, of the buffer
/// pointed to lpServiceClassInfo needed to retrieve the record.
///
///
///
/// A pointer to a WSASERVICECLASSINFO structure that contains the service class information from the indicated namespace provider
/// for the specified service class.
///
///
///
/// The return value is zero if the WSAGetServiceClassInfo was successful. Otherwise, the value SOCKET_ERROR is returned, and
/// a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
/// -
/// WSAEACCES
/// The calling routine does not have sufficient privileges to access the information.
///
/// -
/// WSAEFAULT
///
/// The buffer pointed to by the lpServiceClassInfo parameter is too small to contain a WSASERVICECLASSINFOW. The application needs
/// to pass in a larger buffer.
///
///
/// -
/// WSAEINVAL
///
/// The specified service class identifier or namespace provider identifier is not valid. This error is returned if the
/// lpProviderId, lpServiceClassId, lpdwBufSize, or lpServiceClassInfo parameters are NULL.
///
///
/// -
/// WSAEOPNOTSUPP
///
/// The operation is not supported for the type of object referenced. This error is returned by some namespace providers that do not
/// support getting service class information.
///
///
/// -
/// WSANO_DATA
/// The requested name is valid, but no data of the requested type was found.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSATYPE_NOT_FOUND
/// The specified class was not found.
///
///
///
///
/// The WSAGetServiceClassInfo function retrieves service class information from a namespace provider. The service class
/// information retrieved from a particular namespace provider might not be the complete set of class information that was specified
/// when the service class was installed. Individual namespace providers are only required to retain service class information that
/// is applicable to the namespaces that they support. See the section Service Class Data Structures for more information.
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsagetserviceclassinfow INT WSAAPI
// WSAGetServiceClassInfoW( LPGUID lpProviderId, LPGUID lpServiceClassId, LPDWORD lpdwBufSize, LPWSASERVICECLASSINFOW
// lpServiceClassInfo );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "e177bb7d-c7d3-43a4-a809-ab8212feea2e")]
public static extern WSRESULT WSAGetServiceClassInfo(in Guid lpProviderId, in Guid lpServiceClassId, ref uint lpdwBufSize, IntPtr lpServiceClassInfo);
///
/// The WSAGetServiceClassNameByClassId function retrieves the name of the service associated with the specified type. This
/// name is the generic service name, like FTP or SNA, and not the name of a specific instance of that service.
///
/// A pointer to the GUID for the service class.
/// A pointer to the service name.
///
/// On input, the length of the buffer returned by lpszServiceClassName, in characters. On output, the length of the service name
/// copied into lpszServiceClassName, in characters.
///
///
///
/// The WSAGetServiceClassNameByClassId function returns a value of zero if successful. Otherwise, the value SOCKET_ERROR is
/// returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSA_INVALID_PARAMETER
/// The lpServiceClassId parameter specified is invalid.
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
/// -
/// WSAEACCES
/// The calling routine does not have sufficient privileges to access the information.
///
/// -
/// WSAEFAULT
/// The specified buffer pointed to by lpszServiceClassName is too small. Pass in a larger buffer.
///
/// -
/// WSAENOBUFS
/// No buffer space available.
///
/// -
/// WSAEOPNOTSUPP
///
/// The operation is not supported for the type of object referenced. This error is returned by some namespace providers that do not
/// support getting service class information.
///
///
/// -
/// WSANO_DATA
/// The lpServiceClassId is valid, but no data of the requested type was found.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsagetserviceclassnamebyclassida INT WSAAPI
// WSAGetServiceClassNameByClassIdA( LPGUID lpServiceClassId, LPSTR lpszServiceClassName, LPDWORD lpdwBufferLength );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "0a61751e-10e5-4f91-a0b2-8c1baf477653")]
public static extern WSRESULT WSAGetServiceClassNameByClassId(in Guid lpServiceClassId, [MarshalAs(UnmanagedType.LPTStr)] StringBuilder lpszServiceClassName, ref uint lpdwBufferLength);
/// The WSAHtonl function converts a u_long from host byte order to network byte order.
/// A descriptor identifying a socket.
/// A 32-bit number in host byte order.
/// A pointer to a 32-bit number to receive the number in network byte order.
///
///
/// If no error occurs, WSAHtonl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can
/// be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
///
/// The lpnetlong parameter is NULL or the address pointed to is not completely contained in a valid part of the user address space.
///
///
///
///
///
///
/// The WSAHtonl function takes a 32-bit number in host byte order and returns a 32-bit number in network byte order in the
/// 32-bit number pointed to by the lpnetlong parameter. The socket passed in the s parameter is used to determine the network byte
/// order required based on the Winsock catalog protocol entry associated with the socket. This feature supports Winsock providers
/// that use different network byte orders.
///
///
/// If the socket is for the AF_INET or AF_INET6 address family, the WSAHtonl function can be used to convert an IPv4 address
/// in host byte order to the IPv4 address in network byte order. This function does not do any checking to determine if the
/// hostlong parameter is a valid IPv4 address.
///
///
/// The WSAHtonl function requires that the Winsock DLL has previously been loaded with a successful call to the WSAStartup
/// function. For use with the AF_INET or AF_INET6 family, the htonlfunction does not require that the Winsock DLL be loaded.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsahtonl int WSAAPI WSAHtonl( IN SOCKET s, IN u_long
// hostlong, OUT u_long *lpnetlong );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "33512f49-d576-4439-ad8d-5c87387d6214")]
public static extern WSRESULT WSAHtonl([In] SOCKET s, [In] uint hostlong, out uint lpnetlong);
/// The WSAHtons function converts a u_short from host byte order to network byte order.
/// A descriptor identifying a socket.
/// A 16-bit number in host byte order.
/// A pointer to a 16-bit buffer to receive the number in network byte order.
///
///
/// If no error occurs, WSAHtons returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can
/// be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
///
/// The lpnetshort parameter is NULL or the address pointed to is not completely contained in a valid part of the user address space.
///
///
///
///
///
///
/// The WSAHtons function takes a 16-bit number in host byte order and returns a 16-bit number in network byte order in the
/// 16-bit number pointed to by the lpnetshort parameter. The socket passed in the s parameter is used to determine the network byte
/// order required based on the Winsock catalog protocol entry associated with the socket. This feature supports Winsock providers
/// that use different network byte orders.
///
///
/// If the socket is for the AF_INET or AF_INET6 address family, the WSAHtons function can be used to convert an IP port
/// number in host byte order to the IP port number in network byte order.
///
///
/// The WSAHtons function requires that the Winsock DLL has previously been loaded with a successful call to the WSAStartup
/// function. For use with the AF_INET OR AF_INET6 address family, the htonsfunction does not require that the Winsock DLL be loaded.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsahtons int WSAAPI WSAHtons( IN SOCKET s, IN u_short
// hostshort, OUT u_short *lpnetshort );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "95fb103b-f7dd-4fa4-bf68-ed8e87cdd96b")]
public static extern WSRESULT WSAHtons([In] SOCKET s, [In] ushort hostshort, out ushort lpnetshort);
///
/// The WSAInstallServiceClass function registers a service class schema within a namespace. This schema includes the class
/// name, class identifier, and any namespace-specific information that is common to all instances of the service, such as the SAP
/// identifier or object identifier.
///
///
/// Service class to namespace specific–type mapping information. Multiple mappings can be handled at one time.
/// See the section Service Class Data Structures for a description of pertinent data structures.
///
///
///
/// The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSA_INVALID_PARAMETER
/// The namespace provider cannot supply the requested class information.
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
/// -
/// WSAEACCES
/// The calling function does not have sufficient privileges to install the service.
///
/// -
/// WSAEALREADY
///
/// Service class information has already been registered for this service class identifier. To modify service class information,
/// first use WSARemoveServiceClass, and then reinstall with updated class information data.
///
///
/// -
/// WSAEINVAL
///
/// The service class information was not valid or improperly structured. This error is returned if the lpServiceClassInfo parameter
/// is NULL.
///
///
/// -
/// WSAEOPNOTSUPP
/// The operation is not supported. This error is returned if the namespace provider does not implement this function.
///
/// -
/// WSANO_DATA
/// The requested name is valid, but no data of the requested type was found.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsainstallserviceclassa INT WSAAPI
// WSAInstallServiceClassA( LPWSASERVICECLASSINFOA lpServiceClassInfo );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "06760319-aeeb-4ad7-b77a-01efea7ed904")]
public static extern WSRESULT WSAInstallServiceClass(in WSASERVICECLASSINFO lpServiceClassInfo);
/// The WSAIoctl function controls the mode of a socket.
/// A descriptor identifying a socket.
/// The control code of operation to perform.
/// A pointer to the input buffer.
/// The size, in bytes, of the input buffer.
/// A pointer to the output buffer.
/// The size, in bytes, of the output buffer.
/// A pointer to actual number of bytes of output.
/// A pointer to a WSAOVERLAPPED structure (ignored for non-overlapped sockets).
///
/// Note A pointer to the completion routine called when the operation has been completed (ignored for non-overlapped
/// sockets). See Remarks.
///
///
///
/// Upon successful completion, the WSAIoctl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific
/// error code can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSA_IO_PENDING
/// An overlapped operation was successfully initiated and completion will be indicated at a later time.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEFAULT
///
/// The lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped, or lpCompletionRoutine parameter is not totally contained in a
/// valid part of the user address space, or the cbInBuffer or cbOutBuffer parameter is too small.
///
///
/// -
/// WSAEINVAL
///
/// The dwIoControlCode parameter is not a valid command, or a specified input parameter is not acceptable, or the command is not
/// applicable to the type of socket specified.
///
///
/// -
/// WSAEINPROGRESS
/// The function is invoked when a callback is in progress.
///
/// -
/// WSAENOTSOCK
/// The descriptor s is not a socket.
///
/// -
/// WSAEOPNOTSUPP
///
/// The specified IOCTL command cannot be realized. (For example, the FLOWSPEC structures specified in SIO_SET_QOS or
/// SIO_SET_GROUP_QOS cannot be satisfied.)
///
///
/// -
/// WSAEWOULDBLOCK
/// The socket is marked as non-blocking and the requested operation would block.
///
/// -
/// WSAENOPROTOOPT
///
/// The socket option is not supported on the specified protocol. For example, an attempt to use the SIO_GET_BROADCAST_ADDRESS IOCTL
/// was made on an IPv6 socket or an attempt to use the TCP SIO_KEEPALIVE_VALS IOCTL was made on a datagram socket.
///
///
///
///
///
///
/// The WSAIoctl function is used to set or retrieve operating parameters associated with the socket, the transport protocol,
/// or the communications subsystem.
///
///
/// If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a non-overlapped
/// socket. For a non-overlapped socket, lpOverlapped and lpCompletionRoutine parameters are ignored, which causes the function to
/// behave like the standard ioctlsocket function except that the function can block if socket s is in blocking mode. If socket s is
/// in non-blocking mode, this function can return WSAEWOULDBLOCK when the specified operation cannot be finished immediately. In
/// this case, the application may change the socket to blocking mode and reissue the request or wait for the corresponding network
/// event (such as FD_ROUTING_INTERFACE_CHANGE or FD_ADDRESS_LIST_CHANGE in the case of SIO_ROUTING_INTERFACE_CHANGE or
/// SIO_ADDRESS_LIST_CHANGE) using a Windows message (using WSAAsyncSelect)-based or event (using WSAEventSelect)-based
/// notification mechanism.
///
///
/// For overlapped sockets, operations that cannot be completed immediately will be initiated, and completion will be indicated at a
/// later time. The DWORD value pointed to by the lpcbBytesReturned parameter that is returned may be ignored. The final
/// completion status and bytes returned can be retrieved when the appropriate completion method is signaled when the operation has completed.
///
///
/// Any IOCTL may block indefinitely, depending on the service provider's implementation. If the application cannot tolerate
/// blocking in a WSAIoctl call, overlapped I/O would be advised for IOCTLs that are especially likely to block including:
///
/// SIO_ADDRESS_LIST_CHANGE
/// SIO_FINDROUTE
/// SIO_FLUSH
/// SIO_GET_QOS
/// SIO_GET_GROUP_QOS
/// SIO_ROUTING_INTERFACE_CHANGE
/// SIO_SET_QOS
/// SIO_SET_GROUP_QOS
///
/// Some protocol-specific IOCTLs may also be especially likely to block. Check the relevant protocol-specific annex for any
/// available information.
///
/// The prototype for the completion routine pointed to by the lpCompletionRoutine parameter is as follows:
///
/// The CompletionRoutine is a placeholder for an application-supplied function name. The dwError parameter specifies the completion
/// status for the overlapped operation as indicated by lpOverlapped parameter. The cbTransferred parameter specifies the number of
/// bytes received. The dwFlags parameter is not used for this IOCTL. The completion routine does not return a value.
///
///
/// It is possible to adopt an encoding scheme that preserves the currently defined ioctlsocket opcodes while providing a convenient
/// way to partition the opcode identifier space in as much as the dwIoControlCode parameter is now a 32-bit entity. The
/// dwIoControlCode parameter is built to allow for protocol and vendor independence when adding new control codes while retaining
/// backward compatibility with the Windows Sockets 1.1 and Unix control codes. The dwIoControlCode parameter has the following form.
///
///
///
/// I
/// O
/// V
/// T
/// Vendor/address family
/// Code
///
/// -
/// 3
/// 3
/// 2
/// 2 2
/// 2 2 2 2 2 2 2 1 1 1 1
/// 1 1 1 1 1 1
///
/// -
/// 1
/// 0
/// 9
/// 8 7
/// 6 5 4 3 2 1 0 9 8 7 6
/// 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
///
///
///
/// Note The bits in dwIoControlCode parameter displayed in the table must be read vertically from top to bottom by column.
/// So the left-most bit is bit 31, the next bit is bit 30, and the right-most bit is bit 0.
///
/// I is set if the input buffer is valid for the code, as with IOC_IN.
///
/// O is set if the output buffer is valid for the code, as with IOC_OUT. Control codes using both input and output buffers
/// set both I and O.
///
/// V is set if there are no parameters for the code, as with IOC_VOID.
/// T is a 2-bit quantity that defines the type of the IOCTL. The following values are defined:
/// 0 The IOCTL is a standard Unix IOCTL code, as with FIONREAD and FIONBIO.
/// 1 The IOCTL is a generic Windows Sockets 2 IOCTL code. New IOCTL codes defined for Windows Sockets 2 will have T == 1.
/// 2 The IOCTL applies only to a specific address family.
///
/// 3 The IOCTL applies only to a specific vendor's provider, as with IOC_VENDOR. This type allows companies to be assigned a
/// vendor number that appears in the Vendor/Address family parameter. Then, the vendor can define new IOCTLs specific to
/// that vendor without having to register the IOCTL with a clearinghouse, thereby providing vendor flexibility and privacy.
///
///
/// Vendor/Address family An 11-bit quantity that defines the vendor who owns the code (if T == 3) or that contains the
/// address family to which the code applies (if T == 2). If this is a Unix IOCTL code (T == 0) then this parameter has the same
/// value as the code on Unix. If this is a generic Windows Sockets 2 IOCTL (T == 1) then this parameter can be used as an extension
/// of the code parameter to provide additional code values.
///
/// Code The 16-bit quantity that contains the specific IOCTL code for the operation.
/// The following Unix IOCTL codes (commands) are supported.
/// The following Windows Sockets 2 commands are supported.
///
/// If an overlapped operation completes immediately, WSAIoctl returns a value of zero and the lpcbBytesReturned parameter is
/// updated with the number of bytes in the output buffer. If the overlapped operation is successfully initiated and will complete
/// later, this function returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpcbBytesReturned is not
/// updated. When the overlapped operation completes the amount of data in the output buffer is indicated either through the
/// cbTransferred parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.
///
///
/// When called with an overlapped socket, the lpOverlapped parameter must be valid for the duration of the overlapped operation.
/// The lpOverlapped parameter contains the address of a WSAOVERLAPPED structure.
///
///
/// If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped
/// operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or
/// WSAGetOverlappedResult to wait or poll on the event object.
///
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. See ExitThread for more information.
///
///
/// If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context
/// information to the completion routine. A caller that passes a non- NULL lpCompletionRoutine and later calls
/// WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of
/// WSAGetOverlappedResult to TRUE. In this case, the usage of the hEvent parameter is undefined, and attempting to
/// wait on the hEvent parameter would produce unpredictable results.
///
/// The prototype of the completion routine is as follows:
///
/// This CompletionRoutine is a placeholder for an application-defined or library-defined function. The completion routine is
/// invoked only if the thread is in an alertable state. To put a thread into an alertable state, use the WSAWaitForMultipleEvents,
/// WaitForSingleObjectEx, or WaitForMultipleObjectsEx function with the fAlertable or bAlertable parameter set to TRUE.
///
///
/// The dwError parameter of CompletionRoutine specifies the completion status for the overlapped operation as indicated by
/// lpOverlapped. The cbTransferred parameter specifies the number of bytes returned. Currently, no flag values are defined and
/// dwFlags will be zero. The CompletionRoutine function does not return a value.
///
///
/// Returning from this function allows invocation of another pending completion routine for this socket. The completion routines
/// can be called in any order, not necessarily in the same order the overlapped operations are completed.
///
/// Compatibility
///
/// The IOCTL codes with T == 0 are a subset of the IOCTL codes used in Berkeley sockets. In particular, there is no command that is
/// equivalent to FIOASYNC.
///
///
/// Note Some IOCTL codes require additional header files. For example, use of the SIO_RCVALL IOCTL requires the
/// Mstcpip.h header file.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-wsaioctl int WSAAPI WSAIoctl( SOCKET s, DWORD
// dwIoControlCode, LPVOID lpvInBuffer, DWORD cbInBuffer, LPVOID lpvOutBuffer, DWORD cbOutBuffer, LPDWORD lpcbBytesReturned,
// LPWSAOVERLAPPED lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "038aeca6-d7b7-4f74-ac69-4536c2e5118b")]
public static extern WSRESULT WSAIoctl(SOCKET s, uint dwIoControlCode, [In] IntPtr lpvInBuffer, uint cbInBuffer, [Out] IntPtr lpvOutBuffer, uint cbOutBuffer, out uint lpcbBytesReturned, [Optional] IntPtr lpOverlapped, [Optional] IntPtr lpCompletionRoutine);
/// The WSAIoctl function controls the mode of a socket.
/// A descriptor identifying a socket.
/// The control code of operation to perform.
/// The input value.
/// The output value.
///
///
/// Upon successful completion, the WSAIoctl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific
/// error code can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEFAULT
///
/// The lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped, or lpCompletionRoutine parameter is not totally contained in a
/// valid part of the user address space, or the cbInBuffer or cbOutBuffer parameter is too small.
///
///
/// -
/// WSAEINVAL
///
/// The dwIoControlCode parameter is not a valid command, or a specified input parameter is not acceptable, or the command is not
/// applicable to the type of socket specified.
///
///
/// -
/// WSAENOTSOCK
/// The descriptor s is not a socket.
///
/// -
/// WSAEOPNOTSUPP
///
/// The specified IOCTL command cannot be realized. (For example, the FLOWSPEC structures specified in SIO_SET_QOS or
/// SIO_SET_GROUP_QOS cannot be satisfied.)
///
///
/// -
/// WSAEWOULDBLOCK
/// The socket is marked as non-blocking and the requested operation would block.
///
/// -
/// WSAENOPROTOOPT
///
/// The socket option is not supported on the specified protocol. For example, an attempt to use the SIO_GET_BROADCAST_ADDRESS IOCTL
/// was made on an IPv6 socket or an attempt to use the TCP SIO_KEEPALIVE_VALS IOCTL was made on a datagram socket.
///
///
///
///
///
///
/// The WSAIoctl function is used to set or retrieve operating parameters associated with the socket, the transport protocol,
/// or the communications subsystem.
///
///
/// If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a non-overlapped
/// socket. For a non-overlapped socket, lpOverlapped and lpCompletionRoutine parameters are ignored, which causes the function to
/// behave like the standard ioctlsocket function except that the function can block if socket s is in blocking mode. If socket s is
/// in non-blocking mode, this function can return WSAEWOULDBLOCK when the specified operation cannot be finished immediately. In
/// this case, the application may change the socket to blocking mode and reissue the request or wait for the corresponding network
/// event (such as FD_ROUTING_INTERFACE_CHANGE or FD_ADDRESS_LIST_CHANGE in the case of SIO_ROUTING_INTERFACE_CHANGE or
/// SIO_ADDRESS_LIST_CHANGE) using a Windows message (using WSAAsyncSelect)-based or event (using WSAEventSelect)-based
/// notification mechanism.
///
///
/// Any IOCTL may block indefinitely, depending on the service provider's implementation. If the application cannot tolerate
/// blocking in a WSAIoctl call, overlapped I/O would be advised for IOCTLs that are especially likely to block including:
///
/// SIO_ADDRESS_LIST_CHANGE
/// SIO_FINDROUTE
/// SIO_FLUSH
/// SIO_GET_QOS
/// SIO_GET_GROUP_QOS
/// SIO_ROUTING_INTERFACE_CHANGE
/// SIO_SET_QOS
/// SIO_SET_GROUP_QOS
///
/// Some protocol-specific IOCTLs may also be especially likely to block. Check the relevant protocol-specific annex for any
/// available information.
///
///
/// It is possible to adopt an encoding scheme that preserves the currently defined ioctlsocket opcodes while providing a convenient
/// way to partition the opcode identifier space in as much as the dwIoControlCode parameter is now a 32-bit entity. The
/// dwIoControlCode parameter is built to allow for protocol and vendor independence when adding new control codes while retaining
/// backward compatibility with the Windows Sockets 1.1 and Unix control codes. The dwIoControlCode parameter has the following form.
///
///
///
/// I
/// O
/// V
/// T
/// Vendor/address family
/// Code
///
/// -
/// 3
/// 3
/// 2
/// 2 2
/// 2 2 2 2 2 2 2 1 1 1 1
/// 1 1 1 1 1 1
///
/// -
/// 1
/// 0
/// 9
/// 8 7
/// 6 5 4 3 2 1 0 9 8 7 6
/// 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
///
///
///
/// Note The bits in dwIoControlCode parameter displayed in the table must be read vertically from top to bottom by column.
/// So the left-most bit is bit 31, the next bit is bit 30, and the right-most bit is bit 0.
///
/// I is set if the input buffer is valid for the code, as with IOC_IN.
///
/// O is set if the output buffer is valid for the code, as with IOC_OUT. Control codes using both input and output buffers
/// set both I and O.
///
/// V is set if there are no parameters for the code, as with IOC_VOID.
/// T is a 2-bit quantity that defines the type of the IOCTL. The following values are defined:
/// 0 The IOCTL is a standard Unix IOCTL code, as with FIONREAD and FIONBIO.
/// 1 The IOCTL is a generic Windows Sockets 2 IOCTL code. New IOCTL codes defined for Windows Sockets 2 will have T == 1.
/// 2 The IOCTL applies only to a specific address family.
///
/// 3 The IOCTL applies only to a specific vendor's provider, as with IOC_VENDOR. This type allows companies to be assigned a
/// vendor number that appears in the Vendor/Address family parameter. Then, the vendor can define new IOCTLs specific to
/// that vendor without having to register the IOCTL with a clearinghouse, thereby providing vendor flexibility and privacy.
///
///
/// Vendor/Address family An 11-bit quantity that defines the vendor who owns the code (if T == 3) or that contains the
/// address family to which the code applies (if T == 2). If this is a Unix IOCTL code (T == 0) then this parameter has the same
/// value as the code on Unix. If this is a generic Windows Sockets 2 IOCTL (T == 1) then this parameter can be used as an extension
/// of the code parameter to provide additional code values.
///
/// Code The 16-bit quantity that contains the specific IOCTL code for the operation.
/// The following Unix IOCTL codes (commands) are supported.
/// The following Windows Sockets 2 commands are supported.
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. See ExitThread for more information.
///
/// Compatibility
///
/// The IOCTL codes with T == 0 are a subset of the IOCTL codes used in Berkeley sockets. In particular, there is no command that is
/// equivalent to FIOASYNC.
///
///
/// Note Some IOCTL codes require additional header files. For example, use of the SIO_RCVALL IOCTL requires the
/// Mstcpip.h header file.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock2/nf-winsock2-wsaioctl int WSAAPI WSAIoctl( SOCKET s, DWORD
// dwIoControlCode, LPVOID lpvInBuffer, DWORD cbInBuffer, LPVOID lpvOutBuffer, DWORD cbOutBuffer, LPDWORD lpcbBytesReturned,
// LPWSAOVERLAPPED lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine );
[PInvokeData("winsock2.h", MSDNShortId = "038aeca6-d7b7-4f74-ac69-4536c2e5118b")]
public static WSRESULT WSAIoctl(SOCKET s, uint dwIoControlCode, TIn inVal, out TOut outVal) where TIn : struct where TOut : struct
{
using SafeHGlobalHandle ptrIn = SafeHGlobalHandle.CreateFromStructure(inVal), ptrOut = SafeHGlobalHandle.CreateFromStructure();
var ret = WSAIoctl(s, dwIoControlCode, ptrIn, ptrIn.Size, ptrOut, ptrOut.Size, out var bRet);
if (ret.Failed)
{
outVal = default;
return WSAGetLastError();
}
outVal = ptrOut.ToStructure();
return 0;
}
///
/// The WSAJoinLeaf function joins a leaf node into a multipoint session, exchanges connect data, and specifies needed
/// quality of service based on the specified FLOWSPEC structures.
///
/// Descriptor identifying a multipoint socket.
/// Name of the peer to which the socket is to be joined.
/// Length of name, in bytes.
/// Pointer to the user data that is to be transferred to the peer during multipoint session establishment.
///
/// Pointer to the user data that is to be transferred back from the peer during multipoint session establishment.
///
/// Pointer to the FLOWSPEC structures for socket s, one for each direction.
///
/// Reserved for future use with socket groups. A pointer to the FLOWSPEC structures for the socket group (if applicable).
///
///
/// Flags to indicate that the socket is acting as a sender (JL_SENDER_ONLY), receiver (JL_RECEIVER_ONLY), or both (JL_BOTH).
///
///
///
/// If no error occurs, WSAJoinLeaf returns a value of type SOCKET that is a descriptor for the newly created multipoint
/// socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.
///
/// On a blocking socket, the return value indicates success or failure of the join operation.
///
/// With a nonblocking socket, successful initiation of a join operation is indicated by a return of a valid socket descriptor.
/// Subsequently, an FD_CONNECT indication will be given on the original socket s when the join operation completes, either
/// successfully or otherwise. The application must use either WSAAsyncSelect or WSAEventSelect with interest registered for the
/// FD_CONNECT event in order to determine when the join operation has completed and checks the associated error code to determine
/// the success or failure of the operation. The select function cannot be used to determine when the join operation completes.
///
///
/// Also, until the multipoint session join attempt completes all subsequent calls to WSAJoinLeaf on the same socket will
/// fail with the error code WSAEALREADY. After the WSAJoinLeaf operation completes successfully, a subsequent attempt will
/// usually fail with the error code WSAEISCONN. An exception to the WSAEISCONN rule occurs for a c_root socket that allows
/// root-initiated joins. In such a case, another join may be initiated after a prior WSAJoinLeaf operation completes.
///
///
/// If the return error code indicates the multipoint session join attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH,
/// WSAETIMEDOUT) the application can call WSAJoinLeaf again for the same socket.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAEADDRINUSE
///
/// The socket's local address is already in use and the socket was not marked to allow address reuse with SO_REUSEADDR. This error
/// usually occurs at the time of bind, but could be delayed until this function if the bind was to a partially wildcard address
/// (involving ADDR_ANY) and if a specific address needs to be committed at the time of this function.
///
///
/// -
/// WSAEADDRNOTAVAIL
/// The remote address is not a valid address (such as ADDR_ANY).
///
/// -
/// WSAEAFNOSUPPORT
/// Addresses in the specified family cannot be used with this socket.
///
/// -
/// WSAEALREADY
/// A nonblocking WSAJoinLeaf call is in progress on the specified socket.
///
/// -
/// WSAECONNREFUSED
/// The attempt to join was forcefully rejected.
///
/// -
/// WSAEFAULT
///
/// The name or the namelen parameter is not a valid part of the user address space, the namelen parameter is too small, the buffer
/// length for lpCalleeData, lpSQOS, and lpGQOS are too small, or the buffer length for lpCallerData is too large.
///
///
/// -
/// WSAEINVAL
///
/// A WSAJoinLeaf function call was performed on a UDP socket that was opened without setting its WSA_FLAG_MULTIPOINT_C_LEAF or
/// WSA_FLAG_MULTIPOINT_D_LEAF multipoint flag.
///
///
/// -
/// WSAEISCONN
/// The socket is already a member of the multipoint session.
///
/// -
/// WSAEINTR
/// A blocking Windows Socket 1.1 call was canceled through WSACancelBlockingCall.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENETUNREACH
/// The network cannot be reached from this host at this time.
///
/// -
/// WSAENOBUFS
/// No buffer space is available. The socket cannot be joined.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEOPNOTSUPP
/// The FLOWSPEC structures specified in lpSQOS and lpGQOS cannot be satisfied.
///
/// -
/// WSAEPROTONOSUPPORT
/// The lpCallerData augment is not supported by the service provider.
///
/// -
/// WSAETIMEDOUT
/// The attempt to join timed out without establishing a multipoint session.
///
///
///
///
///
/// The WSAJoinLeaf function is used to join a leaf node to a multipoint session, and to perform a number of other ancillary
/// operations that occur at session join time as well. If the socket s is unbound, unique values are assigned to the local
/// association by the system, and the socket is marked as bound.
///
///
/// The WSAJoinLeaf function has the same parameters and semantics as WSAConnect except that it returns a socket descriptor
/// (as in WSAAccept), and it has an additional dwFlags parameter. Only multipoint sockets created using WSASocket with appropriate
/// multipoint flags set can be used for input parameter s in this function. The returned socket descriptor will not be usable until
/// after the join operation completes. For example, if the socket is in nonblocking mode after a corresponding FD_CONNECT
/// indication has been received from WSAAsyncSelect or WSAEventSelect on the original socket s, except that closesocket may be
/// invoked on this new socket descriptor to cancel a pending join operation. A root application in a multipoint session may call
/// WSAJoinLeaf one or more times in order to add a number of leaf nodes, however at most one multipoint connection request
/// may be outstanding at a time. Refer to Multipoint and Multicast Semantics for additional information.
///
///
/// For nonblocking sockets it is often not possible to complete the connection immediately. In such a case, this function returns
/// an as-yet unusable socket descriptor and the operation proceeds. There is no error code such as WSAEWOULDBLOCK in this case,
/// since the function has effectively returned a successful start indication. When the final outcome success or failure becomes
/// known, it may be reported through WSAAsyncSelect or WSAEventSelect depending on how the client registers for notification on the
/// original socket s. In either case, the notification is announced with FD_CONNECT and the error code associated with the
/// FD_CONNECT indicates either success or a specific reason for failure. The select function cannot be used to detect completion
/// notification for WSAJoinLeaf.
///
///
/// The socket descriptor returned by WSAJoinLeaf is different depending on whether the input socket descriptor, s, is a
/// c_root or a c_leaf. When used with a c_root socket, the name parameter designates a particular leaf node to be added and the
/// returned socket descriptor is a c_leaf socket corresponding to the newly added leaf node. The newly created socket has the same
/// properties as s, including asynchronous events registered with WSAAsyncSelect or with WSAEventSelect. It is not intended to be
/// used for exchange of multipoint data, but rather is used to receive network event indications (for example, FD_CLOSE) for the
/// connection that exists to the particular c_leaf. Some multipoint implementations can also allow this socket to be used for side
/// chats between the root and an individual leaf node. An FD_CLOSE indication will be received for this socket if the corresponding
/// leaf node calls closesocket to drop out of the multipoint session. Symmetrically, invoking closesocket on the c_leaf
/// socket returned from WSAJoinLeaf will cause the socket in the corresponding leaf node to get an FD_CLOSE notification.
///
///
/// When WSAJoinLeaf is invoked with a c_leaf socket, the name parameter contains the address of the root application (for a
/// rooted control scheme) or an existing multipoint session (nonrooted control scheme), and the returned socket descriptor is the
/// same as the input socket descriptor. In other words, a new socket descriptor is not allocated. In a rooted control scheme, the
/// root application would put its c_root socket in listening mode by calling listen. The standard FD_ACCEPT notification will be
/// delivered when the leaf node requests to join itself to the multipoint session. The root application uses the usual accept or
/// WSAAccept functions to admit the new leaf node. The value returned from either accept or WSAAccept is also a
/// c_leaf socket descriptor just like those returned from WSAJoinLeaf. To accommodate multipoint schemes that allow both
/// root-initiated and leaf-initiated joins, it is acceptable for a c_root socket that is already in listening mode to be used as an
/// input to WSAJoinLeaf.
///
///
/// The application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.
///
///
/// The lpCallerData is a value parameter that contains any user data that is to be sent along with the multipoint session join
/// request. If lpCallerData is NULL, no user data will be passed to the peer. The lpCalleeData is a result parameter that
/// will contain any user data passed back from the peer as part of the multipoint session establishment. The len member of
/// the WSABUF structure pointed to by the lpCalleeData parameter initially contains the length of the buffer allocated by the
/// application and pointed to by the buf member of the WSABUF structure. The len member of the WSABUF
/// structure pointed to by the lpCalleeData parameter will be set to zero if no user data has been passed back. The lpCalleeData
/// information will be valid when the multipoint join operation is complete.
///
///
/// For blocking sockets, this will be when the WSAJoinLeaf function returns. For nonblocking sockets, this will be after the
/// join operation has completed. For example, this could occur after FD_CONNECT notification on the original socket s). If
/// lpCalleeData is NULL, no user data will be passed back. The exact format of the user data is specific to the address
/// family to which the socket belongs.
///
///
/// At multipoint session establishment time, an application can use the lpSQOS and/or lpGQOS parameters to override any previous
/// quality of service specification made for the socket through WSAIoctl with the SIO_SET_QOS or SIO_SET_GROUP_QOS opcodes.
///
///
/// The lpSQOS parameter specifies the FLOWSPEC structures for socket s, one for each direction, followed by any additional
/// provider-specific parameters. If either the associated transport provider in general or the specific type of socket in
/// particular cannot honor the quality of service request, an error will be returned as indicated in the following. The respective
/// sending or receiving flow specification values will be ignored for any unidirectional sockets. If no provider-specific
/// parameters are specified, the buf and len members of the WSABUF structure pointed to by the lpCalleeData parameter
/// should be set to NULL and zero, respectively. A NULL value for lpSQOS indicates no application-supplied quality of service.
///
///
/// Reserved for future socket groups. The lpGQOS parameter specifies the FLOWSPEC structures for the socket group (if applicable),
/// one for each direction, followed by any additional provider-specific parameters. If no provider-specific parameters are
/// specified, the the buf and len members of the WSABUF structure pointed to by the lpCalleeData parameter should be
/// set to should be set to NULL and zero, respectively. A NULL value for lpGQOS indicates no application-supplied
/// group quality of service. This parameter will be ignored if s is not the creator of the socket group.
///
///
/// When connected sockets break (that is, become closed for whatever reason), they should be discarded and recreated. It is safest
/// to assume that when things go awry for any reason on a connected socket, the application must discard and recreate the needed
/// sockets in order to return to a stable point.
///
///
/// Note When issuing a blocking Winsock call such as WSAJoinLeaf, Winsock may need to wait for a network event before
/// the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous
/// procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an
/// ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsajoinleaf SOCKET WSAAPI WSAJoinLeaf( SOCKET s, const
// sockaddr *name, int namelen, LPWSABUF lpCallerData, LPWSABUF lpCalleeData, LPQOS lpSQOS, LPQOS lpGQOS, DWORD dwFlags );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "ef9efa03-feed-4f0d-b874-c646cce745c9")]
public static extern SOCKET WSAJoinLeaf(SOCKET s, [In] SOCKADDR name, int namelen, [In, Optional] IntPtr lpCallerData, [Out, Optional] IntPtr lpCalleeData, [In, Optional] IntPtr lpSQOS, [In, Optional] IntPtr lpGQOS, JL dwFlags);
///
/// The WSALookupServiceBegin function initiates a client query that is constrained by the information contained within a
/// WSAQUERYSET structure. WSALookupServiceBegin only returns a handle, which should be used by subsequent calls to
/// WSALookupServiceNext to get the actual results.
///
/// A pointer to the search criteria. See the Remarks for details.
///
/// A set of flags that controls the depth of the search.
///
/// Supported values for the dwControlFlags parameter are defined in the Winsock2.h header file and can be a combination of the
/// following options.
///
///
///
/// Flag
/// Meaning
///
/// -
/// LUP_DEEP 0x0001
/// Queries deep as opposed to just the first level.
///
/// -
/// LUP_CONTAINERS 0x0002
/// Returns containers only.
///
/// -
/// LUP_NOCONTAINERS 0x0004
/// Do not return containers.
///
/// -
/// LUP_NEAREST 0x0008
/// If possible, returns results in the order of distance. The measure of distance is provider specific.
///
/// -
/// LUP_RETURN_NAME 0x0010
/// Retrieves the name as lpszServiceInstanceName.
///
/// -
/// LUP_RETURN_TYPE 0x0020
/// Retrieves the type as lpServiceClassId.
///
/// -
/// LUP_RETURN_VERSION 0x0040
/// Retrieves the version as lpVersion.
///
/// -
/// LUP_RETURN_COMMENT 0x0080
/// Retrieves the comment as lpszComment.
///
/// -
/// LUP_RETURN_ADDR 0x0100
/// Retrieves the addresses as lpcsaBuffer.
///
/// -
/// LUP_RETURN_BLOB 0x0200
/// Retrieves the private data as lpBlob.
///
/// -
/// LUP_RETURN_ALIASES 0x0400
///
/// Any available alias information is to be returned in successive calls to WSALookupServiceNext, and each alias returned will have
/// the RESULT_IS_ALIAS flag set.
///
///
/// -
/// LUP_RETURN_QUERY_STRING 0x0800
/// Retrieves the query string used for the request.
///
/// -
/// LUP_RETURN_ALL 0x0FF0
/// A set of flags that retrieves all of the LUP_RETURN_* values.
///
/// -
/// LUP_FLUSHPREVIOUS 0x1000
///
/// Used as a value for the dwControlFlags parameter in WSALookupServiceNext. Setting this flag instructs the provider to discard
/// the last result set, which was too large for the specified buffer, and move on to the next result set.
///
///
/// -
/// LUP_FLUSHCACHE 0x2000
/// If the provider has been caching information, ignores the cache, and queries the namespace itself.
///
/// -
/// LUP_RES_SERVICE 0x8000
///
/// This indicates whether prime response is in the remote or local part of CSADDR_INFO structure. The other part needs to be usable
/// in either case.
///
///
///
///
/// A handle to be used when calling WSALookupServiceNext in order to start retrieving the results set.
///
///
/// The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
/// -
/// WSAEINVAL
/// One or more parameters were missing or invalid for this provider.
///
/// -
/// WSANO_DATA
/// The name was found in the database but no data matching the given restrictions was located.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSASERVICE_NOT_FOUND
///
/// No such service is known. The service cannot be found in the specified name space. This error is returned for a bluetooth
/// service discovery request if no remote bluetooth devices were found.
///
///
///
///
///
///
/// The lpqsRestrictions parameter points to a buffer containing a WSAQUERYSET structure. At a minimum, the dwSize member of
/// the WSAQUERYSET must be set to the length of the buffer before calling the WSALookupServiceBegin function.
/// Applications can restrict the query by specifying other members in the WSAQUERYSET.
///
///
/// In most instances, applications interested in only a particular transport protocol should constrain their query by address
/// family and protocol using the dwNumberOfProtocols and lpafpProtocols members of the WSAQUERYSET rather than by
/// specifiying the namespace in the dwNameSpace member.
///
///
/// Information on supported network transport protocols can be retreived using the EnumProtocols, WSAEnumProtocols,
/// WSCEnumProtocols, or WSCEnumProtocols32 function.
///
///
/// It is also possible to constrain the query to a single namespace. For example, a query that only wants results from DNS (not
/// results from the local hosts file and other naming services) would set the dwNameSpace member to NS_DNS. For example, a
/// bluetooth device discovery would set the the dwNameSpace member to NS_BTH.
///
///
/// Applications can also restrict the query to a specific namespace provider by specifying a pointer to the GUID for the provider
/// in the lpNSProviderId member.
///
///
/// Information on namespace providers on the local computer can be retrieved using the WSAEnumNameSpaceProviders,
/// WSAEnumNameSpaceProvidersEx, WSCEnumNameSpaceProviders32, or WSCEnumNameSpaceProvidersEx32 function.
///
///
/// If LUP_CONTAINERS is specified in a call, other restriction values should be avoided. If any are specified, it is up to the name
/// service provider to decide if it can support this restriction over the containers. If it cannot, it should return an error.
///
///
/// Some name service providers can have other means of finding containers. For example, containers might all be of some well-known
/// type, or of a set of well-known types, and therefore a query restriction can be created for finding them. No matter what other
/// means the name service provider has for locating containers, LUP_CONTAINERS and LUP_NOCONTAINERS take precedence. Hence, if a
/// query restriction is given that includes containers, specifying LUP_NOCONTAINERS will prevent the container items from being
/// returned. Similarly, no matter the query restriction, if LUP_CONTAINERS is given, only containers should be returned. If a
/// namespace does not support containers, and LUP_CONTAINERS is specified, it should simply return WSANO_DATA.
///
/// The preferred method of obtaining the containers within another container, is the call:
///
/// This call is followed by the requisite number of WSALookupServiceNext calls. This will return all containers contained
/// immediately within the starting context; that is, it is not a deep query. With this, one can map the address space structure by
/// walking the hierarchy, perhaps enumerating the content of selected containers. Subsequent uses of WSALookupServiceBegin
/// use the containers returned from a previous call.
///
///
/// As mentioned above, a WSAQUERYSET structure is used as an input parameter to WSALookupBegin in order to qualify the
/// query. The following table indicates how the WSAQUERYSET is used to construct a query. When a parameter is marked as
/// (Optional) a NULL pointer can be specified, indicating that the parameter will not be used as a search criteria. See
/// section Query-Related Data Structures for additional information.
///
///
///
/// WSAQUERYSET member
/// Query interpretation
///
/// -
/// dwSize
/// Must be set to sizeof(WSAQUERYSET). This is a versioning mechanism.
///
/// -
/// dwOutputFlags
/// Ignored for queries.
///
/// -
/// lpszServiceInstanceName
///
/// (Optional) Referenced string contains service name. The semantics for wildcarding within the string are not defined, but can be
/// supported by certain namespace providers.
///
///
/// -
/// lpServiceClassId
/// (Required) The GUID corresponding to the service class.
///
/// -
/// lpVersion
///
/// (Optional) References desired version number and provides version comparison semantics (that is, version must match exactly, or
/// version must be not less than the value specified).
///
///
/// -
/// lpszComment
/// Ignored for queries.
///
/// -
/// dwNameSpace See the Important note that follows.
/// Identifier of a single namespace in which to constrain the search, or NS_ALL to include all namespaces.
///
/// -
/// lpNSProviderId
/// (Optional) References the GUID of a specific namespace provider, and limits the query to this provider only.
///
/// -
/// lpszContext
/// (Optional) Specifies the starting point of the query in a hierarchical namespace.
///
/// -
/// dwNumberOfProtocols
/// Size of the protocol constraint array, can be zero.
///
/// -
/// lpafpProtocols
/// (Optional) References an array of AFPROTOCOLS structure. Only services that utilize these protocols will be returned.
///
/// -
/// lpszQueryString
///
/// (Optional) Some namespaces (such as whois++) support enriched SQL-like queries that are contained in a simple text string. This
/// parameter is used to specify that string.
///
///
/// -
/// dwNumberOfCsAddrs
/// Ignored for queries.
///
/// -
/// lpcsaBuffer
/// Ignored for queries.
///
/// -
/// lpBlob
/// (Optional) This is a pointer to a provider-specific entity.
///
///
///
/// Important In most instances, applications interested in only a particular transport protocol should constrain their query
/// by address family and protocol rather than by namespace. This would allow an application that needs to locate a TCP/IP service,
/// for example, to have its query processed by all available namespaces such as the local hosts file, DNS, and NIS.
///
///
/// Windows Phone 8: The WSALookupServiceBeginW function is supported for Windows Phone Store apps on Windows Phone 8
/// and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSALookupServiceBeginW function is supported for Windows Store
/// apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsalookupservicebegina INT WSAAPI WSALookupServiceBeginA(
// LPWSAQUERYSETA lpqsRestrictions, DWORD dwControlFlags, LPHANDLE lphLookup );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "448309ef-b9dd-4960-8016-d26691df59ec")]
public static extern WSRESULT WSALookupServiceBegin(in WSAQUERYSET lpqsRestrictions, LUP dwControlFlags, out HANDLE lphLookup);
///
///
/// The WSALookupServiceEnd function is called to free the handle after previous calls to WSALookupServiceBegin and WSALookupServiceNext.
///
///
/// If you call WSALookupServiceEnd from another thread while an existing WSALookupServiceNext is blocked, the end call will
/// have the same effect as a cancel and will cause the WSALookupServiceNext call to return immediately.
///
///
/// Handle previously obtained by calling WSALookupServiceBegin.
///
///
/// The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSA_INVALID_HANDLE
/// The handle is not valid.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsalookupserviceend INT WSAAPI WSALookupServiceEnd(
// HANDLE hLookup );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "f9d2ac54-a818-464d-918e-80ebb5b1b106")]
public static extern WSRESULT WSALookupServiceEnd(HANDLE hLookup);
///
///
/// The WSALookupServiceNext function is called after obtaining a handle from a previous call to WSALookupServiceBegin in
/// order to retrieve the requested service information.
///
///
/// The provider will pass back a WSAQUERYSET structure in the lpqsResults buffer. The client should continue to call this function
/// until it returns WSA_E_NO_MORE, indicating that all of WSAQUERYSET has been returned.
///
///
/// A handle returned from the previous call to WSALookupServiceBegin.
///
///
/// A set of flags that controls the operation. The values passed in the dwControlFlags parameter to the
/// WSALookupServiceBeginfunction determine the possible criteria. Any values passed in the dwControlFlags parameter to the
/// WSALookupServiceNext function further restrict the criteria for the service lookup.
///
///
/// Currently, LUP_FLUSHPREVIOUS is defined as a means to cope with a result set that is too large. If an application does not (or
/// cannot) supply a large enough buffer, setting LUP_FLUSHPREVIOUS instructs the provider to discard the last result set—which was
/// too large—and move on to the next set for this call.
///
///
/// Supported values for the dwControlFlags parameter are defined in the Winsock2.h header file and can be a combination of the
/// following options.
///
///
///
/// Flag
/// Meaning
///
/// -
/// LUP_DEEP 0x0001
/// Queries deep as opposed to just the first level.
///
/// -
/// LUP_CONTAINERS 0x0002
/// Returns containers only.
///
/// -
/// LUP_NOCONTAINERS 0x0004
/// Do not return containers.
///
/// -
/// LUP_NEAREST 0x0008
/// If possible, returns results in the order of distance. The measure of distance is provider specific.
///
/// -
/// LUP_RETURN_NAME 0x0010
/// Retrieves the name as lpszServiceInstanceName.
///
/// -
/// LUP_RETURN_TYPE 0x0020
/// Retrieves the type as lpServiceClassId.
///
/// -
/// LUP_RETURN_VERSION 0x0040
/// Retrieves the version as lpVersion.
///
/// -
/// LUP_RETURN_COMMENT 0x0080
/// Retrieves the comment as lpszComment.
///
/// -
/// LUP_RETURN_ADDR 0x0100
/// Retrieves the addresses as lpcsaBuffer.
///
/// -
/// LUP_RETURN_BLOB 0x0200
/// Retrieves the private data as lpBlob.
///
/// -
/// LUP_RETURN_ALIASES 0x0400
///
/// Any available alias information is to be returned in successive calls to WSALookupServiceNext, and each alias returned will have
/// the RESULT_IS_ALIAS flag set.
///
///
/// -
/// LUP_RETURN_QUERY_STRING 0x0800
/// Retrieves the query string used for the request.
///
/// -
/// LUP_RETURN_ALL 0x0FF0
/// A set of flags that retrieves all of the LUP_RETURN_* values.
///
/// -
/// LUP_FLUSHPREVIOUS 0x1000
///
/// Used as a value for the dwControlFlags parameter in WSALookupServiceNext. Setting this flag instructs the provider to discard
/// the last result set, which was too large for the specified buffer, and move on to the next result set.
///
///
/// -
/// LUP_FLUSHCACHE 0x2000
/// If the provider has been caching information, ignores the cache, and queries the namespace itself.
///
/// -
/// LUP_RES_SERVICE 0x8000
///
/// This indicates whether prime response is in the remote or local part of CSADDR_INFO structure. The other part needs to be usable
/// in either case.
///
///
///
///
///
/// On input, the number of bytes contained in the buffer pointed to by lpqsResults. On output, if the function fails and the error
/// is WSAEFAULT, then it contains the minimum number of bytes to pass for the lpqsResults to retrieve the record.
///
/// A pointer to a block of memory, which will contain one result set in a WSAQUERYSET structure on return.
///
///
/// The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSA_E_CANCELLED
///
/// A call to WSALookupServiceEnd was made while this call was still processing. The call has been canceled. The data in the
/// lpqsResults buffer is undefined. In Windows Sockets version 2, conflicting error codes are defined for WSAECANCELLED (10103) and
/// WSA_E_CANCELLED (10111). The error code WSAECANCELLED will be removed in a future version and only WSA_E_CANCELLED will remain.
/// For Windows Sockets version 2, however, applications should check for both WSAECANCELLED and WSA_E_CANCELLED for the widest
/// possible compatibility with namespace providers that use either one.
///
///
/// -
/// WSA_E_NO_MORE
///
/// There is no more data available. In Windows Sockets version 2, conflicting error codes are defined for WSAENOMORE (10102) and
/// WSA_E_NO_MORE (10110). The error code WSAENOMORE will be removed in a future version and only WSA_E_NO_MORE will remain. For
/// Windows Sockets version 2, however, applications should check for both WSAENOMORE and WSA_E_NO_MORE for the widest possible
/// compatibility with name-space providers that use either one.
///
///
/// -
/// WSAEFAULT
/// The lpqsResults buffer was too small to contain a WSAQUERYSET set.
///
/// -
/// WSAEINVAL
/// One or more required parameters were invalid or missing.
///
/// -
/// WSA_INVALID_HANDLE
/// The specified Lookup handle is invalid.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSANO_DATA
/// The name was found in the database, but no data matching the given restrictions was located.
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
///
/// The dwControlFlags parameter specified in this function and the ones specified at the time of WSALookupServiceBegin are treated
/// as restrictions for the purpose of combination. The restrictions are combined between the ones at WSALookupServiceBegin
/// time and the ones at WSALookupServiceNext time. Therefore the flags at WSALookupServiceNext can never increase the
/// amount of data returned beyond what was requested at WSALookupServiceBegin, although it is not an error to specify more
/// or fewer flags. The flags specified at a given WSALookupServiceNext apply only to that call.
///
///
/// The dwControlFlags LUP_FLUSHPREVIOUS and LUP_RES_SERVICE are exceptions to the combined restrictions rule (because they are
/// behavior flags instead of restriction flags). If either of these flags are used in WSALookupServiceNext they have their
/// defined effect regardless of the setting of the same flags at WSALookupServiceBegin.
///
///
/// For example, if LUP_RETURN_VERSION is specified at WSALookupServiceBegin the service provider retrieves records including the
/// version. If LUP_RETURN_VERSION is NOT specified at WSALookupServiceNext, the returned information does not include the
/// version, even though it was available. No error is generated.
///
///
/// Also for example, if LUP_RETURN_BLOB is NOT specified at WSALookupServiceBegin but is specified at WSALookupServiceNext,
/// the returned information does not include the private data. No error is generated.
///
///
/// If the WSALookupServiceNext function fails with an error of WSAEFAULT, this indicates that the buffer pointed to by the
/// lpqsResults parameter was too small to contain the query results. A new buffer for a WSAQUERYSET should be provided with a size
/// specified by the value pointed to by the lpdwBufferLength parameter. This new buffer for the WSAQUERYSET needs to have
/// some of the members of the WSAQUERYSET specified before calling the WSALookupServiceNext function again. At a
/// minimum, the dwSize member of the WSAQUERYSET must be set to the new size of the buffer.
///
/// Query Results
/// The following table describes how the query results are represented in the WSAQUERYSET structure.
///
///
/// WSAQUERYSET member
/// Result interpretation
///
/// -
/// dwSize
/// Will be set to sizeof( WSAQUERYSET). This is used as a versioning mechanism.
///
/// -
/// dwOutputFlags
/// RESULT_IS_ALIAS flag indicates this is an alias result.
///
/// -
/// lpszServiceInstanceName
/// Referenced string contains service name.
///
/// -
/// lpServiceClassId
/// The GUID corresponding to the service class.
///
/// -
/// lpVersion
/// References version number of the particular service instance.
///
/// -
/// lpszComment
/// Optional comment string specified by service instance.
///
/// -
/// dwNameSpace
/// Namespace in which the service instance was found.
///
/// -
/// lpNSProviderId
/// Identifies the specific namespace provider that supplied this query result.
///
/// -
/// lpszContext
/// Specifies the context point in a hierarchical namespace at which the service is located.
///
/// -
/// dwNumberOfProtocols
/// Undefined for results.
///
/// -
/// lpafpProtocols
/// Undefined for results, all needed protocol information is in the CSADDR_INFO structures.
///
/// -
/// lpszQueryString
///
/// When dwControlFlags includes LUP_RETURN_QUERY_STRING, this parameter returns the unparsed remainder of the
/// lpszServiceInstanceName specified in the original query. For example, in a namespace that identifies services by hierarchical
/// names that specify a host name and a file path within that host, the address returned might be the host address and the unparsed
/// remainder might be the file path. If the lpszServiceInstanceName is fully parsed and LUP_RETURN_QUERY_STRING is used, this
/// parameter is NULL or points to a zero-length string.
///
///
/// -
/// dwNumberOfCsAddrs
/// Indicates the number of elements in the array of CSADDR_INFO structures.
///
/// -
/// lpcsaBuffer
/// A pointer to an array of CSADDR_INFO structures, with one complete transport address contained within each element.
///
/// -
/// lpBlob
/// (Optional) This is a pointer to a provider-specific entity.
///
///
///
/// Windows Phone 8: The WSALookupServiceNextW function is supported for Windows Phone Store apps on Windows Phone 8
/// and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSALookupServiceNextW function is supported for Windows Store
/// apps on Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsalookupservicenexta INT WSAAPI WSALookupServiceNextA(
// HANDLE hLookup, DWORD dwControlFlags, LPDWORD lpdwBufferLength, LPWSAQUERYSETA lpqsResults );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "ab4f1830-b38d-4224-a6a9-6d4512245ad6")]
public static extern WSRESULT WSALookupServiceNext(HANDLE hLookup, LUP dwControlFlags, ref uint lpdwBufferLength, [Out] IntPtr lpqsResults);
/// The Windows Sockets WSANSPIoctl function enables developers to make I/O control calls to a registered namespace.
/// The lookup handle returned from a previous call to the WSALookupServiceBegin function.
///
/// The control code of the operation to perform.
/// The values that may be used for the dwControlCode parameter are determined by the namespace provider.
///
/// The following value is supported by several Microsoft namespace providers including the Network Location Awareness (NS_NLA)
/// namespace provider. This IOCTL is defined in the Winsock2.h header file.
///
///
///
/// Value
/// Meaning
///
/// -
/// SIO_NSP_NOTIFY_CHANGE
///
/// This operation checks if the results returned with previous calls using the hLookup parameter are still valid. These previous
/// calls include the initial call to the WSALookupServiceBegin function to retrieve the hLookup parameter. These previous calls may
/// also include calls to the WSALookupServiceNext function using the hLookup parameter.
///
///
///
///
/// A pointer to the input buffer.
/// The size, in bytes, of the input buffer.
/// A pointer to the output buffer.
/// The size, in bytes, of the output buffer.
/// A pointer to the number of bytes returned.
///
/// A pointer to a WSACOMPLETION structure, used for asynchronous processing. Set lpCompletion to NULL to force blocking
/// (synchronous) execution.
///
///
///
/// Success returns NO_ERROR. Failure returns SOCKET_ERROR, and a specific error code can be retrieved by calling the
/// WSAGetLastError function. The following table describes the error codes.
///
///
///
/// Error code
/// Description
///
/// -
/// WSA_INVALID_HANDLE
/// The hLookup parameter was not a valid query handle returned by WSALookupServiceBegin.
///
/// -
/// WSA_IO_PENDING
/// An overlapped operation was successfully initiated and completion will be indicated at a later time.
///
/// -
/// WSAEFAULT
///
/// The lpvInBuffer, cbInBuffer, lpvOutBuffer, cbOutBuffer, or lpCompletion argument is not totally contained in a valid part of the
/// user address space. Alternatively, the cbInBuffer or cbOutBuffer argument is too small, and the argument is modified to reflect
/// the required allocation size.
///
///
/// -
/// WSAEINVAL
///
/// A supplied parameter is not acceptable, or the operation inappropriately returns results from multiple namespaces when it does
/// not make sense for the specified operation.
///
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEOPNOTSUPP
///
/// The operation is not supported. This error is returned if the namespace provider does not implement this function. This error
/// can also be returned if the specified dwControlCode is an unrecognized command.
///
///
/// -
/// WSAEWOULDBLOCK
///
/// The socket is not using overlapped I/O (asynchronous processing), yet the lpCompletion parameter is non-NULL. This error is used
/// as a special notification for the SIO_NSP_NOTIFY_CHANGE IOCTL when the lpCompletion parameter is NULL (a poll) to indicate that
/// a query set remains valid.
///
///
///
///
///
///
/// The WSANSPIoctl function is used to set or retrieve operating parameters associated with a query handle to a namespace
/// provider. The hLookup parameter is a handle to the namespace provider query previously returned by the WSALookupServiceBegin
/// function (not a socket handle).
///
///
/// Any IOCTL sent to a namespace provider may block indefinitely, depending upon the implementation of the namespace. If an
/// application cannot tolerate blocking in a WSANSPIoctl function call, overlapped I/O should be used and the lpCompletion
/// parameter should point to a WSACOMPLETION structure. To make a WSANSPIoctl function call nonblocking and return
/// immediately, set the Type member of the WSACOMPLETION structure to NSP_NOTIFY_IMMEDIATELY.
///
///
/// If lpCompletion is NULL, the WSANSPIoctl function executes as a blocking call. The namespace provider should
/// return immediately and should not block. But each namespace is responsible for enforcing this behavior.
///
/// The following IOCTL code is supported by several Microsoft name space provider:
///
/// Immediate poll operations are usually much less expensive since they do not require a notification object. In most cases, this
/// is implemented as a simple Boolean variable check. Asynchronous notification, however, may necessitate the creation of dedicated
/// worker threads and/or inter-process communication channels, depending on the implementation of the namespace provider service,
/// and will incur processing overhead related to the notification object involved with signaling the change event.
///
///
/// To cancel an asynchronous notification request, end the original query with a WSALookupServiceEnd function call on the affected
/// query handle. Canceling the asynchronous notification for LUP_NOTIFY_HWND will not post any message, however, an overlapped
/// operation will be completed and notification will be delivered with the error WSA_OPERATION_ABORTED.
///
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. See ExitThread for more information.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsanspioctl INT WSAAPI WSANSPIoctl( HANDLE hLookup, DWORD
// dwControlCode, LPVOID lpvInBuffer, DWORD cbInBuffer, LPVOID lpvOutBuffer, DWORD cbOutBuffer, LPDWORD lpcbBytesReturned,
// LPWSACOMPLETION lpCompletion );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "6ecaedf0-0038-46d3-9916-c9cb069c5e92")]
public static extern WSRESULT WSANSPIoctl(HANDLE hLookup, uint dwControlCode, [In, Optional] IntPtr lpvInBuffer, uint cbInBuffer, [Out, Optional] IntPtr lpvOutBuffer, uint cbOutBuffer, out uint lpcbBytesReturned, [In, Optional] IntPtr lpCompletion);
/// The WSANtohl function converts a u_long from network byte order to host byte order.
/// A descriptor identifying a socket.
/// A 32-bit number in network byte order.
/// A pointer to a 32-bit number to receive the number in host byte order.
///
///
/// If no error occurs, WSANtohl returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can
/// be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
///
/// The lphostlong parameter is NULL or the address pointed to is not completely contained in a valid part of the user address space.
///
///
///
///
///
///
/// The WSANtohl function takes a 32-bit number in network byte order and returns a 32-bit number in host byte order in the
/// 32-bit number pointed to by the lphostlong parameter. The socket passed in the s parameter is used to determine the network byte
/// order required based on the Winsock catalog protocol entry associated with the socket. This feature supports Winsock providers
/// that use different network byte orders.
///
///
/// If the socket is for the AF_INET or AF_INET6 address family, the WSANtohl function can be used to convert an IPv4 address
/// in network byte order to the IPv4 address in host byte order. This function does not do any checking to determine if the netlong
/// parameter is a valid IPv4 address.
///
///
/// The WSANtohl function requires that the Winsock DLL has previously been loaded with a successful call to the WSAStartup
/// function. For use with the AF_INET or AF_INET6 family, the ntohl function does not require that the Winsock DLL be loaded.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsantohl int WSAAPI WSANtohl( SOCKET s, u_long netlong,
// u_long *lphostlong );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "7e3b42eb-3b93-459f-828a-c19e277882c7")]
public static extern WSRESULT WSANtohl(SOCKET s, uint netlong, out uint lphostlong);
/// The WSANtohs function converts a u_short from network byte order to host byte order.
/// A descriptor identifying a socket.
/// A 16-bit number in network byte order.
/// A pointer to a 16-bit number to receive the number in host byte order.
///
///
/// If no error occurs, WSANtohs returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can
/// be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
///
/// The lphostshort parameter is NULL or the address pointed to is not completely contained in a valid part of the user address space.
///
///
///
///
///
///
/// The WSANtohs function takes a 16-bit number in network byte order and returns a 16-bit number in host byte order in the
/// 16-bit number pointed to by the lphostshort parameter. The socket passed in the s parameter is used to determine the network
/// byte order required based on the Winsock catalog protocol entry associated with the socket. This feature supports Winsock
/// providers that use different network byte orders.
///
///
/// If the socket is for the AF_INET or AF_INET6 address family, the WSANtohs function can be used to convert an IP port
/// number in network byte order to the IP port number in host byte order.
///
///
/// The WSANtohs function requires that the Winsock DLL has previously been loaded with a successful call to the WSAStartup
/// function. For use with the AF_INET OR AF_INET6 address family, the ntohsfunction does not require that the Winsock DLL be loaded.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsantohs int WSAAPI WSANtohs( SOCKET s, u_short netshort,
// u_short *lphostshort );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "0a4bc3a9-9919-4dcb-8a37-af37e0243c8f")]
public static extern WSRESULT WSANtohs(SOCKET s, ushort netshort, out ushort lphostshort);
/// The WSAPoll function determines status of one or more sockets.
///
/// An array of one or more POLLFD structures specifying the set of sockets for which status is requested. The array must
/// contain at least one structure with a valid socket. Upon return, this parameter receives the updated sockets with the
/// revents status flags member set on each one that matches the status query criteria.
///
///
/// The number of WSAPOLLFD structures in fdarray. This is not necessarily the number of sockets for which status is requested.
///
///
/// A value that specifies the wait behavior, based on the following values.
///
///
/// Return value
/// Meaning
///
/// -
/// Greater than zero
/// The time, in milliseconds, to wait.
///
/// -
/// Zero
/// Return immediately.
///
/// -
/// Less than zero
/// Wait indefinitely.
///
///
///
///
/// Returns one of the following values.
///
///
/// Value
/// Description
///
/// -
/// Zero
/// No sockets were in the queried state before the timer expired.
///
/// -
/// Greater than zero
/// The number of elements in fdarray for which an revents member of the POLLFD structure is nonzero.
///
/// -
/// SOCKET_ERROR
/// An error occurred. Call the WSAGetLastError function to retrieve the extended error code.
///
///
///
///
/// Extended Error code
/// Meaning
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEFAULT
/// An exception occurred while reading user input parameters.
///
/// -
/// WSAEINVAL
///
/// An invalid parameter was passed. This error is returned if the
/// [WSAPOLLFD](/windows/win32/api/winsock2/ns-winsock2-wsapollfd)a> structures pointed to by the fdarray parameter when
/// requesting socket status. This error is also returned if none of the sockets specified in the fd member of any of the WSAPOLLFD
/// structures pointed to by the fdarray parameter were valid.
///
///
/// -
/// WSAENOBUFS
/// The function was unable to allocate sufficient memory.
///
///
///
///
/// The WSAPoll function is defined on Windows Vista and later.
///
/// The WSAPOLLFD structures. An application sets the appropriate flags in the events member of the WSAPOLLFD
/// structure to specify the type of status requested for each corresponding socket. The WSAPoll function returns the status
/// of a socket in the revents member of the WSAPOLLFD structure.
///
///
/// For each socket, a caller can request information on read or write status. Error conditions are always returned, so information
/// on them need not be requested.
///
///
/// The WSAPOLLFD structure pointed to by the fdarray parameter. All sockets that do not meet these criteria and have no error
/// condition will have the corresponding revents member set to 0.
///
///
/// A combination of the following flags can be set in the WSAPOLLFD structure for a given socket when requesting status for that socket:
///
///
///
/// Flag
/// Description
///
/// -
/// POLLPRI
/// Priority data may be read without blocking. This flag is not supported by the Microsoft Winsock provider.
///
/// -
/// POLLRDBAND
/// Priority band (out-of-band) data may be read without blocking.
///
/// -
/// POLLRDNORM
/// Normal data may be read without blocking.
///
/// -
/// POLLWRNORM
/// Normal data may be written without blocking.
///
///
///
/// The POLLIN flag is defined as the combination of the POLLRDNORM and POLLRDBAND flag values. The
/// POLLOUT flag is defined as the same as the POLLWRNORM flag value.
///
///
/// The WSAPOLLFD structure must only contain a combination of the above flags that are supported by the Winsock provider. Any other
/// values are considered errors and WSAPoll will return SOCKET_ERROR. A subsequent call to the WSAGetLastError
/// function will retrieve the extended error code of WSAEINVAL. If the POLLPRI flag is set on a socket for the Microsoft
/// Winsock provider, the WSAPoll function will fail.
///
/// When the WSAPOLLFD structures pointed to by the fdarray parameter to indicate socket status:
///
///
/// Flag
/// Description
///
/// -
/// POLLERR
/// An error has occurred.
///
/// -
/// POLLHUP
/// A stream-oriented connection was either disconnected or aborted.
///
/// -
/// POLLNVAL
/// An invalid socket was used.
///
/// -
/// POLLPRI
/// Priority data may be read without blocking. This flag is not returned by the Microsoft Winsock provider.
///
/// -
/// POLLRDBAND
/// Priority band (out-of-band) data may be read without blocking.
///
/// -
/// POLLRDNORM
/// Normal data may be read without blocking.
///
/// -
/// POLLWRNORM
/// Normal data may be written without blocking.
///
///
/// With regard to TCP and UDP sockets:
///
///
/// The number of elements (not sockets) in fdarray is indicated by nfds. Members of fdarray which have their fd member set
/// to a negative value are ignored and their revents will be set to POLLNVAL upon return. This behavior is useful to
/// an application which maintains a fixed fdarray allocation and will not compact the array to remove unused entries or to
/// reallocate memory. It is not necessary to clear revents for any element prior to calling WSAPoll.
///
///
/// The timeout argument specifies how long the function is to wait before returning. A positive value contains the number of
/// milliseconds to wait before returning. A zero value forces WSAPoll to return immediately, and a negative value indicates
/// that WSAPoll should wait indefinitely.
///
///
/// Note When issuing a blocking Winsock call such as WSAPoll with the timeout parameter set to a negative number,
/// Winsock may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation,
/// which can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock
/// call inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and
/// must never be attempted by Winsock clients.
///
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsapoll int WSAAPI WSAPoll( LPWSAPOLLFD fdArray, ULONG
// fds, INT timeout );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "3f6f872c-5cee-49f3-bf22-2e8a5d147987")]
public static extern WSRESULT WSAPoll([In, Out, MarshalAs(UnmanagedType.LPArray)] WSAPOLLFD[] fdArray, uint fds, int timeout);
/// The WSAProviderConfigChange function notifies the application when the provider configuration is changed.
///
/// Pointer to notification handle. If the notification handle is set to NULL (the handle value not the pointer itself), this
/// function returns a notification handle in the location pointed to by lpNotificationHandle.
///
/// Pointer to a WSAOVERLAPPED structure.
/// Pointer to the completion routine called when the provider change notification is received.
///
///
/// If no error occurs the WSAProviderConfigChange returns 0. Otherwise, a value of SOCKET_ERROR is returned and a specific
/// error code may be retrieved by calling WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped operation
/// has been successfully initiated and that completion (and thus change event) will be indicated at a later time.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// Not enough free memory available to complete the operation.
///
/// -
/// WSA_INVALID_HANDLE
/// Value pointed by lpNotificationHandle parameter is not a valid notification handle.
///
/// -
/// WSAEOPNOTSUPP
/// Current operating system environment does not support provider installation or removal without restart.
///
///
///
///
///
/// The WSAProviderConfigChange function notifies the application of provider (both transport and namespace) installation or
/// removal in Windows operating environments that support such configuration change without requiring a restart. When called for
/// the first time (lpNotificationHandle parameter points to NULL handle), this function completes immediately and returns
/// notification handle in the location pointed by lpNotificationHandle that can be used in subsequent calls to receive
/// notifications of provider installation and removal. The second and any subsequent calls only complete when provider information
/// changes since the time the call was made It is expected (but not required) that the application uses overlapped I/O on second
/// and subsequent calls to WSAProviderConfigChange, in which case the call will return immediately and application will be
/// notified of provider configuration changes using the completion mechanism chosen through specified overlapped completion parameters.
///
///
/// Notification handle returned by WSAProviderConfigChange is like any regular operating system handle that should be closed
/// (when no longer needed) using Windows CloseHandle call.
///
///
/// The following sequence of actions can be used to guarantee that application always has current protocol configuration information:
///
///
/// -
/// Call WSAProviderConfigChange
///
/// -
/// Call WSAEnumProtocols and/or WSAEnumNameSpaceProviders
///
/// -
///
/// Whenever WSAProviderConfigChange notifies application of provider configuration change (through blocking or overlapped
/// I/O), the whole sequence of actions should be repeated.
///
///
///
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaproviderconfigchange INT WSAAPI
// WSAProviderConfigChange( LPHANDLE lpNotificationHandle, LPWSAOVERLAPPED lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE
// lpCompletionRoutine );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "abaf367a-8f99-478c-a58c-d57e9f9cd8a1")]
public static extern WSRESULT WSAProviderConfigChange(ref HANDLE lpNotificationHandle, [In, Out, Optional] IntPtr lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
/// The WSARecv function receives data from a connected socket or a bound connectionless socket.
/// A descriptor identifying a connected socket.
///
/// A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length, in
/// bytes, of the buffer.
///
/// The number of WSABUF structures in the lpBuffers array.
///
/// A pointer to the number, in bytes, of data received by this call if the receive operation completes immediately.
///
/// Use NULL for this parameter if the lpOverlapped parameter is not NULL to avoid potentially erroneous results. This
/// parameter can be NULL only if the lpOverlapped parameter is not NULL.
///
///
///
/// A pointer to flags used to modify the behavior of the WSARecv function call. For more information, see the Remarks section.
///
/// A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).
///
/// A pointer to the completion routine called when the receive operation has been completed (ignored for nonoverlapped sockets).
///
///
///
/// If no error occurs and the receive operation has completed immediately, WSARecv returns zero. In this case, the
/// completion routine will have already been scheduled to be called once the calling thread is in the alertable state. Otherwise, a
/// value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError. The error code
/// WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at
/// a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion
/// indication will occur.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAECONNABORTED
/// The virtual circuit was terminated due to a time-out or other failure.
///
/// -
/// WSAECONNRESET
///
/// For a stream socket, the virtual circuit was reset by the remote side. The application should close the socket as it is no
/// longer usable. For a UDP datagram socket, this error would indicate that a previous send operation resulted in an ICMP "Port
/// Unreachable" message.
///
///
/// -
/// WSAEDISCON
/// Socket s is message oriented and the virtual circuit was gracefully closed by the remote side.
///
/// -
/// WSAEFAULT
/// The lpBuffers parameter is not completely contained in a valid part of the user address space.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEINTR
/// The (blocking) call was canceled by the WSACancelBlockingCall function.
///
/// -
/// WSAEINVAL
/// The socket has not been bound (for example, with bind).
///
/// -
/// WSAEMSGSIZE
///
/// The message was too large to fit into the specified buffer and (for unreliable protocols only) any trailing portion of the
/// message that did not fit into the buffer has been discarded.
///
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENETRESET
///
/// For a connection-oriented socket, this error indicates that the connection has been broken due to keep-alive activity that
/// detected a failure while the operation was in progress. For a datagram socket, this error indicates that the time to live has expired.
///
///
/// -
/// WSAENOTCONN
/// The socket is not connected.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEOPNOTSUPP
///
/// MSG_OOB was specified, but the socket is not stream-style such as type SOCK_STREAM, OOB data is not supported in the
/// communication domain associated with this socket, or the socket is unidirectional and supports only send operations.
///
///
/// -
/// WSAESHUTDOWN
///
/// The socket has been shut down; it is not possible to call WSARecv on a socket after shutdown has been invoked with how set to
/// SD_RECEIVE or SD_BOTH.
///
///
/// -
/// WSAETIMEDOUT
/// The connection has been dropped because of a network failure or because the peer system failed to respond.
///
/// -
/// WSAEWOULDBLOCK
///
/// Windows NT: Overlapped sockets: there are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is
/// marked as nonblocking and the receive operation cannot be completed immediately.
///
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSA_IO_PENDING
/// An overlapped operation was successfully initiated and completion will be indicated at a later time.
///
/// -
/// WSA_OPERATION_ABORTED
/// The overlapped operation has been canceled due to the closure of the socket.
///
///
///
///
///
/// The WSARecv function provides some additional features compared with the standard recv function in three important areas:
///
///
/// -
/// It can be used in conjunction with overlapped sockets to perform overlapped recv operations.
///
/// -
/// It allows multiple receive buffers to be specified making it applicable to the scatter/gather type of I/O.
///
/// -
///
/// The lpFlags parameter is used both on input and returned on output, allowing applications to sense the output state of the
/// MSG_PARTIAL flag bit. However, the MSG_PARTIAL flag bit is not supported by all protocols.
///
///
///
///
/// The WSARecv function is used on connected sockets or bound connectionless sockets specified by the s parameter and is
/// used to read incoming data. The socket's local address must be known. For server applications, this is usually done explicitly
/// through bind or implicitly through accept or WSAAccept. Explicit binding is discouraged for client applications. For client
/// applications the socket can become bound implicitly to a local address through connect, WSAConnect, sendto, WSASendTo, or WSAJoinLeaf.
///
///
/// For connected, connectionless sockets, this function restricts the addresses from which received messages are accepted. The
/// function only returns messages from the remote address specified in the connection. Messages from other addresses are (silently) discarded.
///
///
/// For overlapped sockets, WSARecv is used to post one or more buffers into which incoming data will be placed as it becomes
/// available, after which the application-specified completion indication (invocation of the completion routine or setting of an
/// event object) occurs. If the operation does not complete immediately, the final completion status is retrieved through the
/// completion routine or WSAGetOverlappedResult.
///
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. See ExitThread for more information.
///
///
/// If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a nonoverlapped socket.
///
///
/// For nonoverlapped sockets, the blocking semantics are identical to that of the standard recv function and the lpOverlapped and
/// lpCompletionRoutine parameters are ignored. Any data that has already been received and buffered by the transport will be copied
/// into the specified user buffers. In the case of a blocking socket with no data currently having been received and buffered by
/// the transport, the call will block until data is received. Windows Sockets 2 does not define any standard blocking time-out
/// mechanism for this function. For protocols acting as byte-stream protocols the stack tries to return as much data as possible
/// subject to the available buffer space and amount of received data available. However, receipt of a single byte is sufficient to
/// unblock the caller. There is no guarantee that more than a single byte will be returned. For protocols acting as
/// message-oriented, a full message is required to unblock the caller.
///
/// Note The socket options SO_RCVTIMEO and SO_SNDTIMEO apply only to blocking sockets.
///
/// Whether or not a protocol is acting as byte stream is determined by the setting of XP1_MESSAGE_ORIENTED and XP1_PSEUDO_STREAM in
/// its WSAPROTOCOL_INFO structure and the setting of the MSG_PARTIAL flag passed in to this function (for protocols that support
/// it). The following table lists relevant combinations, (an asterisk (*) indicates that the setting of this bit does not matter in
/// this case).
///
///
///
/// XP1_MESSAGE_ORIENTED
/// XP1_PSEUDO_STREAM
/// MSG_PARTIAL
/// Acts as
///
/// -
/// not set
/// *
/// *
/// Byte stream
///
/// -
/// *
/// Set
/// *
/// Byte stream
///
/// -
/// set
/// Not set
/// set
/// Byte stream
///
/// -
/// set
/// Not set
/// not set
/// Message oriented
///
///
///
/// The buffers are filled in the order in which they appear in the array pointed to by lpBuffers, and the buffers are packed so
/// that no holes are created.
///
///
/// If this function is completed in an overlapped manner, it is the Winsock service provider's responsibility to capture the WSABUF
/// structures before returning from this call. This enables applications to build stack-based WSABUF arrays pointed to by
/// the lpBuffers parameter.
///
///
/// For byte stream-style sockets (for example, type SOCK_STREAM), incoming data is placed into the buffers until the buffers
/// are filled, the connection is closed, or the internally buffered data is exhausted. Regardless of whether or not the incoming
/// data fills all the buffers, the completion indication occurs for overlapped sockets.
///
///
/// For message-oriented sockets (for example, type SOCK_DGRAM), an incoming message is placed into the buffers up to the
/// total size of the buffers, and the completion indication occurs for overlapped sockets. If the message is larger than the
/// buffers, the buffers are filled with the first part of the message. If the MSG_PARTIAL feature is supported by the
/// underlying service provider, the MSG_PARTIAL flag is set in lpFlags and subsequent receive operations will retrieve the
/// rest of the message. If MSG_PARTIAL is not supported but the protocol is reliable, WSARecv generates the error
/// WSAEMSGSIZE and a subsequent receive operation with a larger buffer can be used to retrieve the entire message. Otherwise, (that
/// is, the protocol is unreliable and does not support MSG_PARTIAL), the excess data is lost, and WSARecv generates
/// the error WSAEMSGSIZE.
///
///
/// For connection-oriented sockets, WSARecv can indicate the graceful termination of the virtual circuit in one of two ways
/// that depend on whether the socket is byte stream or message oriented. For byte streams, zero bytes having been read (as
/// indicated by a zero return value to indicate success, and lpNumberOfBytesRecvd value of zero) indicates graceful closure and
/// that no more bytes will ever be read. For message-oriented sockets, where a zero byte message is often allowable, a failure with
/// an error code of WSAEDISCON is used to indicate graceful closure. In any case a return error code of WSAECONNRESET indicates an
/// abortive close has occurred.
///
///
/// The lpFlags parameter can be used to influence the behavior of the function invocation beyond the options specified for the
/// associated socket. That is, the semantics of this function are determined by the socket options and the lpFlags parameter. The
/// latter is constructed by using the bitwise OR operator with any of the values listed in the following table.
///
///
///
/// Value
/// Meaning
///
/// -
/// MSG_PEEK
///
/// Peeks at the incoming data. The data is copied into the buffer, but is not removed from the input queue. This flag is valid only
/// for nonoverlapped sockets.
///
///
/// -
/// MSG_OOB
/// Processes OOB data.
///
/// -
/// MSG_PARTIAL
///
/// This flag is for message-oriented sockets only. On output, this flag indicates that the data specified is a portion of the
/// message transmitted by the sender. Remaining portions of the message will be specified in subsequent receive operations. A
/// subsequent receive operation with the MSG_PARTIAL flag cleared indicates end of sender's message. As an input parameter, this
/// flag indicates that the receive operation should complete even if only part of a message has been received by the transport provider.
///
///
/// -
/// MSG_PUSH_IMMEDIATE
///
/// This flag is for stream-oriented sockets only. This flag allows an application that uses stream sockets to tell the transport
/// provider not to delay completion of partially filled pending receive requests. This is a hint to the transport provider that the
/// application is willing to receive any incoming data as soon as possible without necessarily waiting for the remainder of the
/// data that might still be in transit. What constitutes a partially filled pending receive request is a transport-specific matter.
/// In the case of TCP, this refers to the case of incoming TCP segments being placed into the receive request data buffer where
/// none of the TCP segments indicated a PUSH bit value of 1. In this case, TCP may hold the partially filled receive request a
/// little longer to allow the remainder of the data to arrive with a TCP segment that has the PUSH bit set to 1. This flag tells
/// TCP not to hold the receive request but to complete it immediately. Using this flag for large block transfers is not recommended
/// since processing partial blocks is often not optimal. This flag is useful only for cases where receiving and processing the
/// partial data immediately helps decrease processing latency. This flag is a hint rather than an actual guarantee. This flag is
/// supported on Windows 8.1, Windows Server 2012 R2, and later.
///
///
/// -
/// MSG_WAITALL
///
/// The receive request will complete only when one of the following events occurs: Be aware that if the underlying transport
/// provider does not support MSG_WAITALL, or if the socket is in a non-blocking mode, then this call will fail with WSAEOPNOTSUPP.
/// Also, if MSG_WAITALL is specified along with MSG_OOB, MSG_PEEK, or MSG_PARTIAL, then this call will fail with WSAEOPNOTSUPP.
/// This flag is not supported on datagram sockets or message-oriented sockets.
///
///
///
///
/// For message-oriented sockets, the MSG_PARTIAL bit is set in the lpFlags parameter if a partial message is received. If a
/// complete message is received, MSG_PARTIAL is cleared in lpFlags. In the case of delayed completion, the value pointed to
/// by lpFlags is not updated. When completion has been indicated, the application should call WSAGetOverlappedResult and examine
/// the flags indicated by the lpdwFlags parameter.
///
///
/// Note When issuing a blocking Winsock call such as WSARecv with the lpOverlapped parameter set to NULL, Winsock may
/// need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which can
/// be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call
/// inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must
/// never be attempted by Winsock clients.
///
/// Overlapped Socket I/O
///
/// If an overlapped operation completes immediately, WSARecv returns a value of zero and the lpNumberOfBytesRecvd parameter
/// is updated with the number of bytes received and the flag bits indicated by the lpFlags parameter are also updated. If the
/// overlapped operation is successfully initiated and will complete later, WSARecv returns SOCKET_ERROR and indicates
/// error code WSA_IO_PENDING. In this case, lpNumberOfBytesRecvd and lpFlags are not updated. When the overlapped operation
/// completes, the amount of data transferred is indicated either through the cbTransferred parameter in the completion routine (if
/// specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult. Flag values are obtained by examining the lpdwFlags
/// parameter of WSAGetOverlappedResult.
///
///
/// The WSARecv function using overlapped I/O can be called from within the completion routine of a previous WSARecv,
/// WSARecvFrom, WSASend or WSASendTo function. For a given socket, I/O completion routines will not be nested. This permits
/// time-sensitive data transmissions to occur entirely within a preemptive context.
///
///
/// The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are
/// simultaneously outstanding, each must reference a separate WSAOVERLAPPED structure.
///
///
/// If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped
/// operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or
/// WSAGetOverlappedResult to wait or poll on the event object.
///
///
/// If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context
/// information to the completion routine. A caller that passes a non- NULL lpCompletionRoutine and later calls
/// WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of
/// WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is undefined, and attempting to
/// wait on the hEvent parameter would produce unpredictable results.
///
///
/// The completion routine follows the same rules as stipulated for Windows file I/O completion routines. The completion routine
/// will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents
/// with the fAlertable parameter set to TRUE is invoked.
///
/// The prototype of the completion routine is as follows:
///
/// CompletionRoutine is a placeholder for an application-defined or library-defined function name. The dwError specifies the
/// completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferred parameter specifies the number of
/// bytes received. The dwFlags parameter contains information that would have appeared in lpFlags if the receive operation had
/// completed immediately. This function does not return a value.
///
///
/// Returning from this function allows invocation of another pending completion routine for this socket. When using
/// WSAWaitForMultipleEvents, all waiting completion routines are called before the alertable thread's wait is satisfied with a
/// return code of WSA_IO_COMPLETION. The completion routines can be called in any order, not necessarily in the same order
/// the overlapped operations are completed. However, the posted buffers are guaranteed to be filled in the same order in which they
/// are specified.
///
///
/// If you are using I/O completion ports, be aware that the order of calls made to WSARecv is also the order in which the
/// buffers are populated. WSARecv should not be called on the same socket simultaneously from different threads, because it
/// can result in an unpredictable buffer order.
///
/// Example Code
/// The following example shows how to use the WSARecv function in overlapped I/O mode.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsarecv int WSAAPI WSARecv( SOCKET s, LPWSABUF lpBuffers,
// DWORD dwBufferCount, LPDWORD lpNumberOfBytesRecvd, LPDWORD lpFlags, LPWSAOVERLAPPED lpOverlapped,
// LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "bfe66e11-e9a7-4321-ad55-3141113e9a03")]
public static extern WSRESULT WSARecv(SOCKET s, [In] IntPtr lpBuffers, uint dwBufferCount, out uint lpNumberOfBytesRecvd, ref MsgFlags lpFlags, [In, Out, Optional] IntPtr lpOverlapped,
[In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
///
/// The WSARecvDisconnect function terminates reception on a socket, and retrieves the disconnect data if the socket is
/// connection oriented.
///
/// A descriptor identifying a socket.
/// A pointer to the incoming disconnect data.
///
///
/// If no error occurs, WSARecvDisconnect returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error
/// code can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEFAULT
/// The buffer referenced by the parameter lpInboundDisconnectData is too small.
///
/// -
/// WSAENOPROTOOPT
///
/// The disconnect data is not supported by the indicated protocol family. Note that implementations of TCP/IP that do not support
/// disconnect data are not required to return the WSAENOPROTOOPT error code. See the remarks section for information about the
/// Microsoft implementation of TCP/IP.
///
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAENOTCONN
/// The socket is not connected (connection-oriented sockets only).
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
///
///
///
///
/// The WSARecvDisconnect function is used on connection-oriented sockets to disable reception and retrieve any incoming
/// disconnect data from the remote party. This is equivalent to a shutdown (SD_RECEIVE), except that WSARecvDisconnect also
/// allows receipt of disconnect data (in protocols that support it).
///
///
/// After this function has been successfully issued, subsequent receives on the socket will be disallowed. Calling
/// WSARecvDisconnect has no effect on the lower protocol layers. For TCP sockets, if there is still data queued on the
/// socket waiting to be received, or data arrives subsequently, the connection is reset, since the data cannot be delivered to the
/// user. For UDP, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.
///
///
/// Note The native implementation of TCP/IP on Windows does not support disconnect data. Disconnect data is only supported
/// with Windows Sockets providers that have the XP1_DISCONNECT_DATA flag in their WSAPROTOCOL_INFO structure. Use the
/// WSAEnumProtocols function to obtain WSAPROTOCOL_INFO structures for all installed providers.
///
///
/// To successfully receive incoming disconnect data, an application must use other mechanisms to determine that the circuit has
/// been closed. For example, an application needs to receive an FD_CLOSE notification, to receive a zero return value, or to
/// receive a WSAEDISCON or WSAECONNRESET error code from recv/WSARecv.
///
///
/// The WSARecvDisconnect function does not close the socket, and resources attached to the socket will not be freed until
/// closesocket is invoked.
///
/// The WSARecvDisconnect function does not block regardless of the SO_LINGER setting on the socket.
///
/// An application should not rely on being able to reuse a socket after it has been disconnected using WSARecvDisconnect. In
/// particular, a Windows Sockets provider is not required to support the use of connect or WSAConnect on such a socket.
///
///
/// Note When issuing a blocking Winsock call such as WSARecvDisconnect, Winsock may need to wait for a network event
/// before the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous
/// procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an
/// ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsarecvdisconnect int WSAAPI WSARecvDisconnect( SOCKET s,
// LPWSABUF lpInboundDisconnectData );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "33e0fb8e-3ece-427f-b3ef-43a0f5cf0cc8")]
public static extern WSRESULT WSARecvDisconnect(SOCKET s, [In, Out, Optional] IntPtr lpInboundDisconnectData);
/// The WSARecvFrom function receives a datagram and stores the source address.
/// A descriptor identifying a socket.
///
/// A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length of the buffer.
///
/// The number of WSABUF structures in the lpBuffers array.
///
/// A pointer to the number of bytes received by this call if the WSARecvFrom operation completes immediately.
///
/// Use NULL for this parameter if the lpOverlapped parameter is not NULL to avoid potentially erroneous results. This
/// parameter can be NULL only if the lpOverlapped parameter is not NULL.
///
///
/// A pointer to flags used to modify the behavior of the WSARecvFrom function call. See remarks below.
///
/// An optional pointer to a buffer that will hold the source address upon the completion of the overlapped operation.
///
/// A pointer to the size, in bytes, of the "from" buffer required only if lpFrom is specified.
/// A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).
///
/// A pointer to the completion routine called when the WSARecvFrom operation has been completed (ignored for nonoverlapped sockets).
///
///
///
/// If no error occurs and the receive operation has completed immediately, WSARecvFrom returns zero. In this case, the
/// completion routine will have already been scheduled to be called once the calling thread is in the alertable state. Otherwise, a
/// value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError. The error code
/// WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be
/// indicated at a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no
/// completion indication will occur.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAECONNRESET
///
/// The virtual circuit was reset by the remote side executing a hard or abortive close. The application should close the socket as
/// it is no longer usable. For a UPD datagram socket, this error would indicate that a previous send operation resulted in an ICMP
/// "Port Unreachable" message.
///
///
/// -
/// WSAEFAULT
///
/// The lpBuffers, lpFlags, lpFrom, lpNumberOfBytesRecvd, lpFromlen, lpOverlapped, or lpCompletionRoutine parameter is not totally
/// contained in a valid part of the user address space: the lpFrom buffer was too small to accommodate the peer address.
///
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEINTR
/// A blocking Windows Socket 1.1 call was canceled through WSACancelBlockingCall.
///
/// -
/// WSAEINVAL
/// The socket has not been bound (with bind, for example).
///
/// -
/// WSAEMSGSIZE
///
/// The message was too large for the specified buffer and (for unreliable protocols only) any trailing portion of the message that
/// did not fit into the buffer has been discarded.
///
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENETRESET
/// For a datagram socket, this error indicates that the time to live has expired.
///
/// -
/// WSAENOTCONN
/// The socket is not connected (connection-oriented sockets only).
///
/// -
/// WSAEWOULDBLOCK
///
/// Windows NT: Overlapped sockets: There are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is
/// marked as nonblocking and the receive operation cannot be completed immediately.
///
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSA_IO_PENDING
/// An overlapped operation was successfully initiated and completion will be indicated later.
///
/// -
/// WSA_OPERATION_ABORTED
/// The overlapped operation has been canceled due to the closure of the socket.
///
///
///
///
///
/// The WSARecvFrom function provides functionality over and above the standard recvfrom function in three important areas:
///
///
/// -
/// It can be used in conjunction with overlapped sockets to perform overlapped receive operations.
///
/// -
/// It allows multiple receive buffers to be specified making it applicable to the scatter/gather type of I/O.
///
/// -
///
/// The lpFlags parameter is both an input and an output parameter, allowing applications to sense the output state of the
/// MSG_PARTIAL flag bit. Be aware that the MSG_PARTIAL flag bit is not supported by all protocols.
///
///
///
///
/// The WSARecvFrom function is used primarily on a connectionless socket specified by s. The socket's local address must be
/// known. For server applications, this is usually done explicitly through bind. Explicit binding is discouraged for client
/// applications. For client applications using this function the socket can become bound implicitly to a local address through
/// sendto, WSASendTo, or WSAJoinLeaf.
///
///
/// For overlapped sockets, this function is used to post one or more buffers into which incoming data will be placed as it becomes
/// available on a (possibly connected) socket, after which the application-specified completion indication (invocation of the
/// completion routine or setting of an event object) occurs. If the operation does not complete immediately, the final completion
/// status is retrieved through the completion routine or WSAGetOverlappedResult. Also, the values indicated by lpFrom and lpFromlen
/// are not updated until completion is itself indicated. Applications must not use or disturb these values until they have been
/// updated, therefore the application must not use automatic (that is, stack-based) variables for these parameters.
///
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. See ExitThread for more information.
///
///
/// If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a nonoverlapped socket.
///
///
/// For nonoverlapped sockets, the blocking semantics are identical to that of the standard WSARecv function and the lpOverlapped
/// and lpCompletionRoutine parameters are ignored. Any data that has already been received and buffered by the transport will be
/// copied into the user buffers. For the case of a blocking socket with no data currently having been received and buffered by the
/// transport, the call will block until data is received.
///
///
/// The buffers are filled in the order in which they appear in the array indicated by lpBuffers, and the buffers are packed so that
/// no holes are created.
///
///
/// If this function is completed in an overlapped manner, it is the Winsock service provider's responsibility to capture the WSABUF
/// structures before returning from this call. This enables applications to build stack-based WSABUF arrays pointed to by
/// the lpBuffers parameter.
///
///
/// For connectionless socket types, the address from which the data originated is copied to the buffer indicated by lpFrom. The
/// value pointed to by lpFromlen is initialized to the size of this buffer, and is modified on completion to indicate the actual
/// size of the address stored there. As stated previously for overlapped sockets, the lpFrom and lpFromlen parameters are not
/// updated until after the overlapped I/O has completed. The memory pointed to by these parameters must, therefore, remain
/// available to the service provider and cannot be allocated on the application stack frame. The lpFrom and lpFromlen parameters
/// are ignored for connection-oriented sockets.
///
/// For byte stream–style sockets (for example, type SOCK_STREAM), incoming data is placed into the buffers until:
///
/// -
/// The buffers are filled.
///
/// -
/// The connection is closed.
///
/// -
/// The internally buffered data is exhausted.
///
///
///
/// Regardless of whether or not the incoming data fills all the buffers, the completion indication occurs for overlapped sockets.
/// For message-oriented sockets, an incoming message is placed into the buffers up to the total size of the buffers, and the
/// completion indication occurs for overlapped sockets. If the message is larger than the buffers, the buffers are filled with the
/// first part of the message. If the MSG_PARTIAL feature is supported by the underlying service provider, the
/// MSG_PARTIAL flag is set in lpFlags and subsequent receive operation(s) will retrieve the rest of the message. If
/// MSG_PARTIAL is not supported, but the protocol is reliable, WSARecvFrom generates the error WSAEMSGSIZE and a
/// subsequent receive operation with a larger buffer can be used to retrieve the entire message. Otherwise, (that is, the protocol
/// is unreliable and does not support MSG_PARTIAL), the excess data is lost, and WSARecvFrom generates the error WSAEMSGSIZE.
///
///
/// The lpFlags parameter can be used to influence the behavior of the function invocation beyond the options specified for the
/// associated socket. That is, the semantics of this function are determined by the socket options and the lpFlags parameter. The
/// latter is constructed by using the bitwise OR operator with any of any of the values listed in the following table.
///
///
///
/// Value
/// Meaning
///
/// -
/// MSG_PEEK
///
/// Previews the incoming data. The data is copied into the buffer, but is not removed from the input queue. This flag is valid only
/// for nonoverlapped sockets.
///
///
/// -
/// MSG_OOB
/// Processes OOB data.
///
/// -
/// MSG_PARTIAL
///
/// This flag is for message-oriented sockets only. On output, this flag indicates that the data is a portion of the message
/// transmitted by the sender. Remaining portions of the message will be transmitted in subsequent receive operations. A subsequent
/// receive operation with MSG_PARTIAL flag cleared indicates the end of the sender's message. As an input parameter, this flag
/// indicates that the receive operation should complete even if only part of a message has been received by the service provider.
///
///
///
///
/// For message-oriented sockets, the MSG_PARTIAL bit is set in the lpFlags parameter if a partial message is received. If a
/// complete message is received, MSG_PARTIAL is cleared in lpFlags. In the case of delayed completion, the value pointed to
/// by lpFlags is not updated. When completion has been indicated the application should call WSAGetOverlappedResult and examine the
/// flags pointed to by the lpdwFlags parameter.
///
///
/// Note When issuing a blocking Winsock call such as WSARecvFrom with the lpOverlapped parameter set to NULL, Winsock
/// may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which
/// can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call
/// inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must
/// never be attempted by Winsock clients.
///
/// Overlapped Socket I/O
///
/// If an overlapped operation completes immediately, WSARecvFrom returns a value of zero and the lpNumberOfBytesRecvd
/// parameter is updated with the number of bytes received and the flag bits pointed by the lpFlags parameter are also updated. If
/// the overlapped operation is successfully initiated and will complete later, WSARecvFrom returns SOCKET_ERROR and
/// indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesRecvd and lpFlags is not updated. When the overlapped
/// operation completes the amount of data transferred is indicated either through the cbTransferred parameter in the completion
/// routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult. Flag values are obtained either through
/// the dwFlags parameter of the completion routine, or by examining the lpdwFlags parameter of WSAGetOverlappedResult.
///
///
/// The WSARecvFrom function can be called from within the completion routine of a previous WSARecv, WSARecvFrom,
/// WSASend, or WSASendTo function. For a given socket, I/O completion routines will not be nested. This permits time-sensitive data
/// transmissions to occur entirely within a preemptive context.
///
///
/// The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are
/// simultaneously outstanding, each must reference a separate WSAOVERLAPPED structure.
///
///
/// If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped
/// operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or
/// WSAGetOverlappedResult to wait or poll on the event object.
///
///
/// If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context
/// information to the completion routine. A caller that passes a non- NULL lpCompletionRoutine and later calls
/// WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of
/// WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is undefined, and attempting to
/// wait on the hEvent parameter would produce unpredictable results.
///
///
/// The completion routine follows the same rules as stipulated for Windows file I/O completion routines. The completion routine
/// will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents
/// with the fAlertable parameter set to TRUE is invoked.
///
///
/// The transport providers allow an application to invoke send and receive operations from within the context of the socket I/O
/// completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits
/// time-sensitive data transmissions to occur entirely within a preemptive context.
///
/// The prototype of the completion routine is as follows.
///
/// The CompletionRoutine is a placeholder for an application-defined or library-defined function name. The dwError specifies
/// the completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferred specifies the number of bytes
/// received. The dwFlags parameter contains information that would have appeared in lpFlags if the receive operation had completed
/// immediately. This function does not return a value.
///
///
/// Returning from this function allows invocation of another pending completion routine for this socket. When using
/// WSAWaitForMultipleEvents, all waiting completion routines are called before the alertable thread's wait is satisfied with a
/// return code of WSA_IO_COMPLETION. The completion routines can be called in any order, not necessarily in the same order the
/// overlapped operations are completed. However, the posted buffers are guaranteed to be filled in the same order they are specified.
///
/// Example Code
/// The following example demonstrates the use of the WSARecvFrom function.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsarecvfrom int WSAAPI WSARecvFrom( SOCKET s, LPWSABUF
// lpBuffers, DWORD dwBufferCount, LPDWORD lpNumberOfBytesRecvd, LPDWORD lpFlags, sockaddr *lpFrom, LPINT lpFromlen, LPWSAOVERLAPPED
// lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "8617dbb8-0e4e-4cd3-9597-5d20de6778f6")]
public static extern WSRESULT WSARecvFrom(SOCKET s, [In, Out, Optional, MarshalAs(UnmanagedType.LPArray)] WSABUF[] lpBuffers, uint dwBufferCount, out uint lpNumberOfBytesRecvd, ref MsgFlags lpFlags,
[Out] SOCKADDR lpFrom, ref int lpFromlen, [In, Out, Optional] IntPtr lpOverlapped, [In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
/// The WSARemoveServiceClass function permanently removes the service class schema from the registry.
/// Pointer to the GUID for the service class you want to remove.
///
///
/// The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error
/// number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSATYPE_NOT_FOUND
/// The specified class was not found.
///
/// -
/// WSAEACCES
/// The calling routine does not have sufficient privileges to remove the Service.
///
/// -
/// WSAETOOMANYREFS
/// There are service instances that still reference the class. Removal of this class is not possible at this time.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSAEINVAL
/// The specified GUID was not valid.
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaremoveserviceclass INT WSAAPI WSARemoveServiceClass(
// LPGUID lpServiceClassId );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "7d72f727-cca9-4a07-beb4-d64f23c1f0c1")]
public static extern WSRESULT WSARemoveServiceClass(in Guid lpServiceClassId);
/// The WSAResetEvent function resets the state of the specified event object to nonsignaled.
/// A handle that identifies an open event object handle.
///
///
/// If the WSAResetEvent function succeeds, the return value is TRUE. If the function fails, the return value is
/// FALSE. To get extended error information, call WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSA_INVALID_HANDLE
/// The hEvent parameter is not a valid event object handle.
///
///
///
///
/// The WSAResetEvent function is used to set the state of the event object to nonsignaled.
///
/// The proper way to reset the state of an event object used with the WSAEventSelect function is to pass the handle of the event
/// object to the WSAEnumNetworkEvents function in the hEventObject parameter. This will reset the event object and adjust the
/// status of active FD events on the socket in an atomic fashion.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaresetevent BOOL WSAAPI WSAResetEvent( WSAEVENT hEvent );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "99a8b0f3-977f-44cd-a224-0819d7513c90")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WSAResetEvent(WSAEVENT hEvent);
/// The WSASend function sends data on a connected socket.
/// A descriptor that identifies a connected socket.
///
/// A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length, in
/// bytes, of the buffer. For a Winsock application, once the WSASend function is called, the system owns these buffers and
/// the application may not access them. This array must remain valid for the duration of the send operation.
///
/// The number of WSABUF structures in the lpBuffers array.
///
/// A pointer to the number, in bytes, sent by this call if the I/O operation completes immediately.
///
/// Use NULL for this parameter if the lpOverlapped parameter is not NULL to avoid potentially erroneous results. This
/// parameter can be NULL only if the lpOverlapped parameter is not NULL.
///
///
///
/// The flags used to modify the behavior of the WSASend function call. For more information, see Using dwFlags in the
/// Remarks section.
///
/// A pointer to a WSAOVERLAPPED structure. This parameter is ignored for nonoverlapped sockets.
///
/// A pointer to the completion routine called when the send operation has been completed. This parameter is ignored for
/// nonoverlapped sockets.
///
///
///
/// If no error occurs and the send operation has completed immediately, WSASend returns zero. In this case, the completion
/// routine will have already been scheduled to be called once the calling thread is in the alertable state. Otherwise, a value of
/// SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError. The error code
/// WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at
/// a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion
/// indication will occur.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAECONNABORTED
/// The virtual circuit was terminated due to a time-out or other failure.
///
/// -
/// WSAECONNRESET
///
/// For a stream socket, the virtual circuit was reset by the remote side. The application should close the socket as it is no
/// longer usable. For a UDP datagram socket, this error would indicate that a previous send operation resulted in an ICMP "Port
/// Unreachable" message.
///
///
/// -
/// WSAEFAULT
///
/// The lpBuffers, lpNumberOfBytesSent, lpOverlapped, lpCompletionRoutine parameter is not totally contained in a valid part of the
/// user address space.
///
///
/// -
/// WSAEINTR
/// A blocking Windows Socket 1.1 call was canceled through WSACancelBlockingCall.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEINVAL
/// The socket has not been bound with bind or the socket is not created with the overlapped flag.
///
/// -
/// WSAEMSGSIZE
/// The socket is message oriented, and the message is larger than the maximum supported by the underlying transport.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENETRESET
///
/// For a stream socket, the connection has been broken due to keep-alive activity detecting a failure while the operation was in
/// progress. For a datagram socket, this error indicates that the time to live has expired.
///
///
/// -
/// WSAENOBUFS
/// The Windows Sockets provider reports a buffer deadlock.
///
/// -
/// WSAENOTCONN
/// The socket is not connected.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEOPNOTSUPP
///
/// MSG_OOB was specified, but the socket is not stream-style such as type SOCK_STREAM, OOB data is not supported in the
/// communication domain associated with this socket, MSG_PARTIAL is not supported, or the socket is unidirectional and supports
/// only receive operations.
///
///
/// -
/// WSAESHUTDOWN
///
/// The socket has been shut down; it is not possible to WSASend on a socket after shutdown has been invoked with how set to SD_SEND
/// or SD_BOTH.
///
///
/// -
/// WSAEWOULDBLOCK
///
/// Windows NT: Overlapped sockets: There are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is
/// marked as nonblocking and the send operation cannot be completed immediately.
///
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSA_IO_PENDING
/// An overlapped operation was successfully initiated and completion will be indicated at a later time.
///
/// -
/// WSA_OPERATION_ABORTED
///
/// The overlapped operation has been canceled due to the closure of the socket, the execution of the "SIO_FLUSH" command in
/// WSAIoctl, or the thread that initiated the overlapped request exited before the operation completed. For more information, see
/// the Remarks section.
///
///
///
///
///
/// The WSASend function provides functionality over and above the standard send function in two important areas:
///
/// -
/// It can be used in conjunction with overlapped sockets to perform overlapped send operations.
///
/// -
/// It allows multiple send buffers to be specified making it applicable to the scatter/gather type of I/O.
///
///
///
/// The WSASend function is used to write outgoing data from one or more buffers on a connection-oriented socket specified by
/// s. It can also be used, however, on connectionless sockets that have a stipulated default peer address established through the
/// connect or WSAConnect function.
///
///
/// A socket created by the socket function will have the overlapped attribute as the default. A socket created by the WSASocket
/// function with the dwFlags parameter passed to WSASocket with the WSA_FLAG_OVERLAPPED bit set will have the
/// overlapped attribute. For sockets with the overlapped attribute, WSASend uses overlapped I/O unless both the lpOverlapped
/// and lpCompletionRoutine parameters are NULL. In that case, the socket is treated as a non-overlapped socket. A completion
/// indication will occur, invoking the completion of a routine or setting of an event object, when the buffer(s) have been consumed
/// by the transport. If the operation does not complete immediately, the final completion status is retrieved through the
/// completion routine or WSAGetOverlappedResult.
///
///
/// If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a non-overlapped socket.
///
///
/// For non-overlapped sockets, the last two parameters (lpOverlapped, lpCompletionRoutine) are ignored and WSASend adopts
/// the same blocking semantics as send. Data is copied from the buffer(s) into the transport's buffer. If the socket is
/// non-blocking and stream-oriented, and there is not sufficient space in the transport's buffer, WSASend will return with
/// only part of the application's buffers having been consumed. Given the same buffer situation and a blocking socket,
/// WSASend will block until all of the application buffer contents have been consumed.
///
/// Note The socket options SO_RCVTIMEO and SO_SNDTIMEO apply only to blocking sockets.
///
/// If this function is completed in an overlapped manner, it is the Winsock service provider's responsibility to capture the WSABUF
/// structures before returning from this call. This enables applications to build stack-based WSABUF arrays pointed to by
/// the lpBuffers parameter.
///
///
/// For message-oriented sockets, do not exceed the maximum message size of the underlying provider, which can be obtained by
/// getting the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying
/// protocol the error WSAEMSGSIZE is returned, and no data is transmitted.
///
/// Windows Me/98/95: The WSASend function does not support more than 16 buffers.
/// Note The successful completion of a WSASend does not indicate that the data was successfully delivered.
/// Using dwFlags
///
/// The dwFlags parameter can be used to influence the behavior of the function invocation beyond the options specified for the
/// associated socket. That is, the semantics of this function are determined by the socket options and the dwFlags parameter. The
/// latter is constructed by using the bitwise OR operator with any of any of the values listed in the following table.
///
///
///
/// Value
/// Meaning
///
/// -
/// MSG_DONTROUTE
///
/// Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.
///
///
/// -
/// MSG_OOB
/// Send OOB data on a stream-style socket such as SOCK_STREAM only.
///
/// -
/// MSG_PARTIAL
///
/// Specifies that lpBuffers only contains a partial message. Be aware that the error code WSAEOPNOTSUPP will be returned by
/// transports that do not support partial message transmissions.
///
///
///
///
/// Note When issuing a blocking Winsock call such as WSASend with the lpOverlapped parameter set to NULL, Winsock may
/// need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which can
/// be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call
/// inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must
/// never be attempted by Winsock clients.
///
/// Overlapped Socket I/O
///
/// If an overlapped operation completes immediately, WSASend returns a value of zero and the lpNumberOfBytesSent parameter
/// is updated with the number of bytes sent. If the overlapped operation is successfully initiated and will complete later,
/// WSASend returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesSent is not updated.
/// When the overlapped operation completes the amount of data transferred is indicated either through the cbTransferred parameter
/// in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.
///
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. For more information, see ExitThread.
///
///
/// The WSASend function using overlapped I/O can be called from within the completion routine of a previous WSARecv,
/// WSARecvFrom, WSASend, or WSASendTo function. This enables time-sensitive data transmissions to occur entirely within a
/// preemptive context.
///
///
/// The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are
/// simultaneously outstanding, each must reference a separate WSAOVERLAPPED structure.
///
///
/// If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped
/// operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or
/// WSAGetOverlappedResult to wait or poll on the event object.
///
///
/// If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context
/// information to the completion routine. A caller that passes a non- NULL lpCompletionRoutine and later calls
/// WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of
/// WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is undefined, and attempting to
/// wait on the hEvent parameter would produce unpredictable results.
///
///
/// The completion routine follows the same rules as stipulated for Windows file I/O completion routines. The completion routine
/// will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents
/// with the fAlertable parameter set to TRUE is invoked.
///
///
/// The transport providers allow an application to invoke send and receive operations from within the context of the socket I/O
/// completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits
/// time-sensitive data transmissions to occur entirely within a preemptive context.
///
/// The following C++ code example is a prototype of the completion routine.
///
/// The CompletionRoutine function is a placeholder for an application-defined or library-defined function name. The dwError
/// parameter specifies the completion status for the overlapped operation as indicated by lpOverlapped. cbTransferred specifies the
/// number of bytes sent. Currently there are no flag values defined and dwFlags will be zero. This function does not return a value.
///
///
/// Returning from this function allows invocation of another pending completion routine for this socket. All waiting completion
/// routines are called before the alertable thread's wait is satisfied with a return code of WSA_IO_COMPLETION. The
/// completion routines can be called in any order, not necessarily in the same order the overlapped operations are completed.
/// However, the posted buffers are guaranteed to be sent in the same order they are specified.
///
///
/// The order of calls made to WSASend is also the order in which the buffers are transmitted to the transport layer.
/// WSASend should not be called on the same stream-oriented socket concurrently from different threads, because some Winsock
/// providers may split a large send request into multiple transmissions, and this may lead to unintended data interleaving from
/// multiple concurrent send requests on the same stream-oriented socket.
///
/// Example Code
/// The following code example shows how to use the WSASend function in overlapped I/O mode.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasend int WSAAPI WSASend( SOCKET s, LPWSABUF lpBuffers,
// DWORD dwBufferCount, LPDWORD lpNumberOfBytesSent, DWORD dwFlags, LPWSAOVERLAPPED lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE
// lpCompletionRoutine );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "764339e6-a1ac-455d-8ebd-ad0fa50dc3b0")]
public static extern WSRESULT WSASend(SOCKET s, [In, MarshalAs(UnmanagedType.LPArray)] WSABUF[] lpBuffers, uint dwBufferCount, out uint lpNumberOfBytesSent,
MsgFlags dwFlags, [In, Out, Optional] IntPtr lpOverlapped, [In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
///
/// The WSASendDisconnect function initiates termination of the connection for the socket and sends disconnect data.
///
/// Descriptor identifying a socket.
/// A pointer to the outgoing disconnect data.
///
///
/// If no error occurs, WSASendDisconnect returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error
/// code can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOPROTOOPT
/// The parameter lpOutboundDisconnectData is not NULL, and the disconnect data is not supported by the service provider.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAENOTCONN
/// The socket is not connected (connection-oriented sockets only).
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
/// The lpOutboundDisconnectData parameter is not completely contained in a valid part of the user address space.
///
///
///
///
///
/// The WSASendDisconnect function is used on connection-oriented sockets to disable transmission and to initiate termination
/// of the connection along with the transmission of disconnect data, if any. This is equivalent to a shutdown (SD_SEND), except
/// that WSASendDisconnect also allows sending disconnect data (in protocols that support it).
///
/// After this function has been successfully issued, subsequent sends are disallowed.
///
/// The lpOutboundDisconnectData parameter, if not NULL, points to a buffer containing the outgoing disconnect data to be
/// sent to the remote party for retrieval by using WSARecvDisconnect.
///
///
/// Note The native implementation of TCP/IP on Windows does not support disconnect data. Disconnect data is only supported
/// with Windows Sockets providers that have the XP1_DISCONNECT_DATA flag in their WSAPROTOCOL_INFO structure. Use the
/// WSAEnumProtocols function to obtain WSAPROTOCOL_INFO structures for all installed providers.
///
///
/// The WSASendDisconnect function does not close the socket, and resources attached to the socket will not be freed until
/// closesocket is invoked.
///
/// The WSASendDisconnect function does not block regardless of the SO_LINGER setting on the socket.
///
/// An application should not rely on being able to reuse a socket after calling WSASendDisconnect. In particular, a Windows
/// Sockets provider is not required to support the use of connect/WSAConnect on such a socket.
///
///
/// Note When issuing a blocking Winsock call such as WSASendDisconnect, Winsock may need to wait for a network event
/// before the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous
/// procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an
/// ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasenddisconnect int WSAAPI WSASendDisconnect( SOCKET s,
// LPWSABUF lpOutboundDisconnectData );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "c05fc719-e35a-4194-ac01-a294b19ccce9")]
public static extern WSRESULT WSASendDisconnect(SOCKET s, in WSABUF lpOutboundDisconnectData);
///
/// The WSASendDisconnect function initiates termination of the connection for the socket and sends disconnect data.
///
/// Descriptor identifying a socket.
/// A pointer to the outgoing disconnect data.
///
///
/// If no error occurs, WSASendDisconnect returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error
/// code can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENOPROTOOPT
/// The parameter lpOutboundDisconnectData is not NULL, and the disconnect data is not supported by the service provider.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAENOTCONN
/// The socket is not connected (connection-oriented sockets only).
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEFAULT
/// The lpOutboundDisconnectData parameter is not completely contained in a valid part of the user address space.
///
///
///
///
///
/// The WSASendDisconnect function is used on connection-oriented sockets to disable transmission and to initiate termination
/// of the connection along with the transmission of disconnect data, if any. This is equivalent to a shutdown (SD_SEND), except
/// that WSASendDisconnect also allows sending disconnect data (in protocols that support it).
///
/// After this function has been successfully issued, subsequent sends are disallowed.
///
/// The lpOutboundDisconnectData parameter, if not NULL, points to a buffer containing the outgoing disconnect data to be
/// sent to the remote party for retrieval by using WSARecvDisconnect.
///
///
/// Note The native implementation of TCP/IP on Windows does not support disconnect data. Disconnect data is only supported
/// with Windows Sockets providers that have the XP1_DISCONNECT_DATA flag in their WSAPROTOCOL_INFO structure. Use the
/// WSAEnumProtocols function to obtain WSAPROTOCOL_INFO structures for all installed providers.
///
///
/// The WSASendDisconnect function does not close the socket, and resources attached to the socket will not be freed until
/// closesocket is invoked.
///
/// The WSASendDisconnect function does not block regardless of the SO_LINGER setting on the socket.
///
/// An application should not rely on being able to reuse a socket after calling WSASendDisconnect. In particular, a Windows
/// Sockets provider is not required to support the use of connect/WSAConnect on such a socket.
///
///
/// Note When issuing a blocking Winsock call such as WSASendDisconnect, Winsock may need to wait for a network event
/// before the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous
/// procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an
/// ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasenddisconnect int WSAAPI WSASendDisconnect( SOCKET s,
// LPWSABUF lpOutboundDisconnectData );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "c05fc719-e35a-4194-ac01-a294b19ccce9")]
public static extern WSRESULT WSASendDisconnect(SOCKET s, [In, Optional] IntPtr lpOutboundDisconnectData);
/// The WSASendMsg function sends data and optional control information from connected and unconnected sockets.
/// A descriptor identifying the socket.
/// A WSAMSG structure storing the Posix.1g msghdr structure.
///
/// The flags used to modify the behavior of the WSASendMsg function call. For more information, see Using dwFlags in the
/// Remarks section.
///
///
/// A pointer to the number, in bytes, sent by this call if the I/O operation completes immediately.
///
/// Use NULL for this parameter if the lpOverlapped parameter is not NULL to avoid potentially erroneous results. This
/// parameter can be NULL only if the lpOverlapped parameter is not NULL.
///
///
/// A pointer to a WSAOVERLAPPED structure. Ignored for non-overlapped sockets.
///
/// A pointer to the completion routine called when the send operation completes. Ignored for non-overlapped sockets.
///
///
///
/// Returns zero when successful and immediate completion occurs. When zero is returned, the specified completion routine is called
/// when the calling thread is in the alertable state.
///
///
/// A return value of SOCKET_ERROR, and subsequent call to WSAGetLastError that returns WSA_IO_PENDING, indicates the
/// overlapped operation has successfully initiated; completion is then indicated through other means, such as through events or
/// completion ports.
///
///
/// Upon failure, returns SOCKET_ERROR and a subsequent call to WSAGetLastError returns a value other than
/// WSA_IO_PENDING. The following table lists error codes.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEACCES
/// The requested address is a broadcast address, but the appropriate flag was not set.
///
/// -
/// WSAECONNRESET
///
/// For a UDP datagram socket, this error would indicate that a previous send operation resulted in an ICMP "Port Unreachable" message.
///
///
/// -
/// WSAEFAULT
///
/// The lpMsg, lpNumberOfBytesSent, lpOverlapped, or lpCompletionRoutine parameter is not totally contained in a valid part of the
/// user address space. This error is also returned if a name member of the WSAMSGstructure pointed to by the lpMsg parameter was a
/// NULL pointer and the namelen member of the WSAMSGstructure was not set to zero. This error is also returned if a Control.buf
/// member of the WSAMSGstructure pointed to by the lpMsg parameter was a NULL pointer and the Control.len member of the
/// WSAMSGstructure was not set to zero.
///
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEINTR
/// A blocking Windows Socket 1.1 call was canceled through WSACancelBlockingCall.
///
/// -
/// WSAEINVAL
/// The socket has not been bound with bind, or the socket was not created with the overlapped flag.
///
/// -
/// WSAEMSGSIZE
/// The socket is message oriented, and the message is larger than the maximum supported by the underlying transport.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENETRESET
/// For a datagram socket, this error indicates that the time to live has expired.
///
/// -
/// WSAENETUNREACH
/// The network is unreachable.
///
/// -
/// WSAENOBUFS
/// The Windows Sockets provider reports a buffer deadlock.
///
/// -
/// WSAENOTCONN
/// The socket is not connected.
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAEOPNOTSUPP
///
/// The socket operation is not supported. This error is returned if the dwFlags member of the WSAMSGstructure pointed to by the
/// lpMsg parameter includes any control flags invalid for WSASendMsg.
///
///
/// -
/// WSAESHUTDOWN
///
/// The socket has been shut down; it is not possible to call the WSASendMsg function on a socket after shutdown has been invoked
/// with how set to SD_SEND or SD_BOTH.
///
///
/// -
/// WSAETIMEDOUT
///
/// The socket timed out. This error is returned if the socket had a wait timeout specified using the SO_SNDTIMEO socket option and
/// the timeout was exceeded.
///
///
/// -
/// WSAEWOULDBLOCK
///
/// Overlapped sockets: There are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is marked as
/// nonblocking and the send operation cannot be completed immediately.
///
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSA_IO_PENDING
/// An overlapped operation was successfully initiated and completion will be indicated at a later time.
///
/// -
/// WSA_OPERATION_ABORTED
///
/// The overlapped operation has been canceled due to the closure of the socket or due to the execution of the SIO_FLUSH command in WSAIoctl.
///
///
///
///
///
///
/// The WSASendMsg function can be used in place of the WSASend and WSASendTo functions. The WSASendMsg function can
/// only be used with datagrams and raw sockets. The socket descriptor in the s parameter must be opened with the socket type set to
/// SOCK_DGRAM or SOCK_RAW.
///
///
/// The dwFlags parameter can only contain a combination of the following control flags: MSG_DONTROUTE, MSG_PARTIAL,
/// and MSG_OOB. The dwFlags member of the WSAMSGstructure pointed to by the lpMsg parameter is ignored on input and
/// not used on output.
///
///
/// Note The function pointer for the WSASendMsg function must be obtained at run time by making a call to the
/// WSAIoctl function with the SIO_GET_EXTENSION_FUNCTION_POINTER opcode specified. The input buffer passed to the
/// WSAIoctl function must contain WSAID_WSASENDMSG, a globally unique identifier (GUID) whose value identifies the
/// WSASendMsg extension function. On success, the output returned by the WSAIoctl function contains a pointer to the
/// WSASendMsg function. The WSAID_WSASENDMSG GUID is defined in the Mswsock.h header file.
///
///
/// Overlapped sockets are created with a WSASocket function call that has the WSA_FLAG_OVERLAPPED flag set. For overlapped
/// sockets, sending information uses overlapped I/O unless both lpOverlapped and lpCompletionRoutine are NULL; when
/// lpOverlapped and lpCompletionRoutine are NULL, the socket is treated as a nonoverlapped socket. A completion indication
/// occurs with overlapped sockets; once the buffer or buffers have been consumed by the transport, a completion routine is
/// triggered or an event object is set. If the operation does not complete immediately, the final completion status is retrieved
/// through the completion routine or by calling the WSAGetOverlappedResult function.
///
///
/// For nonoverlapped sockets, the lpOverlapped and lpCompletionRoutine parameters are ignored and WSASendMsg adopts the same
/// blocking semantics as the send function: data is copied from the buffer or buffers into the transport's buffer. If the socket is
/// nonblocking and stream oriented, and there is insufficient space in the transport's buffer, WSASendMsg returns with only
/// part of the application's buffers having been consumed. In contrast, this buffer situation on a blocking socket results in
/// WSASendMsg blocking until all of the application's buffer contents have been consumed.
///
///
/// If this function is completed in an overlapped manner, it is the Winsock service provider's responsibility to capture this
/// WSABUF structure before returning from this call. This enables applications to build stack-based WSABUF arrays pointed to
/// by the lpBuffers member of the WSAMSGstructure pointed to by the lpMsg parameter.
///
///
/// For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying provider, which can be
/// obtained by getting the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the
/// underlying protocol, the error WSAEMSGSIZE is returned and no data is transmitted.
///
///
/// On an IPv4 socket of type SOCK_DGRAM or SOCK_RAW, an application can specific the local IP source address to use
/// for sending with the WSASendMsg function. One of the control data objects passed in the WSAMSG structure to the
/// WSASendMsg function may contain an in_pktinfo structure used to specify the local IPv4 source address to use for sending.
///
///
/// On an IPv6 socket of type SOCK_DGRAM or SOCK_RAW, an application can specific the local IP source address to use
/// for sending with the WSASendMsg function. One of the control data objects passed in the WSAMSG structure to the
/// WSASendMsg function may contain an in6_pktinfo structure used to specify the local IPv6 source address to use for sending.
///
///
/// For a dual-stack socket when sending datagrams with the WSASendMsg function and an application wants to specify a
/// specific local IP source address to be used, the method to handle this depends on the destination IP address. When sending to an
/// IPv4 destination address or an IPv4-mapped IPv6 destination address, one of the control data objects passed in the WSAMSG
/// structure pointed to by the lpMsg parameter should contain an in_pktinfo structure containing the local IPv4 source address to
/// use for sending. When sending to an IPv6 destination address that is not a an IPv4-mapped IPv6 address, one of the control data
/// objects passed in the WSAMSG structure pointed to by the lpMsg parameter should contain an in6_pktinfo structure
/// containing the local IPv6 source address to use for sending.
///
/// Note The SO_SNDTIMEO socket option applies only to blocking sockets.
/// Note The successful completion of a WSASendMsg does not indicate that the data was successfully delivered.
///
/// Note When issuing a blocking Winsock call such as WSASendMsg with the lpOverlapped parameter set to NULL, Winsock
/// may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which
/// can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call
/// inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must
/// never be attempted by Winsock clients.
///
/// dwFlags
///
/// The dwFlags input parameter can be used to influence the behavior of the function invocation beyond the options specified for
/// the associated socket. That is, the semantics of this function are determined by the socket options and the dwFlags parameter.
/// The latter is constructed by using the bitwise OR operator with any of the following values.
///
///
///
/// Value
/// Meaning
///
/// -
/// MSG_DONTROUTE
///
/// Specifies that the data should not be subject to routing. A Windows Sockets service provider can choose to ignore this flag.
///
///
/// -
/// MSG_PARTIAL
///
/// Specifies that lpMsg->lpBuffers contains only a partial message. Note that the error code WSAEOPNOTSUPP will be returned by
/// transports that do not support partial message transmissions.
///
///
///
/// The possible values for dwFlags parameter are defined in the Winsock2.h header file.
/// On output, the dwFlags member of the WSAMSGstructure pointed to by the lpMsg parameter is not used.
/// Overlapped Socket I/O
///
/// If an overlapped operation completes immediately, WSASendMsg returns a value of zero and the lpNumberOfBytesSent
/// parameter is updated with the number of bytes sent. If the overlapped operation is successfully initiated and will complete
/// later, WSASendMsg returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesSent is not
/// updated. When the overlapped operation completes, the amount of data transferred is indicated either through the cbTransferred
/// parameter in the completion routine (if specified) or through the lpcbTransfer parameter in WSAGetOverlappedResult.
///
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. See ExitThread for more information.
///
///
/// The WSASendMsg function using overlapped I/O can be called from within the completion routine of a previous , WSARecv,
/// WSARecvFrom, WSARecvMsg, WSASend, WSASendMsg, or WSASendTo function. This permits time-sensitive data transmissions to
/// occur entirely within a preemptive context.
///
///
/// The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are
/// simultaneously outstanding, each must reference a separate WSAOVERLAPPED structure.
///
///
/// If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped
/// operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or
/// WSAGetOverlappedResult to wait or poll on the event object.
///
///
/// If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context
/// information to the completion routine. A caller that passes a non- NULL lpCompletionRoutine and later calls
/// WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of
/// WSAGetOverlappedResult to TRUE. In this case, the usage of the hEvent parameter is undefined, and attempting to
/// wait on the hEvent parameter would produce unpredictable results.
///
///
/// The completion routine follows the same rules as stipulated for Windows file I/O completion routines. The completion routine
/// will not be invoked until the thread is in an alertable wait state, for example, with WSAWaitForMultipleEvents called with the
/// fAlertable parameter set to TRUE.
///
///
/// The transport providers allow an application to invoke send and receive operations from within the context of the socket I/O
/// completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits
/// time-sensitive data transmissions to occur entirely within a preemptive context.
///
/// The prototype of the completion routine is as follows.
///
/// The CompletionRoutine function is a placeholder for an application-defined or library-defined function name. The dwError
/// parameter specifies the completion status for the overlapped operation as indicated by the lpOverlapped parameter. The
/// cbTransferred parameter indicates the number of bytes sent. Currently there are no flag values defined and the dwFlags parameter
/// will be zero. The CompletionRoutine function does not return a value.
///
///
/// Returning from this function allows invocation of another pending completion routine for the socket. All waiting completion
/// routines are called before the alertable thread's wait is satisfied with a return code of WSA_IO_COMPLETION. The completion
/// routines can be called in any order, not necessarily in the same order the overlapped operations are completed. However, the
/// posted buffers are guaranteed to be sent in the same order they are specified.
///
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg int WSAAPI WSASendMsg( SOCKET Handle, LPWSAMSG
// lpMsg, DWORD dwFlags, LPDWORD lpNumberOfBytesSent, LPWSAOVERLAPPED lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE
// lpCompletionRoutine );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "3b2ba645-6a70-4ba2-b4a2-5bde0c7f8d08")]
public static extern WSRESULT WSASendMsg(SOCKET Handle, in WSAMSG lpMsg, MsgFlags dwFlags, out uint lpNumberOfBytesSent, [In, Out, Optional] IntPtr lpOverlapped,
[In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
/// The WSASendTo function sends data to a specific destination, using overlapped I/O where applicable.
/// A descriptor identifying a (possibly connected) socket.
///
/// A pointer to an array of WSABUF structures. Each WSABUF structure contains a pointer to a buffer and the length of the
/// buffer, in bytes. For a Winsock application, once the WSASendTo function is called, the system owns these buffers and the
/// application may not access them. This array must remain valid for the duration of the send operation.
///
/// The number of WSABUF structures in the lpBuffers array.
///
/// A pointer to the number of bytes sent by this call if the I/O operation completes immediately.
///
/// Use NULL for this parameter if the lpOverlapped parameter is not NULL to avoid potentially erroneous results. This
/// parameter can be NULL only if the lpOverlapped parameter is not NULL.
///
///
/// The flags used to modify the behavior of the WSASendTo function call.
/// An optional pointer to the address of the target socket in the SOCKADDR structure.
/// The size, in bytes, of the address in the lpTo parameter.
/// A pointer to a WSAOVERLAPPED structure (ignored for nonoverlapped sockets).
///
/// A pointer to the completion routine called when the send operation has been completed (ignored for nonoverlapped sockets).
///
///
///
/// If no error occurs and the send operation has completed immediately, WSASendTo returns zero. In this case, the completion
/// routine will have already been scheduled to be called once the calling thread is in the alertable state. Otherwise, a value of
/// SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError. The error code
/// WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion will be indicated at
/// a later time. Any other error code indicates that the overlapped operation was not successfully initiated and no completion
/// indication will occur.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEACCES
/// The requested address is a broadcast address, but the appropriate flag was not set.
///
/// -
/// WSAEADDRNOTAVAIL
/// The remote address is not a valid address (such as ADDR_ANY).
///
/// -
/// WSAEAFNOSUPPORT
/// Addresses in the specified family cannot be used with this socket.
///
/// -
/// WSAECONNRESET
///
/// For a UDP datagram socket, this error would indicate that a previous send operation resulted in an ICMP "Port Unreachable" message.
///
///
/// -
/// WSAEDESTADDRREQ
/// A destination address is required.
///
/// -
/// WSAEFAULT
///
/// The lpBuffers, lpTo, lpOverlapped, lpNumberOfBytesSent, or lpCompletionRoutine parameters are not part of the user address
/// space, or the lpTo parameter is too small.
///
///
/// -
/// WSAEHOSTUNREACH
/// A socket operation was attempted to an unreachable host.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEINTR
/// A blocking Windows Socket 1.1 call was canceled through WSACancelBlockingCall.
///
/// -
/// WSAEINVAL
/// The socket has not been bound with bind, or the socket is not created with the overlapped flag.
///
/// -
/// WSAEMSGSIZE
/// The socket is message oriented, and the message is larger than the maximum supported by the underlying transport.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAENETRESET
/// For a datagram socket, this error indicates that the time to live has expired.
///
/// -
/// WSAENETUNREACH
/// The network cannot be reached from this host at this time.
///
/// -
/// WSAENOBUFS
/// The Windows Sockets provider reports a buffer deadlock.
///
/// -
/// WSAENOTCONN
/// The socket is not connected (connection-oriented sockets only).
///
/// -
/// WSAENOTSOCK
/// The descriptor is not a socket.
///
/// -
/// WSAESHUTDOWN
///
/// The socket has been shut down; it is not possible to WSASendTo on a socket after shutdown has been invoked with how set to
/// SD_SEND or SD_BOTH.
///
///
/// -
/// WSAEWOULDBLOCK
///
/// Windows NT: Overlapped sockets: there are too many outstanding overlapped I/O requests. Nonoverlapped sockets: The socket is
/// marked as nonblocking and the send operation cannot be completed immediately.
///
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSA_IO_PENDING
/// An overlapped operation was successfully initiated and completion will be indicated at a later time.
///
/// -
/// WSA_OPERATION_ABORTED
///
/// The overlapped operation has been canceled due to the closure of the socket, or the execution of the SIO_FLUSH command in WSAIoctl.
///
///
///
///
///
/// The WSASendTo function provides enhanced features over the standard sendto function in two important areas:
///
/// -
/// It can be used in conjunction with overlapped sockets to perform overlapped send operations.
///
/// -
/// It allows multiple send buffers to be specified making it applicable to the scatter/gather type of I/O.
///
///
///
/// The WSASendTo function is normally used on a connectionless socket specified by s to send a datagram contained in one or
/// more buffers to a specific peer socket identified by the lpTo parameter. Even if the connectionless socket has been previously
/// connected using the connect function to a specific address, lpTo overrides the destination address for that particular datagram
/// only. On a connection-oriented socket, the lpTo and iToLen parameters are ignored; in this case, the WSASendTo is
/// equivalent to WSASend.
///
///
/// For overlapped sockets (created using WSASocket with flag WSA_FLAG_OVERLAPPED) sending data uses overlapped I/O, unless
/// both lpOverlapped and lpCompletionRoutine are NULL in which case the socket is treated as a nonoverlapped socket. A
/// completion indication will occur (invoking the completion routine or setting of an event object) when the buffer(s) have been
/// consumed by the transport. If the operation does not complete immediately, the final completion status is retrieved through the
/// completion routine or WSAGetOverlappedResult.
///
///
/// Note If a socket is opened, a setsockopt call is made, and then a sendto call is made, Windows Sockets performs an
/// implicit bind function call.
///
///
/// If both lpOverlapped and lpCompletionRoutine are NULL, the socket in this function will be treated as a nonoverlapped socket.
///
///
/// For nonoverlapped sockets, the last two parameters (lpOverlapped, lpCompletionRoutine) are ignored and WSASendTo adopts
/// the same blocking semantics as send. Data is copied from the buffer(s) into the transport buffer. If the socket is nonblocking
/// and stream oriented, and there is not sufficient space in the transport's buffer, WSASendTo returns with only part of the
/// application's buffers having been consumed. Given the same buffer situation and a blocking socket, WSASendTo will block
/// until all of the application's buffer contents have been consumed.
///
///
/// If this function is completed in an overlapped manner, it is the Winsock service provider's responsibility to capture the WSABUF
/// structures before returning from this call. This enables applications to build stack-based WSABUF arrays pointed to by
/// the lpBuffers parameter.
///
///
/// For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying transport, which can
/// be obtained by getting the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the
/// underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.
///
///
/// If the socket is unbound, unique values are assigned to the local association by the system, and the socket is then marked as bound.
///
///
/// If the socket is connected, the getsockname function can be used to determine the local IP address and port associated with the socket.
///
///
/// If the socket is not connected, the getsockname function can be used to determine the local port number associated with the
/// socket but the IP address returned is set to the wildcard address for the given protocol (for example, INADDR_ANY or "0.0.0.0"
/// for IPv4 and IN6ADDR_ANY_INIT or "::" for IPv6).
///
/// The successful completion of a WSASendTo does not indicate that the data was successfully delivered.
///
/// The dwFlags parameter can be used to influence the behavior of the function invocation beyond the options specified for the
/// associated socket. That is, the semantics of this function are determined by the socket options and the dwFlags parameter. The
/// latter is constructed by using the bitwise OR operator with any of any of the values listed in the following table.
///
///
///
/// Value
/// Meaning
///
/// -
/// MSG_DONTROUTE
///
/// Specifies that the data should not be subject to routing. A Windows Socket service provider may choose to ignore this flag.
///
///
/// -
/// MSG_OOB
/// Send OOB data (stream-style socket such as SOCK_STREAM only).
///
/// -
/// MSG_PARTIAL
///
/// Specifies that lpBuffers only contains a partial message. Be aware that the error code WSAEOPNOTSUPP will be returned by
/// transports that do not support partial message transmissions.
///
///
///
///
/// Note When issuing a blocking Winsock call such as WSASendTo with the lpOverlapped parameter set to NULL,
/// Winsock may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation,
/// which can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock
/// call inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and
/// must never be attempted by Winsock clients.
///
/// Overlapped Socket I/O
///
/// If an overlapped operation completes immediately, WSASendTo returns a value of zero and the lpNumberOfBytesSent parameter
/// is updated with the number of bytes sent. If the overlapped operation is successfully initiated and will complete later,
/// WSASendTo returns SOCKET_ERROR and indicates error code WSA_IO_PENDING. In this case, lpNumberOfBytesSent is not
/// updated. When the overlapped operation completes the amount of data transferred is indicated either through the cbTransferred
/// parameter in the completion routine (if specified), or through the lpcbTransfer parameter in WSAGetOverlappedResult.
///
///
/// Note All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous
/// operations can fail if the thread is closed before the operations complete. See ExitThread for more information.
///
///
/// The WSASendTo function using overlapped I/O can be called from within the completion routine of a previous WSARecv,
/// WSARecvFrom, WSASend, or WSASendTo function. This permits time-sensitive data transmissions to occur entirely within a
/// preemptive context.
///
///
/// The lpOverlapped parameter must be valid for the duration of the overlapped operation. If multiple I/O operations are
/// simultaneously outstanding, each must reference a separate WSAOVERLAPPED structure.
///
///
/// If the lpCompletionRoutine parameter is NULL, the hEvent parameter of lpOverlapped is signaled when the overlapped
/// operation completes if it contains a valid event object handle. An application can use WSAWaitForMultipleEvents or
/// WSAGetOverlappedResult to wait or poll on the event object.
///
///
/// If lpCompletionRoutine is not NULL, the hEvent parameter is ignored and can be used by the application to pass context
/// information to the completion routine. A caller that passes a non- NULL lpCompletionRoutine and later calls
/// WSAGetOverlappedResult for the same overlapped I/O request may not set the fWait parameter for that invocation of
/// WSAGetOverlappedResult to TRUE. In this case the usage of the hEvent parameter is undefined, and attempting to
/// wait on the hEvent parameter would produce unpredictable results.
///
///
/// The completion routine follows the same rules as stipulated for Windows file I/O completion routines. The completion routine
/// will not be invoked until the thread is in an alertable wait state such as can occur when the function WSAWaitForMultipleEvents
/// with the fAlertable parameter set to TRUE is invoked.
///
///
/// Transport providers allow an application to invoke send and receive operations from within the context of the socket I/O
/// completion routine, and guarantee that, for a given socket, I/O completion routines will not be nested. This permits
/// time-sensitive data transmissions to occur entirely within a preemptive context.
///
/// The prototype of the completion routine is as follows.
///
/// The CompletionRoutine function is a placeholder for an application-defined or library-defined function name. The dwError
/// parameter specifies the completion status for the overlapped operation as indicated by lpOverlapped. The cbTransferred parameter
/// specifies the number of bytes sent. Currently there are no flag values defined and dwFlags will be zero. This function does not
/// return a value.
///
///
/// Returning from this function allows invocation of another pending completion routine for this socket. All waiting completion
/// routines are called before the alertable thread's wait is satisfied with a return code of WSA_IO_COMPLETION. The completion
/// routines can be called in any order, not necessarily in the same order in which the overlapped operations are completed.
/// However, the posted buffers are guaranteed to be sent in the same order they are specified.
///
/// Example Code
/// The following example demonstrates the use of the WSASendTo function using an event object.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendto int WSAAPI WSASendTo( SOCKET s, LPWSABUF
// lpBuffers, DWORD dwBufferCount, LPDWORD lpNumberOfBytesSent, DWORD dwFlags, const sockaddr *lpTo, int iTolen, LPWSAOVERLAPPED
// lpOverlapped, LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "e3a11522-871c-4d6b-a2e6-ca91ffc2b698")]
public static extern WSRESULT WSASendTo(SOCKET s, [In, MarshalAs(UnmanagedType.LPArray)] WSABUF[] lpBuffers, uint dwBufferCount, out uint lpNumberOfBytesSent,
MsgFlags dwFlags, [In, Optional] SOCKADDR lpTo, int iTolen, [In, Out, Optional] IntPtr lpOverlapped,
[In, Optional, MarshalAs(UnmanagedType.FunctionPtr)] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);
/// The WSASetEvent function sets the state of the specified event object to signaled.
/// Handle that identifies an open event object.
///
/// If the function succeeds, the return value is TRUE.
/// If the function fails, the return value is FALSE. To get extended error information, call WSAGetLastError.
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSA_INVALID_HANDLE
/// The hEvent parameter is not a valid event object handle.
///
///
///
///
/// The WSASetEvent function sets the state of the event object to be signaled.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasetevent BOOL WSAAPI WSASetEvent( WSAEVENT hEvent );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "8a3f41fe-77da-4e4e-975d-00eec7c11446")]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool WSASetEvent(WSAEVENT hEvent);
/// The WSASetLastError function sets the error code that can be retrieved through the WSAGetLastError function.
/// Integer that specifies the error code to be returned by a subsequent WSAGetLastError call.
///
/// This function generates no return values.
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
///
///
///
///
/// The WSASetLastError function allows an application to set the error code to be returned by a subsequent WSAGetLastError
/// call for the current thread. Note that any subsequent Windows Sockets routine called by the application will override the error
/// code as set by this routine.
///
///
/// The error code set by WSASetLastError is different from the error code reset by calling the function getsockopt with SO_ERROR.
///
/// The Windows Sockets error codes used by this function are listed under Windows Sockets Error Codes.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-wsasetlasterror void WSASetLastError( int iError );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "596155ee-3dcc-4ae3-97ab-0653e019cbee")]
public static extern void WSASetLastError(WSRESULT iError);
/// The WSASetService function registers or removes from the registry a service instance within one or more namespaces.
/// A pointer to the service information for registration or deregistration.
///
///
/// A value that determines that operation requested. This parameter can be one of the values from the WSAESETSERVICEOP enumeration
/// type defined in the Winsock2.h header file.
///
///
///
/// Value
/// Meaning
///
/// -
/// RNRSERVICE_REGISTER
///
/// Register the service. For SAP, this means sending out a periodic broadcast. This is an NOP for the DNS namespace. For persistent
/// data stores, this means updating the address information.
///
///
/// -
/// RNRSERVICE_DEREGISTER
///
/// Remove the service from the registry. For SAP, this means stop sending out the periodic broadcast. This is an NOP for the DNS
/// namespace. For persistent data stores this means deleting address information.
///
///
/// -
/// RNRSERVICE_DELETE
///
/// Delete the service from dynamic name and persistent spaces. For services represented by multiple CSADDR_INFO structures (using
/// the SERVICE_MULTIPLE flag), only the specified address will be deleted, and this must match exactly the corresponding
/// CSADDR_INFO structure that was specified when the service was registered.
///
///
///
///
///
///
/// Service install flags value that further controls the operation performed of the WSASetService function. The possible
/// values for this parameter are defined in the Winsock2.h header file.
///
///
///
/// Flag
/// Meaning
///
/// -
/// SERVICE_MULTIPLE
///
/// Controls scope of operation. When this flag is not set, service addresses are managed as a group. A register or removal from the
/// registry invalidates all existing addresses before adding the given address set. When set, the action is only performed on the
/// given address set. A register does not invalidate existing addresses and a removal from the registry only invalidates the given
/// set of addresses.
///
///
///
///
///
///
/// The return value for WSASetService is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is
/// returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEACCES
/// The calling routine does not have sufficient privileges to install the Service.
///
/// -
/// WSAEINVAL
/// One or more required parameters were invalid or missing.
///
/// -
/// WSANOTINITIALISED
///
/// The Ws2_32.dll has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.
///
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
///
/// The WSASetService function can be used to affect a specific namespace provider, all providers associated with a specific
/// namespace, or all providers across all namespaces.
///
///
/// The available values for essOperation and dwControlFlags combine to control operation of the WSASetService function as
/// shown in the following table.
///
///
///
/// Operation
/// Flags
/// Service already exists
/// Service does not exist
///
/// -
/// RNRSERVICE_REGISTER
/// None
/// Overwrites the object. Uses only addresses specified. The object is REGISTERED.
/// Creates a new object. Uses only addresses specified. Object is REGISTERED.
///
/// -
/// RNRSERVICE_REGISTER
/// SERVICE_MULTIPLE
/// Updates the object. Adds new addresses to the existing set. The object is REGISTERED.
/// Creates a new object. Uses all addresses specified. Object is REGISTERED.
///
/// -
/// RNRSERVICE_DEREGISTER
/// None
/// Removes all addresses, but does not remove the object from the namespace. The object is removed from the registry.
/// WSASERVICE_NOT_FOUND
///
/// -
/// RNRSERVICE_DEREGISTER
/// SERVICE_MULTIPLE
///
/// Updates the object. Removes only addresses that are specified. Only marks the object as DEREGISTERED if no addresses are
/// present. Does not remove the object from the namespace.
///
/// WSASERVICE_NOT_FOUND
///
/// -
/// RNRSERVICE_DELETE
/// None
/// Removes the object from the namespace.
/// WSASERVICE_NOT_FOUND
///
/// -
/// RNRSERVICE_DELETE
/// SERVICE_MULTIPLE
/// Removes only addresses that are specified. Only removes object from the namespace if no addresses remain.
/// WSASERVICE_NOT_FOUND
///
///
///
/// Publishing services to directories, such as Active Directory Services, is restricted based on access control lists (ACLs). For
/// more information, see Security Issues for Service Publication.
///
///
/// When the dwControlFlags parameter is set to SERVICE_MULTIPLE, an application can manage its addresses independently. This
/// is useful when the application wants to manage its protocols individually or when the service resides on more than one computer.
/// For instance, when a service uses more than one protocol, it may find that one listening socket aborts but the other sockets
/// remain operational. In this case, the service could remove the aborted address from the registry without affecting the other addresses.
///
///
/// When the dwControlFlags parameter is set to SERVICE_MULTIPLE, an application must not let stale addresses remain in the
/// object. This can happen if the application aborts without issuing a DEREGISTER request. When a service registers, it should
/// store its addresses. On its next invocation, the service should explicitly remove these old stale addresses from the registry
/// before registering new addresses.
///
///
/// Note If ANSI character strings are used, there is a chance that the WSAQUERYSET data in lpqsRegInfo may not contain any
/// results after this function returns. This is because the ANSI version of this method, WSASetServiceA, converts the ANSI
/// data in WSAQUERYSET to Unicode internally, but does not convert the results back to ANSI. This primarily impacts
/// transports that return a "service record handle" used to uniquely identify a record. To work around this issue, applications
/// should use Unicode string data in WSAQUERYSET when calling this function.
///
/// Service Properties
///
/// The following table describes how service property data is represented in a WSAQUERYSET structure. Fields labeled as (Optional)
/// can contain a null pointer.
///
///
///
/// WSAQUERYSET member
/// Service property description
///
/// -
/// dwSize
/// Must be set to sizeof (WSAQUERYSET). This is a versioning mechanism.
///
/// -
/// dwOutputFlags
/// Not applicable and ignored.
///
/// -
/// lpszServiceInstanceName
/// Referenced string contains the service instance name.
///
/// -
/// lpServiceClassId
/// The GUID corresponding to this service class.
///
/// -
/// lpVersion
/// (Optional) Supplies service instance version number.
///
/// -
/// lpszComment
/// (Optional) An optional comment string.
///
/// -
/// dwNameSpace
/// See table that follows.
///
/// -
/// lpNSProviderId
/// See table that follows.
///
/// -
/// lpszContext
/// (Optional) Specifies the starting point of the query in a hierarchical namespace.
///
/// -
/// dwNumberOfProtocols
/// Ignored.
///
/// -
/// lpafpProtocols
/// Ignored.
///
/// -
/// lpszQueryString
/// Ignored.
///
/// -
/// dwNumberOfCsAddrs
/// The number of elements in the array of CSADDR_INFO structures referenced by lpcsaBuffer.
///
/// -
/// lpcsaBuffer
/// A pointer to an array of CSADDR_INFO structures that contain the address(es) that the service is listening on.
///
/// -
/// lpBlob
/// (Optional) This is a pointer to a provider-specific entity.
///
///
///
/// As illustrated in the following, the combination of the dwNameSpace and lpNSProviderId members determine that
/// namespace providers are affected by this function.
///
///
///
/// dwNameSpace
/// lpNSProviderId
/// Scope of impact
///
/// -
/// Ignored
/// Non-null
/// The specified name-space provider.
///
/// -
/// A valid name- space identifier
/// Null
/// All name-space providers that support the indicated namespace.
///
/// -
/// NS_ALL
/// Null
/// All name-space providers.
///
///
///
/// Windows Phone 8: The WSASetServiceW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSASetServiceW function is supported for Windows Store apps on
/// Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasetservicea INT WSAAPI WSASetServiceA( LPWSAQUERYSETA
// lpqsRegInfo, WSAESETSERVICEOP essoperation, DWORD dwControlFlags );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "21a8ff26-4c9e-4846-a75a-1a27c746edab")]
public static extern WSRESULT WSASetService(in WSAQUERYSET lpqsRegInfo, WSAESETSERVICEOP essoperation, ServiceInstallFlags dwControlFlags);
/// The WSASocket function creates a socket that is bound to a specific transport-service provider.
///
/// The address family specification. Possible values for the address family are defined in the Winsock2.h header file.
///
/// On the Windows SDK released for Windows Vista and later, the organization of header files has changed and the possible values
/// for the address family are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in
/// Winsock2.h, and should never be used directly.
///
///
/// The values currently supported are AF_INET or AF_INET6, which are the Internet address family formats for IPv4 and IPv6. Other
/// options for address family (AF_NETBIOS for use with NetBIOS, for example) are supported if a Windows Sockets service provider
/// for the address family is installed. Note that the values for the AF_ address family and PF_ protocol family constants are
/// identical (for example, AF_INET and PF_INET), so either constant can be used.
///
/// The table below lists common values for address family although many other values are possible.
///
///
/// Af
/// Meaning
///
/// -
/// AF_UNSPEC 0
/// The address family is unspecified.
///
/// -
/// AF_INET 2
/// The Internet Protocol version 4 (IPv4) address family.
///
/// -
/// AF_IPX 6
///
/// The IPX/SPX address family. This address family is only supported if the NWLink IPX/SPX NetBIOS Compatible Transport protocol is
/// installed. This address family is not supported on Windows Vista and later.
///
///
/// -
/// AF_APPLETALK 16
///
/// The AppleTalk address family. This address family is only supported if the AppleTalk protocol is installed. This address family
/// is not supported on Windows Vista and later.
///
///
/// -
/// AF_NETBIOS 17
///
/// The NetBIOS address family. This address family is only supported if the Windows Sockets provider for NetBIOS is installed. The
/// Windows Sockets provider for NetBIOS is supported on 32-bit versions of Windows. This provider is installed by default on 32-bit
/// versions of Windows. The Windows Sockets provider for NetBIOS is not supported on 64-bit versions of windows including Windows
/// 7, Windows Server 2008, Windows Vista, Windows Server 2003, or Windows XP. The Windows Sockets provider for NetBIOS only
/// supports sockets where the type parameter is set to SOCK_DGRAM. The Windows Sockets provider for NetBIOS is not directly related
/// to the NetBIOS programming interface. The NetBIOS programming interface is not supported on Windows Vista, Windows Server 2008,
/// and later.
///
///
/// -
/// AF_INET6 23
/// The Internet Protocol version 6 (IPv6) address family.
///
/// -
/// AF_IRDA 26
///
/// The Infrared Data Association (IrDA) address family. This address family is only supported if the computer has an infrared port
/// and driver installed.
///
///
/// -
/// AF_BTH 32
///
/// The Bluetooth address family. This address family is supported on Windows XP with SP2 or later if the computer has a Bluetooth
/// adapter and driver installed.
///
///
///
///
///
/// The type specification for the new socket.
/// Possible values for the socket type are defined in the Winsock2.h header file.
/// The following table lists the possible values for the type parameter supported for Windows Sockets 2:
///
///
/// Type
/// Meaning
///
/// -
/// SOCK_STREAM 1
///
/// A socket type that provides sequenced, reliable, two-way, connection-based byte streams with an OOB data transmission mechanism.
/// This socket type uses the Transmission Control Protocol (TCP) for the Internet address family (AF_INET or AF_INET6).
///
///
/// -
/// SOCK_DGRAM 2
///
/// A socket type that supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length.
/// This socket type uses the User Datagram Protocol (UDP) for the Internet address family (AF_INET or AF_INET6).
///
///
/// -
/// SOCK_RAW 3
///
/// A socket type that provides a raw socket that allows an application to manipulate the next upper-layer protocol header. To
/// manipulate the IPv4 header, the IP_HDRINCL socket option must be set on the socket. To manipulate the IPv6 header, the
/// IPV6_HDRINCL socket option must be set on the socket.
///
///
/// -
/// SOCK_RDM 4
///
/// A socket type that provides a reliable message datagram. An example of this type is the Pragmatic General Multicast (PGM)
/// multicast protocol implementation in Windows, often referred to as reliable multicast programming. This type value is only
/// supported if the Reliable Multicast Protocol is installed.
///
///
/// -
/// SOCK_SEQPACKET 5
/// A socket type that provides a pseudo-stream packet based on datagrams.
///
///
///
/// In Windows Sockets 2, new socket types were introduced. An application can dynamically discover the attributes of each available
/// transport protocol through the WSAEnumProtocols function. So an application can determine the possible socket type and protocol
/// options for an address family and use this information when specifying this parameter. Socket type definitions in the Winsock2.h
/// and Ws2def.h header files will be periodically updated as new socket types, address families, and protocols are defined.
///
/// In Windows Sockets 1.1, the only possible socket types are SOCK_DGRAM and SOCK_STREAM.
///
///
///
/// The protocol to be used. The possible options for the protocol parameter are specific to the address family and socket type
/// specified. Possible values for the protocol are defined are defined in the Winsock2.h and Wsrm.h header files.
///
///
/// On the Windows SDK released for Windows Vista and later,, the organization of header files has changed and this parameter can be
/// one of the values from the IPPROTO enumeration type defined in the Ws2def.h header file. Note that the Ws2def.h header
/// file is automatically included in Winsock2.h, and should never be used directly.
///
///
/// If a value of 0 is specified, the caller does not wish to specify a protocol and the service provider will choose the protocol
/// to use.
///
///
/// When the af parameter is AF_INET or AF_INET6 and the type is SOCK_RAW, the value specified for the protocol is set in the
/// protocol field of the IPv6 or IPv4 packet header.
///
/// The table below lists common values for the protocol although many other values are possible.
///
///
/// protocol
/// Meaning
///
/// -
/// IPPROTO_ICMP 1
///
/// The Internet Control Message Protocol (ICMP). This is a possible value when the af parameter is AF_UNSPEC, AF_INET, or AF_INET6
/// and the type parameter is SOCK_RAW or unspecified. This protocol value is supported on Windows XP and later.
///
///
/// -
/// IPPROTO_IGMP 2
///
/// The Internet Group Management Protocol (IGMP). This is a possible value when the af parameter is AF_UNSPEC, AF_INET, or AF_INET6
/// and the type parameter is SOCK_RAW or unspecified. This protocol value is supported on Windows XP and later.
///
///
/// -
/// BTHPROTO_RFCOMM 3
///
/// The Bluetooth Radio Frequency Communications (Bluetooth RFCOMM) protocol. This is a possible value when the af parameter is
/// AF_BTH and the type parameter is SOCK_STREAM. This protocol value is supported on Windows XP with SP2 or later.
///
///
/// -
/// IPPROTO_TCP 6
///
/// The Transmission Control Protocol (TCP). This is a possible value when the af parameter is AF_INET or AF_INET6 and the type
/// parameter is SOCK_STREAM.
///
///
/// -
/// IPPROTO_UDP 17
///
/// The User Datagram Protocol (UDP). This is a possible value when the af parameter is AF_INET or AF_INET6 and the type parameter
/// is SOCK_DGRAM.
///
///
/// -
/// IPPROTO_ICMPV6 58
///
/// The Internet Control Message Protocol Version 6 (ICMPv6). This is a possible value when the af parameter is AF_UNSPEC, AF_INET,
/// or AF_INET6 and the type parameter is SOCK_RAW or unspecified. This protocol value is supported on Windows XP and later.
///
///
/// -
/// IPPROTO_RM 113
///
/// The PGM protocol for reliable multicast. This is a possible value when the af parameter is AF_INET and the type parameter is
/// SOCK_RDM. On the Windows SDK released for Windows Vista and later, this protocol is also called IPPROTO_PGM. This protocol value
/// is only supported if the Reliable Multicast Protocol is installed.
///
///
///
///
///
/// A pointer to a WSAPROTOCOL_INFO structure that defines the characteristics of the socket to be created. If this parameter is not
/// NULL, the socket will be bound to the provider associated with the indicated WSAPROTOCOL_INFO structure.
///
///
/// An existing socket group ID or an appropriate action to take when creating a new socket and a new socket group.
///
/// If g is an existing socket group ID, join the new socket to this socket group, provided all the requirements set by this group
/// are met.
///
/// If g is not an existing socket group ID, then the following values are possible.
///
///
/// g
/// Meaning
///
/// -
/// 0
/// No group operation is performed.
///
/// -
/// SG_UNCONSTRAINED_GROUP 0x01
///
/// Create an unconstrained socket group and have the new socket be the first member. For an unconstrained group, Winsock does not
/// constrain all sockets in the socket group to have been created with the same value for the type and protocol parameters.
///
///
/// -
/// SG_CONSTRAINED_GROUP 0x02
///
/// Create a constrained socket group and have the new socket be the first member. For a contrained socket group, Winsock constrains
/// all sockets in the socket group to have been created with the same value for the type and protocol parameters. A constrained
/// socket group may consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the
/// same address on the same host.
///
///
///
///
/// Note The SG_UNCONSTRAINED_GROUP and SG_CONSTRAINED_GROUP constants are not currently defined in a public header file.
///
///
///
/// A set of flags used to specify additional socket attributes.
/// A combination of these flags may be set, although some combinations are not allowed.
///
///
/// Value
/// Meaning
///
/// -
/// WSA_FLAG_OVERLAPPED 0x01
///
/// Create a socket that supports overlapped I/O operations. Most sockets should be created with this flag set. Overlapped sockets
/// can utilize WSASend, WSASendTo, WSARecv, WSARecvFrom, and WSAIoctl for overlapped I/O operations, which allow multiple
/// operations to be initiated and in progress simultaneously. All functions that allow overlapped operation (WSASend, WSARecv,
/// WSASendTo, WSARecvFrom, WSAIoctl) also support nonoverlapped usage on an overlapped socket if the values for parameters related
/// to overlapped operations are NULL.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_C_ROOT 0x02
///
/// Create a socket that will be a c_root in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the control plane for a
/// multipoint session is rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with the
/// XP1_SUPPORT_MULTIPOINT and XP1_MULTIPOINT_CONTROL_PLANE flags set. When the lpProtocolInfo parameter is not NULL, the
/// WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the lpProtocolInfo
/// parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values specified for the
/// af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a multipoint session.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_C_LEAF 0x04
///
/// Create a socket that will be a c_leaf in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the control plane for a
/// multipoint session is non-rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with
/// the XP1_SUPPORT_MULTIPOINT flag set and the XP1_MULTIPOINT_CONTROL_PLANE flag not set. When the lpProtocolInfo parameter is not
/// NULL, the WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the
/// lpProtocolInfo parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values
/// specified for the af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a
/// multipoint session.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_D_ROOT 0x08
///
/// Create a socket that will be a d_root in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the data plane for a
/// multipoint session is rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with the
/// XP1_SUPPORT_MULTIPOINT and XP1_MULTIPOINT_DATA_PLANE flags set. When the lpProtocolInfo parameter is not NULL, the
/// WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the lpProtocolInfo
/// parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values specified for the
/// af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a multipoint session.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_D_LEAF 0x10
///
/// Create a socket that will be a d_leaf in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the data plane for a
/// multipoint session is non-rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with
/// the XP1_SUPPORT_MULTIPOINT flag set and the XP1_MULTIPOINT_DATA_PLANE flag not set. When the lpProtocolInfo parameter is not
/// NULL, the WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the
/// lpProtocolInfo parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values
/// specified for the af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a
/// multipoint session.
///
///
/// -
/// WSA_FLAG_ACCESS_SYSTEM_SECURITY 0x40
///
/// Create a socket that allows the the ability to set a security descriptor on the socket that contains a security access control
/// list (SACL) as opposed to just a discretionary access control list (DACL). SACLs are used for generating audits and alarms when
/// an access check occurs on the object. For a socket, an access check occurs to determine whether the socket should be allowed to
/// bind to a specific address specified to the bind function. The ACCESS_SYSTEM_SECURITY access right controls the ability to get
/// or set the SACL in an object's security descriptor. The system grants this access right only if the SE_SECURITY_NAME privilege
/// is enabled in the access token of the requesting thread.
///
///
/// -
/// WSA_FLAG_NO_HANDLE_INHERIT 0x80
///
/// Create a socket that is non-inheritable. A socket handle created by the WSASocket or the socket function is inheritable by
/// default. When this flag is set, the socket handle is non-inheritable. The GetHandleInformation function can be used to determine
/// if a socket handle was created with the WSA_FLAG_NO_HANDLE_INHERIT flag set. The GetHandleInformation function will return that
/// the HANDLE_FLAG_INHERIT value is set. This flag is supported on Windows 7 with SP1, Windows Server 2008 R2 with SP1, and later
///
///
///
///
/// Important For multipoint sockets, only one of WSA_FLAG_MULTIPOINT_C_ROOT or WSA_FLAG_MULTIPOINT_C_LEAF
/// flags can be specified, and only one of WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF flags can be
/// specified. Refer to Multipoint and Multicast Semantics for additional information.
///
///
///
///
/// If no error occurs, WSASocket returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is
/// returned, and a specific error code can be retrieved by calling WSAGetLastError.
///
/// Note This error code description is Microsoft-specific.
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEAFNOSUPPORT
/// The specified address family is not supported.
///
/// -
/// WSAEFAULT
/// The lpProtocolInfo parameter is not in a valid part of the process address space.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEINVAL
/// This value is true for any of the following conditions.
///
/// -
/// WSAEINVALIDPROVIDER
/// The service provider returned a version other than 2.2.
///
/// -
/// WSAEINVALIDPROCTABLE
/// The service provider returned an invalid or incomplete procedure table to the WSPStartup.
///
/// -
/// WSAEMFILE
/// No more socket descriptors are available.
///
/// -
/// WSAENOBUFS
/// No buffer space is available. The socket cannot be created.
///
/// -
/// WSAEPROTONOSUPPORT
/// The specified protocol is not supported.
///
/// -
/// WSAEPROTOTYPE
/// The specified protocol is the wrong type for this socket.
///
/// -
/// WSAEPROVIDERFAILEDINIT
///
/// The service provider failed to initialize. This error is returned if a layered service provider (LSP) or namespace provider was
/// improperly installed or the provider fails to operate correctly.
///
///
/// -
/// WSAESOCKTNOSUPPORT
/// The specified socket type is not supported in this address family.
///
///
///
///
///
/// The WSASocket function causes a socket descriptor and any related resources to be allocated and associated with a
/// transport-service provider. Most sockets should be created with the WSA_FLAG_OVERLAPPED attribute set in the dwFlags
/// parameter. A socket created with this attribute supports the use of overlapped I/O operations which provide higher performance.
/// By default, a socket created with the WSASocket function will not have this overlapped attribute set. In contrast, the
/// socket function creates a socket that supports overlapped I/O operations as the default behavior.
///
///
/// If the lpProtocolInfo parameter is NULL, Winsock will utilize the first available transport-service provider that
/// supports the requested combination of address family, socket type and protocol specified in the af, type, and protocol parameters.
///
///
/// If the lpProtocolInfo parameter is not NULL, the socket will be bound to the provider associated with the indicated
/// WSAPROTOCOL_INFO structure. In this instance, the application can supply the manifest constant FROM_PROTOCOL_INFO as the
/// value for any of af, type, or protocol parameters. This indicates that the corresponding values from the indicated
/// WSAPROTOCOL_INFO structure ( iAddressFamily, iSocketType, iProtocol) are to be assumed. In any case,
/// the values specified for af, type, and protocol are passed unmodified to the transport-service provider.
///
///
/// When selecting a protocol and its supporting service provider based on af, type, and protocol, this procedure will only choose a
/// base protocol or a protocol chain, not a protocol layer by itself. Unchained protocol layers are not considered to have partial
/// matches on type or af, either. That is, they do not lead to an error code of WSAEAFNOSUPPORT or WSAEPROTONOSUPPORT, if no
/// suitable protocol is found.
///
///
/// Note The manifest constant AF_UNSPEC continues to be defined in the header file but its use is strongly
/// discouraged, as this can cause ambiguity in interpreting the value of the protocol parameter.
///
///
/// Applications are encouraged to use AF_INET6 for the af parameter and create a dual-mode socket that can be used with both
/// IPv4 and IPv6.
///
///
/// If a socket is created using the WSASocket function, then the dwFlags parameter must have the WSA_FLAG_OVERLAPPED
/// attribute set for the SO_RCVTIMEO or SO_SNDTIMEO socket options to function properly. Otherwise the timeout never
/// takes effect on the socket.
///
///
/// Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before
/// any data can be sent or received on them. A connection to a specified socket is established with a connect or WSAConnect
/// function call. Once connected, data can be transferred using send/WSASend and recv/WSARecv calls. When a session has been
/// completed, the closesocket function should be called to release the resources associated with the socket. For
/// connection-oriented sockets, the shutdown function should be called to stop data transfer on the socket before calling the
/// closesocket function.
///
///
/// The communications protocols used to implement a reliable, connection-oriented socket ensure that data is not lost or
/// duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length
/// of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.
///
///
/// Connectionless, message-oriented sockets allow sending and receiving of datagrams to and from arbitrary peers using
/// sendto/WSASendTo and recvfrom/WSARecvFrom. If such a socket is connected to a specific peer, datagrams can be sent to that peer
/// using send/WSASend and can be received from (only) this peer using recv/WSARecv.
///
///
/// Support for sockets with type SOCK_RAW is not required, but service providers are encouraged to support raw sockets
/// whenever possible.
///
///
/// The WSASocket function can be used to create a socket to be used by a service so that if another socket tries to bind to
/// the same port used by the service, and audit record is generared. To enable this option, an application would need to do the following:
///
///
/// -
///
/// Call the AdjustTokenPrivileges function to enable the SE_SECURITY_NAME privilege in the access token for the process.
/// This privilege is required to set the ACCESS_SYSTEM_SECURITY access rights on the security descriptor for an object.
///
///
/// -
///
/// Call the WSASocket function to create a socket with dwFlag with the WSA_FLAG_ACCESS_SYSTEM_SECURITY option set.
/// The WSASocket function will fail if the AdjustTokenPrivileges function is not called first to enable the
/// SE_SECURITY_NAME privilege needed for this operation.
///
///
/// -
///
/// Call the SetSecurityInfo function to set a security descriptor with a System Access Control List (SACL) on the socket. The
/// socket handle returned by the WSASocket function is passed in the handle parameter. If the function succeeds, this will
/// set the the ACCESS_SYSTEM_SECURITY access right on the security descriptor for the socket.
///
///
/// -
///
/// Call the bindfunction to bind the socket to a specific port. If the bind function succeeds, then an audit entry is
/// generated if another socket tries to bind to the same port.
///
///
/// -
///
/// Call the AdjustTokenPrivileges function to remove the SE_SECURITY_NAME privilege in the access token for the process,
/// since this is no longer needed.
///
///
///
///
/// For more information on ACCESS_SYSTEM_SECURITY, see SACL Access Right and Audit Generation in the Authorization documentation.
///
/// Socket Groups
///
/// WinSock 2 introduced the notion of a socket group as a means for an application, or cooperating set of applications, to indicate
/// to an underlying service provider that a particular set of sockets are related and that the group thus formed has certain
/// attributes. Group attributes include relative priorities of the individual sockets within the group and a group quality of
/// service specification.
///
///
/// Applications that need to exchange multimedia streams over the network are an example where being able to establish a specific
/// relationship among a set of sockets could be beneficial. It is up to the transport on how to treat socket groups.
///
///
/// The WSASocket and WSAAccept functions can be used to explicitly create and join a socket group when creating a new
/// socket. The socket group ID for a socket can be retrieved by using the getsockopt function with level parameter set to
/// SOL_SOCKET and the optname parameter set to SO_GROUP_ID. A socket group and its associated socket group ID remain valid
/// until the last socket belonging to this socket group is closed. Socket group IDs are unique across all processes for a given
/// service provider. A socket group of zero indicates that the socket is not member of a socket group.
///
///
/// The relative group priority of a socket group can be accessed by using the getsockopt function with the level parameter set to
/// SOL_SOCKET and the optname parameter set to SO_GROUP_PRIORITY. The relative group priority of a socket group can be set
/// by using setsockopt with the level parameter set to SOL_SOCKET and the optname parameter set to SO_GROUP_PRIORITY.
///
///
/// The Winsock provider included with Windows allows the creation of socket groups and it enforces the SG_CONSTRAINED_GROUP. All
/// sockets in a constrained socket group must be created with the same value for the type and protocol parameters. A constrained
/// socket group may consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the
/// same address on the same host. This is the only restriction applied to a socket group by the Winsock provider included with
/// Windows. The socket group priority is not currently used by the Winsock provider or the TCP/IP stack included with Windows.
///
/// Example Code
/// The following example demonstrates the use of the WSASocket function.
///
/// Windows Phone 8: The WSASocketW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSASocketW function is supported for Windows Store apps on
/// Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketa SOCKET WSAAPI WSASocketA( int af, int type,
// int protocol, LPWSAPROTOCOL_INFOA lpProtocolInfo, GROUP g, DWORD dwFlags );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "dcf2e543-de54-43d9-9e45-4cb935da3548")]
public static extern SOCKET WSASocket(ADDRESS_FAMILY af, SOCK type, IPPROTO protocol, in WSAPROTOCOL_INFO lpProtocolInfo, GROUP g, WSA_FLAG dwFlags);
/// The WSASocket function creates a socket that is bound to a specific transport-service provider.
///
/// The address family specification. Possible values for the address family are defined in the Winsock2.h header file.
///
/// On the Windows SDK released for Windows Vista and later, the organization of header files has changed and the possible values
/// for the address family are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in
/// Winsock2.h, and should never be used directly.
///
///
/// The values currently supported are AF_INET or AF_INET6, which are the Internet address family formats for IPv4 and IPv6. Other
/// options for address family (AF_NETBIOS for use with NetBIOS, for example) are supported if a Windows Sockets service provider
/// for the address family is installed. Note that the values for the AF_ address family and PF_ protocol family constants are
/// identical (for example, AF_INET and PF_INET), so either constant can be used.
///
/// The table below lists common values for address family although many other values are possible.
///
///
/// Af
/// Meaning
///
/// -
/// AF_UNSPEC 0
/// The address family is unspecified.
///
/// -
/// AF_INET 2
/// The Internet Protocol version 4 (IPv4) address family.
///
/// -
/// AF_IPX 6
///
/// The IPX/SPX address family. This address family is only supported if the NWLink IPX/SPX NetBIOS Compatible Transport protocol is
/// installed. This address family is not supported on Windows Vista and later.
///
///
/// -
/// AF_APPLETALK 16
///
/// The AppleTalk address family. This address family is only supported if the AppleTalk protocol is installed. This address family
/// is not supported on Windows Vista and later.
///
///
/// -
/// AF_NETBIOS 17
///
/// The NetBIOS address family. This address family is only supported if the Windows Sockets provider for NetBIOS is installed. The
/// Windows Sockets provider for NetBIOS is supported on 32-bit versions of Windows. This provider is installed by default on 32-bit
/// versions of Windows. The Windows Sockets provider for NetBIOS is not supported on 64-bit versions of windows including Windows
/// 7, Windows Server 2008, Windows Vista, Windows Server 2003, or Windows XP. The Windows Sockets provider for NetBIOS only
/// supports sockets where the type parameter is set to SOCK_DGRAM. The Windows Sockets provider for NetBIOS is not directly related
/// to the NetBIOS programming interface. The NetBIOS programming interface is not supported on Windows Vista, Windows Server 2008,
/// and later.
///
///
/// -
/// AF_INET6 23
/// The Internet Protocol version 6 (IPv6) address family.
///
/// -
/// AF_IRDA 26
///
/// The Infrared Data Association (IrDA) address family. This address family is only supported if the computer has an infrared port
/// and driver installed.
///
///
/// -
/// AF_BTH 32
///
/// The Bluetooth address family. This address family is supported on Windows XP with SP2 or later if the computer has a Bluetooth
/// adapter and driver installed.
///
///
///
///
///
/// The type specification for the new socket.
/// Possible values for the socket type are defined in the Winsock2.h header file.
/// The following table lists the possible values for the type parameter supported for Windows Sockets 2:
///
///
/// Type
/// Meaning
///
/// -
/// SOCK_STREAM 1
///
/// A socket type that provides sequenced, reliable, two-way, connection-based byte streams with an OOB data transmission mechanism.
/// This socket type uses the Transmission Control Protocol (TCP) for the Internet address family (AF_INET or AF_INET6).
///
///
/// -
/// SOCK_DGRAM 2
///
/// A socket type that supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length.
/// This socket type uses the User Datagram Protocol (UDP) for the Internet address family (AF_INET or AF_INET6).
///
///
/// -
/// SOCK_RAW 3
///
/// A socket type that provides a raw socket that allows an application to manipulate the next upper-layer protocol header. To
/// manipulate the IPv4 header, the IP_HDRINCL socket option must be set on the socket. To manipulate the IPv6 header, the
/// IPV6_HDRINCL socket option must be set on the socket.
///
///
/// -
/// SOCK_RDM 4
///
/// A socket type that provides a reliable message datagram. An example of this type is the Pragmatic General Multicast (PGM)
/// multicast protocol implementation in Windows, often referred to as reliable multicast programming. This type value is only
/// supported if the Reliable Multicast Protocol is installed.
///
///
/// -
/// SOCK_SEQPACKET 5
/// A socket type that provides a pseudo-stream packet based on datagrams.
///
///
///
/// In Windows Sockets 2, new socket types were introduced. An application can dynamically discover the attributes of each available
/// transport protocol through the WSAEnumProtocols function. So an application can determine the possible socket type and protocol
/// options for an address family and use this information when specifying this parameter. Socket type definitions in the Winsock2.h
/// and Ws2def.h header files will be periodically updated as new socket types, address families, and protocols are defined.
///
/// In Windows Sockets 1.1, the only possible socket types are SOCK_DGRAM and SOCK_STREAM.
///
///
///
/// The protocol to be used. The possible options for the protocol parameter are specific to the address family and socket type
/// specified. Possible values for the protocol are defined are defined in the Winsock2.h and Wsrm.h header files.
///
///
/// On the Windows SDK released for Windows Vista and later,, the organization of header files has changed and this parameter can be
/// one of the values from the IPPROTO enumeration type defined in the Ws2def.h header file. Note that the Ws2def.h header
/// file is automatically included in Winsock2.h, and should never be used directly.
///
///
/// If a value of 0 is specified, the caller does not wish to specify a protocol and the service provider will choose the protocol
/// to use.
///
///
/// When the af parameter is AF_INET or AF_INET6 and the type is SOCK_RAW, the value specified for the protocol is set in the
/// protocol field of the IPv6 or IPv4 packet header.
///
/// The table below lists common values for the protocol although many other values are possible.
///
///
/// protocol
/// Meaning
///
/// -
/// IPPROTO_ICMP 1
///
/// The Internet Control Message Protocol (ICMP). This is a possible value when the af parameter is AF_UNSPEC, AF_INET, or AF_INET6
/// and the type parameter is SOCK_RAW or unspecified. This protocol value is supported on Windows XP and later.
///
///
/// -
/// IPPROTO_IGMP 2
///
/// The Internet Group Management Protocol (IGMP). This is a possible value when the af parameter is AF_UNSPEC, AF_INET, or AF_INET6
/// and the type parameter is SOCK_RAW or unspecified. This protocol value is supported on Windows XP and later.
///
///
/// -
/// BTHPROTO_RFCOMM 3
///
/// The Bluetooth Radio Frequency Communications (Bluetooth RFCOMM) protocol. This is a possible value when the af parameter is
/// AF_BTH and the type parameter is SOCK_STREAM. This protocol value is supported on Windows XP with SP2 or later.
///
///
/// -
/// IPPROTO_TCP 6
///
/// The Transmission Control Protocol (TCP). This is a possible value when the af parameter is AF_INET or AF_INET6 and the type
/// parameter is SOCK_STREAM.
///
///
/// -
/// IPPROTO_UDP 17
///
/// The User Datagram Protocol (UDP). This is a possible value when the af parameter is AF_INET or AF_INET6 and the type parameter
/// is SOCK_DGRAM.
///
///
/// -
/// IPPROTO_ICMPV6 58
///
/// The Internet Control Message Protocol Version 6 (ICMPv6). This is a possible value when the af parameter is AF_UNSPEC, AF_INET,
/// or AF_INET6 and the type parameter is SOCK_RAW or unspecified. This protocol value is supported on Windows XP and later.
///
///
/// -
/// IPPROTO_RM 113
///
/// The PGM protocol for reliable multicast. This is a possible value when the af parameter is AF_INET and the type parameter is
/// SOCK_RDM. On the Windows SDK released for Windows Vista and later, this protocol is also called IPPROTO_PGM. This protocol value
/// is only supported if the Reliable Multicast Protocol is installed.
///
///
///
///
///
/// A pointer to a WSAPROTOCOL_INFO structure that defines the characteristics of the socket to be created. If this parameter is not
/// NULL, the socket will be bound to the provider associated with the indicated WSAPROTOCOL_INFO structure.
///
///
/// An existing socket group ID or an appropriate action to take when creating a new socket and a new socket group.
///
/// If g is an existing socket group ID, join the new socket to this socket group, provided all the requirements set by this group
/// are met.
///
/// If g is not an existing socket group ID, then the following values are possible.
///
///
/// g
/// Meaning
///
/// -
/// 0
/// No group operation is performed.
///
/// -
/// SG_UNCONSTRAINED_GROUP 0x01
///
/// Create an unconstrained socket group and have the new socket be the first member. For an unconstrained group, Winsock does not
/// constrain all sockets in the socket group to have been created with the same value for the type and protocol parameters.
///
///
/// -
/// SG_CONSTRAINED_GROUP 0x02
///
/// Create a constrained socket group and have the new socket be the first member. For a contrained socket group, Winsock constrains
/// all sockets in the socket group to have been created with the same value for the type and protocol parameters. A constrained
/// socket group may consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the
/// same address on the same host.
///
///
///
///
/// Note The SG_UNCONSTRAINED_GROUP and SG_CONSTRAINED_GROUP constants are not currently defined in a public header file.
///
///
///
/// A set of flags used to specify additional socket attributes.
/// A combination of these flags may be set, although some combinations are not allowed.
///
///
/// Value
/// Meaning
///
/// -
/// WSA_FLAG_OVERLAPPED 0x01
///
/// Create a socket that supports overlapped I/O operations. Most sockets should be created with this flag set. Overlapped sockets
/// can utilize WSASend, WSASendTo, WSARecv, WSARecvFrom, and WSAIoctl for overlapped I/O operations, which allow multiple
/// operations to be initiated and in progress simultaneously. All functions that allow overlapped operation (WSASend, WSARecv,
/// WSASendTo, WSARecvFrom, WSAIoctl) also support nonoverlapped usage on an overlapped socket if the values for parameters related
/// to overlapped operations are NULL.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_C_ROOT 0x02
///
/// Create a socket that will be a c_root in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the control plane for a
/// multipoint session is rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with the
/// XP1_SUPPORT_MULTIPOINT and XP1_MULTIPOINT_CONTROL_PLANE flags set. When the lpProtocolInfo parameter is not NULL, the
/// WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the lpProtocolInfo
/// parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values specified for the
/// af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a multipoint session.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_C_LEAF 0x04
///
/// Create a socket that will be a c_leaf in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the control plane for a
/// multipoint session is non-rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with
/// the XP1_SUPPORT_MULTIPOINT flag set and the XP1_MULTIPOINT_CONTROL_PLANE flag not set. When the lpProtocolInfo parameter is not
/// NULL, the WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the
/// lpProtocolInfo parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values
/// specified for the af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a
/// multipoint session.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_D_ROOT 0x08
///
/// Create a socket that will be a d_root in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the data plane for a
/// multipoint session is rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with the
/// XP1_SUPPORT_MULTIPOINT and XP1_MULTIPOINT_DATA_PLANE flags set. When the lpProtocolInfo parameter is not NULL, the
/// WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the lpProtocolInfo
/// parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values specified for the
/// af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a multipoint session.
///
///
/// -
/// WSA_FLAG_MULTIPOINT_D_LEAF 0x10
///
/// Create a socket that will be a d_leaf in a multipoint session. This attribute is only allowed if the WSAPROTOCOL_INFO structure
/// for the transport provider that creates the socket supports a multipoint or multicast mechanism and the data plane for a
/// multipoint session is non-rooted. This would be indicated by the dwServiceFlags1 member of the WSAPROTOCOL_INFO structure with
/// the XP1_SUPPORT_MULTIPOINT flag set and the XP1_MULTIPOINT_DATA_PLANE flag not set. When the lpProtocolInfo parameter is not
/// NULL, the WSAPROTOCOL_INFO structure for the transport provider is pointed to by the lpProtocolInfo parameter. When the
/// lpProtocolInfo parameter is NULL, the WSAPROTOCOL_INFO structure is based on the transport provider selected by the values
/// specified for the af, type, and protocol parameters. Refer to Multipoint and Multicast Semantics for additional information on a
/// multipoint session.
///
///
/// -
/// WSA_FLAG_ACCESS_SYSTEM_SECURITY 0x40
///
/// Create a socket that allows the the ability to set a security descriptor on the socket that contains a security access control
/// list (SACL) as opposed to just a discretionary access control list (DACL). SACLs are used for generating audits and alarms when
/// an access check occurs on the object. For a socket, an access check occurs to determine whether the socket should be allowed to
/// bind to a specific address specified to the bind function. The ACCESS_SYSTEM_SECURITY access right controls the ability to get
/// or set the SACL in an object's security descriptor. The system grants this access right only if the SE_SECURITY_NAME privilege
/// is enabled in the access token of the requesting thread.
///
///
/// -
/// WSA_FLAG_NO_HANDLE_INHERIT 0x80
///
/// Create a socket that is non-inheritable. A socket handle created by the WSASocket or the socket function is inheritable by
/// default. When this flag is set, the socket handle is non-inheritable. The GetHandleInformation function can be used to determine
/// if a socket handle was created with the WSA_FLAG_NO_HANDLE_INHERIT flag set. The GetHandleInformation function will return that
/// the HANDLE_FLAG_INHERIT value is set. This flag is supported on Windows 7 with SP1, Windows Server 2008 R2 with SP1, and later
///
///
///
///
/// Important For multipoint sockets, only one of WSA_FLAG_MULTIPOINT_C_ROOT or WSA_FLAG_MULTIPOINT_C_LEAF
/// flags can be specified, and only one of WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF flags can be
/// specified. Refer to Multipoint and Multicast Semantics for additional information.
///
///
///
///
/// If no error occurs, WSASocket returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is
/// returned, and a specific error code can be retrieved by calling WSAGetLastError.
///
/// Note This error code description is Microsoft-specific.
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEAFNOSUPPORT
/// The specified address family is not supported.
///
/// -
/// WSAEFAULT
/// The lpProtocolInfo parameter is not in a valid part of the process address space.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSAEINVAL
/// This value is true for any of the following conditions.
///
/// -
/// WSAEINVALIDPROVIDER
/// The service provider returned a version other than 2.2.
///
/// -
/// WSAEINVALIDPROCTABLE
/// The service provider returned an invalid or incomplete procedure table to the WSPStartup.
///
/// -
/// WSAEMFILE
/// No more socket descriptors are available.
///
/// -
/// WSAENOBUFS
/// No buffer space is available. The socket cannot be created.
///
/// -
/// WSAEPROTONOSUPPORT
/// The specified protocol is not supported.
///
/// -
/// WSAEPROTOTYPE
/// The specified protocol is the wrong type for this socket.
///
/// -
/// WSAEPROVIDERFAILEDINIT
///
/// The service provider failed to initialize. This error is returned if a layered service provider (LSP) or namespace provider was
/// improperly installed or the provider fails to operate correctly.
///
///
/// -
/// WSAESOCKTNOSUPPORT
/// The specified socket type is not supported in this address family.
///
///
///
///
///
/// The WSASocket function causes a socket descriptor and any related resources to be allocated and associated with a
/// transport-service provider. Most sockets should be created with the WSA_FLAG_OVERLAPPED attribute set in the dwFlags
/// parameter. A socket created with this attribute supports the use of overlapped I/O operations which provide higher performance.
/// By default, a socket created with the WSASocket function will not have this overlapped attribute set. In contrast, the
/// socket function creates a socket that supports overlapped I/O operations as the default behavior.
///
///
/// If the lpProtocolInfo parameter is NULL, Winsock will utilize the first available transport-service provider that
/// supports the requested combination of address family, socket type and protocol specified in the af, type, and protocol parameters.
///
///
/// If the lpProtocolInfo parameter is not NULL, the socket will be bound to the provider associated with the indicated
/// WSAPROTOCOL_INFO structure. In this instance, the application can supply the manifest constant FROM_PROTOCOL_INFO as the
/// value for any of af, type, or protocol parameters. This indicates that the corresponding values from the indicated
/// WSAPROTOCOL_INFO structure ( iAddressFamily, iSocketType, iProtocol) are to be assumed. In any case,
/// the values specified for af, type, and protocol are passed unmodified to the transport-service provider.
///
///
/// When selecting a protocol and its supporting service provider based on af, type, and protocol, this procedure will only choose a
/// base protocol or a protocol chain, not a protocol layer by itself. Unchained protocol layers are not considered to have partial
/// matches on type or af, either. That is, they do not lead to an error code of WSAEAFNOSUPPORT or WSAEPROTONOSUPPORT, if no
/// suitable protocol is found.
///
///
/// Note The manifest constant AF_UNSPEC continues to be defined in the header file but its use is strongly
/// discouraged, as this can cause ambiguity in interpreting the value of the protocol parameter.
///
///
/// Applications are encouraged to use AF_INET6 for the af parameter and create a dual-mode socket that can be used with both
/// IPv4 and IPv6.
///
///
/// If a socket is created using the WSASocket function, then the dwFlags parameter must have the WSA_FLAG_OVERLAPPED
/// attribute set for the SO_RCVTIMEO or SO_SNDTIMEO socket options to function properly. Otherwise the timeout never
/// takes effect on the socket.
///
///
/// Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before
/// any data can be sent or received on them. A connection to a specified socket is established with a connect or WSAConnect
/// function call. Once connected, data can be transferred using send/WSASend and recv/WSARecv calls. When a session has been
/// completed, the closesocket function should be called to release the resources associated with the socket. For
/// connection-oriented sockets, the shutdown function should be called to stop data transfer on the socket before calling the
/// closesocket function.
///
///
/// The communications protocols used to implement a reliable, connection-oriented socket ensure that data is not lost or
/// duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length
/// of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.
///
///
/// Connectionless, message-oriented sockets allow sending and receiving of datagrams to and from arbitrary peers using
/// sendto/WSASendTo and recvfrom/WSARecvFrom. If such a socket is connected to a specific peer, datagrams can be sent to that peer
/// using send/WSASend and can be received from (only) this peer using recv/WSARecv.
///
///
/// Support for sockets with type SOCK_RAW is not required, but service providers are encouraged to support raw sockets
/// whenever possible.
///
///
/// The WSASocket function can be used to create a socket to be used by a service so that if another socket tries to bind to
/// the same port used by the service, and audit record is generared. To enable this option, an application would need to do the following:
///
///
/// -
///
/// Call the AdjustTokenPrivileges function to enable the SE_SECURITY_NAME privilege in the access token for the process.
/// This privilege is required to set the ACCESS_SYSTEM_SECURITY access rights on the security descriptor for an object.
///
///
/// -
///
/// Call the WSASocket function to create a socket with dwFlag with the WSA_FLAG_ACCESS_SYSTEM_SECURITY option set.
/// The WSASocket function will fail if the AdjustTokenPrivileges function is not called first to enable the
/// SE_SECURITY_NAME privilege needed for this operation.
///
///
/// -
///
/// Call the SetSecurityInfo function to set a security descriptor with a System Access Control List (SACL) on the socket. The
/// socket handle returned by the WSASocket function is passed in the handle parameter. If the function succeeds, this will
/// set the the ACCESS_SYSTEM_SECURITY access right on the security descriptor for the socket.
///
///
/// -
///
/// Call the bindfunction to bind the socket to a specific port. If the bind function succeeds, then an audit entry is
/// generated if another socket tries to bind to the same port.
///
///
/// -
///
/// Call the AdjustTokenPrivileges function to remove the SE_SECURITY_NAME privilege in the access token for the process,
/// since this is no longer needed.
///
///
///
///
/// For more information on ACCESS_SYSTEM_SECURITY, see SACL Access Right and Audit Generation in the Authorization documentation.
///
/// Socket Groups
///
/// WinSock 2 introduced the notion of a socket group as a means for an application, or cooperating set of applications, to indicate
/// to an underlying service provider that a particular set of sockets are related and that the group thus formed has certain
/// attributes. Group attributes include relative priorities of the individual sockets within the group and a group quality of
/// service specification.
///
///
/// Applications that need to exchange multimedia streams over the network are an example where being able to establish a specific
/// relationship among a set of sockets could be beneficial. It is up to the transport on how to treat socket groups.
///
///
/// The WSASocket and WSAAccept functions can be used to explicitly create and join a socket group when creating a new
/// socket. The socket group ID for a socket can be retrieved by using the getsockopt function with level parameter set to
/// SOL_SOCKET and the optname parameter set to SO_GROUP_ID. A socket group and its associated socket group ID remain valid
/// until the last socket belonging to this socket group is closed. Socket group IDs are unique across all processes for a given
/// service provider. A socket group of zero indicates that the socket is not member of a socket group.
///
///
/// The relative group priority of a socket group can be accessed by using the getsockopt function with the level parameter set to
/// SOL_SOCKET and the optname parameter set to SO_GROUP_PRIORITY. The relative group priority of a socket group can be set
/// by using setsockopt with the level parameter set to SOL_SOCKET and the optname parameter set to SO_GROUP_PRIORITY.
///
///
/// The Winsock provider included with Windows allows the creation of socket groups and it enforces the SG_CONSTRAINED_GROUP. All
/// sockets in a constrained socket group must be created with the same value for the type and protocol parameters. A constrained
/// socket group may consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the
/// same address on the same host. This is the only restriction applied to a socket group by the Winsock provider included with
/// Windows. The socket group priority is not currently used by the Winsock provider or the TCP/IP stack included with Windows.
///
/// Example Code
/// The following example demonstrates the use of the WSASocket function.
///
/// Windows Phone 8: The WSASocketW function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
///
/// Windows 8.1 and Windows Server 2012 R2: The WSASocketW function is supported for Windows Store apps on
/// Windows 8.1, Windows Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketa SOCKET WSAAPI WSASocketA( int af, int type,
// int protocol, LPWSAPROTOCOL_INFOA lpProtocolInfo, GROUP g, DWORD dwFlags );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "dcf2e543-de54-43d9-9e45-4cb935da3548")]
public static extern SOCKET WSASocket(ADDRESS_FAMILY af, SOCK type, IPPROTO protocol, [Optional] IntPtr lpProtocolInfo, GROUP g, WSA_FLAG dwFlags);
/// The WSAStartup function initiates use of the Winsock DLL by a process.
/// TBD
/// A pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.
///
/// If successful, the WSAStartup function returns zero. Otherwise, it returns one of the error codes listed below.
///
/// The WSAStartup function directly returns the extended error code in the return value for this function. A call to the
/// WSAGetLastError function is not needed and should not be used.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSASYSNOTREADY
/// The underlying network subsystem is not ready for network communication.
///
/// -
/// WSAVERNOTSUPPORTED
/// The version of Windows Sockets support requested is not provided by this particular Windows Sockets implementation.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 operation is in progress.
///
/// -
/// WSAEPROCLIM
/// A limit on the number of tasks supported by the Windows Sockets implementation has been reached.
///
/// -
/// WSAEFAULT
/// The lpWSAData parameter is not a valid pointer.
///
///
///
///
///
/// The WSAStartup function must be the first Windows Sockets function called by an application or DLL. It allows an
/// application or DLL to specify the version of Windows Sockets required and retrieve details of the specific Windows Sockets
/// implementation. The application or DLL can only issue further Windows Sockets functions after successfully calling WSAStartup.
///
///
/// In order to support various Windows Sockets implementations and applications that can have functional differences from the
/// latest version of Windows Sockets specification, a negotiation takes place in WSAStartup. The caller of WSAStartup
/// passes in the wVersionRequested parameter the highest version of the Windows Sockets specification that the application
/// supports. The Winsock DLL indicates the highest version of the Windows Sockets specification that it can support in its
/// response. The Winsock DLL also replies with version of the Windows Sockets specification that it expects the caller to use.
///
///
/// When an application or DLL calls the WSAStartup function, the Winsock DLL examines the version of the Windows Sockets
/// specification requested by the application passed in the wVersionRequested parameter. If the version requested by the
/// application is equal to or higher than the lowest version supported by the Winsock DLL, the call succeeds and the Winsock DLL
/// returns detailed information in the WSADATA structure pointed to by the lpWSAData parameter. The wHighVersion member of
/// the WSADATA structure indicates the highest version of the Windows Sockets specification that the Winsock DLL supports.
/// The wVersion member of the WSADATA structure indicates the version of the Windows Sockets specification that the
/// Winsock DLL expects the caller to use.
///
///
/// If the wVersion member of the WSADATA structure is unacceptable to the caller, the application or DLL should call
/// WSACleanup to release the Winsock DLL resources and fail to initialize the Winsock application. In order to support this
/// application or DLL, it will be necessary to search for an updated version of the Winsock DLL to install on the platform.
///
///
/// The current version of the Windows Sockets specification is version 2.2. The current Winsock DLL, Ws2_32.dll, supports
/// applications that request any of the following versions of Windows Sockets specification:
///
///
/// -
/// 1.0
///
/// -
/// 1.1
///
/// -
/// 2.0
///
/// -
/// 2.1
///
/// -
/// 2.2
///
///
///
/// To get full access to the new syntax of a higher version of the Windows Sockets specification, the application must negotiate
/// for this higher version. In this case, the wVersionRequested parameter should be set to request version 2.2. The application
/// must also fully conform to that higher version of the Windows Socket specification, such as compiling against the appropriate
/// header file, linking with a new library, or other special cases. The Winsock2.h header file for Winsock 2 support is included
/// with the Microsoft Windows Software Development Kit (SDK).
///
///
/// Windows Sockets version 2.2 is supported on Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000,
/// Windows NT 4.0 with Service Pack 4 (SP4) and later, Windows Me, Windows 98, and Windows 95 OSR2. Windows Sockets version 2.2 is
/// also supported on Windows 95 with the Windows Socket 2 Update. Applications on these platforms should normally request Winsock
/// 2.2 by setting the wVersionRequested parameter accordingly.
///
///
/// On Windows 95 and versions of Windows NT 3.51 and earlier, Windows Sockets version 1.1 is the highest version of the Windows
/// Sockets specification supported.
///
///
/// It is legal and possible for an application or DLL written to use a lower version of the Windows Sockets specification that is
/// supported by the Winsock DLL to successfully negotiate this lower version using the WSAStartup function. For example, an
/// application can request version 1.1 in the wVersionRequested parameter passed to the WSAStartup function on a platform
/// with the Winsock 2.2 DLL. In this case, the application should only rely on features that fit within the version requested. New
/// Ioctl codes, new behavior of existing functions, and new functions should not be used. The version negotiation provided by the
/// WSAStartup was primarily used to allow older Winsock 1.1 applications developed for Windows 95 and Windows NT 3.51 and
/// earlier to run with the same behavior on later versions of Windows. The Winsock.h header file for Winsock 1.1 support is
/// included with the Windows SDK.
///
///
/// This negotiation in the WSAStartup function allows both the application or DLL that uses Windows Sockets and the Winsock
/// DLL to support a range of Windows Sockets versions. An application or DLL can use the Winsock DLL if there is any overlap in the
/// version ranges. Detailed information on the Windows Sockets implementation is provided in the WSADATA structure returned by the
/// WSAStartup function.
///
/// The following table shows how WSAStartup works with different applications and Winsock DLL versions.
///
///
/// Caller version support
/// Winsock DLL version support
/// wVersion requested
/// wVersion returned
/// wHighVersion returned
/// End result
///
/// -
/// 1.1
/// 1.1
/// 1.1
/// 1.1
/// 1.1
/// use 1.1
///
/// -
/// 1.0 1.1
/// 1.0
/// 1.1
/// 1.0
/// 1.0
/// use 1.0
///
/// -
/// 1.0
/// 1.0 1.1
/// 1.0
/// 1.0
/// 1.1
/// use 1.0
///
/// -
/// 1.1
/// 1.0 1.1
/// 1.1
/// 1.1
/// 1.1
/// use 1.1
///
/// -
/// 1.1
/// 1.0
/// 1.1
/// 1.0
/// 1.0
/// Application fails
///
/// -
/// 1.0
/// 1.1
/// 1.0
/// —
/// —
/// WSAVERNOTSUPPORTED
///
/// -
/// 1.0 1.1
/// 1.0 1.1
/// 1.1
/// 1.1
/// 1.1
/// use 1.1
///
/// -
/// 1.1 2.0
/// 1.0 1.1
/// 2.0
/// 1.1
/// 1.1
/// use 1.1
///
/// -
/// 2.0
/// 1.0 1.1 2.0
/// 2.0
/// 2.0
/// 2.0
/// use 2.0
///
/// -
/// 2.0 2.2
/// 1.0 1.1 2.0
/// 2.2
/// 2.0
/// 2.0
/// use 2.0
///
/// -
/// 2.2
/// 1.0 1.1 2.0 2.1 2.2
/// 2.2
/// 2.2
/// 2.2
/// use 2.2
///
///
///
/// Once an application or DLL has made a successful WSAStartup call, it can proceed to make other Windows Sockets calls as
/// needed. When it has finished using the services of the Winsock DLL, the application must call WSACleanup to allow the Winsock
/// DLL to free internal Winsock resources used by the application.
///
///
/// An application can call WSAStartup more than once if it needs to obtain the WSADATA structure information more than once.
/// On each such call, the application can specify any version number supported by the Winsock DLL.
///
///
/// The WSAStartup function typically leads to protocol-specific helper DLLs being loaded. As a result, the WSAStartup
/// function should not be called from the DllMain function in a application DLL. This can potentially cause deadlocks. For more
/// information, please see the DLL Main Function.
///
///
/// An application must call the WSACleanup function for every successful time the WSAStartup function is called. This means,
/// for example, that if an application calls WSAStartup three times, it must call WSACleanup three times. The first
/// two calls to WSACleanup do nothing except decrement an internal counter; the final WSACleanup call for the task
/// does all necessary resource deallocation for the task.
///
///
/// Note An application can call the WSAGetLastError function to determine the extended error code for other Windows sockets
/// functions as is normally done in Windows Sockets even if the WSAStartup function fails or the WSAStartup function
/// was not called to properly initialize Windows Sockets before calling a Windows Sockets function. The WSAGetLastError
/// function is one of the only functions in the Winsock 2.2 DLL that can be called in the case of a WSAStartup failure.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
/// Examples
///
/// The following code fragment demonstrates how an application that supports only version 2.2 of Windows Sockets makes a
/// WSAStartup call:
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/winsock/nf-winsock-wsastartup int WSAStartup( WORD wVersionRequired,
// LPWSADATA lpWSAData );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock.h", MSDNShortId = "08299592-867c-491d-9769-d16602133659")]
public static extern Win32Error WSAStartup(ushort wVersionRequired, out WSADATA lpWSAData);
///
/// The WSAStringToAddress function converts a network address in its standard text presentation form into its numeric binary
/// form in a sockaddr structure, suitable for passing to Windows Sockets routines that take such a structure.
///
///
/// A pointer to the zero-terminated string that contains the network address in standard text form to convert.
///
/// The address family of the network address pointed to by the AddressString parameter.
///
/// The WSAPROTOCOL_INFO structure associated with the provider to be used. If this is NULL, the call is routed to the
/// provider of the first protocol supporting the indicated AddressFamily.
///
///
/// A pointer to a buffer that is filled with a sockaddr structure for the address string if the function succeeds.
///
///
/// A pointer to the length, in bytes, of the buffer pointed to by the lpAddress parameter. If the function call is successful, this
/// parameter returns a pointer to the size of the sockaddr structure returned in the lpAddress parameter. If the specified buffer
/// is not large enough, the function fails with a specific error of WSAEFAULT and this parameter is updated with the required size
/// in bytes.
///
///
///
/// The return value for WSAStringToAddress is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is
/// returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEFAULT
/// The buffer pointed to by the lpAddress parameter is too small. Pass in a larger buffer.
///
/// -
/// WSAEINVAL
/// The functions was unable to translate the string into a sockaddr. See the following Remarks section for more information.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Socket functions.
///
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
///
/// The WSAStringToAddress function converts a network address in standard text form into its numeric binary form in a
/// sockaddr structure.
///
///
/// Any missing components of the address will be defaulted to a reasonable value, if possible. For example, a missing port number
/// will default to zero. If the caller wants the translation to be done by a particular provider, it should supply the
/// corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
///
///
/// The WSAStringToAddress function fails (and returns WSAEINVAL) if the sin_family member of the SOCKADDR_IN
/// structure, which is passed in the lpAddress parameter in the form of a sockaddr structure, is not set to AF_INET or AF_INET6.
///
///
/// Support for IPv6 addresses using the WSAStringToAddress function was added on Windows XP with Service Pack 1 (SP1)and
/// later. IPv6 must also be installed on the local computer for the WSAStringToAddress function to support IPv6 addresses.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsastringtoaddressa INT WSAAPI WSAStringToAddressA( LPSTR
// AddressString, INT AddressFamily, LPWSAPROTOCOL_INFOA lpProtocolInfo, LPSOCKADDR lpAddress, LPINT lpAddressLength );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "7b9946c3-c8b3-45ae-9bde-03faaf604bba")]
public static extern WSRESULT WSAStringToAddress([MarshalAs(UnmanagedType.LPTStr)] string AddressString, ADDRESS_FAMILY AddressFamily, in WSAPROTOCOL_INFO lpProtocolInfo, [Out] SOCKADDR lpAddress, ref int lpAddressLength);
///
/// The WSAStringToAddress function converts a network address in its standard text presentation form into its numeric binary
/// form in a sockaddr structure, suitable for passing to Windows Sockets routines that take such a structure.
///
///
/// A pointer to the zero-terminated string that contains the network address in standard text form to convert.
///
/// The address family of the network address pointed to by the AddressString parameter.
///
/// The WSAPROTOCOL_INFO structure associated with the provider to be used. If this is NULL, the call is routed to the
/// provider of the first protocol supporting the indicated AddressFamily.
///
///
/// A pointer to a buffer that is filled with a sockaddr structure for the address string if the function succeeds.
///
///
/// A pointer to the length, in bytes, of the buffer pointed to by the lpAddress parameter. If the function call is successful, this
/// parameter returns a pointer to the size of the sockaddr structure returned in the lpAddress parameter. If the specified buffer
/// is not large enough, the function fails with a specific error of WSAEFAULT and this parameter is updated with the required size
/// in bytes.
///
///
///
/// The return value for WSAStringToAddress is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is
/// returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEFAULT
/// The buffer pointed to by the lpAddress parameter is too small. Pass in a larger buffer.
///
/// -
/// WSAEINVAL
/// The functions was unable to translate the string into a sockaddr. See the following Remarks section for more information.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Socket functions.
///
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
///
/// The WSAStringToAddress function converts a network address in standard text form into its numeric binary form in a
/// sockaddr structure.
///
///
/// Any missing components of the address will be defaulted to a reasonable value, if possible. For example, a missing port number
/// will default to zero. If the caller wants the translation to be done by a particular provider, it should supply the
/// corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
///
///
/// The WSAStringToAddress function fails (and returns WSAEINVAL) if the sin_family member of the SOCKADDR_IN
/// structure, which is passed in the lpAddress parameter in the form of a sockaddr structure, is not set to AF_INET or AF_INET6.
///
///
/// Support for IPv6 addresses using the WSAStringToAddress function was added on Windows XP with Service Pack 1 (SP1)and
/// later. IPv6 must also be installed on the local computer for the WSAStringToAddress function to support IPv6 addresses.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsastringtoaddressa INT WSAAPI WSAStringToAddressA( LPSTR
// AddressString, INT AddressFamily, LPWSAPROTOCOL_INFOA lpProtocolInfo, LPSOCKADDR lpAddress, LPINT lpAddressLength );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "7b9946c3-c8b3-45ae-9bde-03faaf604bba")]
public static extern WSRESULT WSAStringToAddress([MarshalAs(UnmanagedType.LPTStr)] string AddressString, ADDRESS_FAMILY AddressFamily, [In, Optional] IntPtr lpProtocolInfo, [Out] SOCKADDR lpAddress, ref int lpAddressLength);
///
/// The WSAStringToAddress function converts a network address in its standard text presentation form into its numeric binary
/// form in a sockaddr structure, suitable for passing to Windows Sockets routines that take such a structure.
///
///
/// A pointer to the zero-terminated string that contains the network address in standard text form to convert.
///
/// The address family of the network address pointed to by the AddressString parameter.
///
/// The WSAPROTOCOL_INFO structure associated with the provider to be used. If this is NULL, the call is routed to the
/// provider of the first protocol supporting the indicated AddressFamily.
///
///
/// A pointer to a buffer that is filled with a sockaddr structure for the address string if the function succeeds.
///
///
/// A pointer to the length, in bytes, of the buffer pointed to by the lpAddress parameter. If the function call is successful, this
/// parameter returns a pointer to the size of the sockaddr structure returned in the lpAddress parameter. If the specified buffer
/// is not large enough, the function fails with a specific error of WSAEFAULT and this parameter is updated with the required size
/// in bytes.
///
///
///
/// The return value for WSAStringToAddress is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is
/// returned, and a specific error number can be retrieved by calling WSAGetLastError.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSAEFAULT
/// The buffer pointed to by the lpAddress parameter is too small. Pass in a larger buffer.
///
/// -
/// WSAEINVAL
/// The functions was unable to translate the string into a sockaddr. See the following Remarks section for more information.
///
/// -
/// WSANOTINITIALISED
///
/// The WS2_32.DLL has not been initialized. The application must first call WSAStartup before calling any Windows Socket functions.
///
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// There was insufficient memory to perform the operation.
///
///
///
///
///
/// The WSAStringToAddress function converts a network address in standard text form into its numeric binary form in a
/// sockaddr structure.
///
///
/// Any missing components of the address will be defaulted to a reasonable value, if possible. For example, a missing port number
/// will default to zero. If the caller wants the translation to be done by a particular provider, it should supply the
/// corresponding WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
///
///
/// The WSAStringToAddress function fails (and returns WSAEINVAL) if the sin_family member of the SOCKADDR_IN
/// structure, which is passed in the lpAddress parameter in the form of a sockaddr structure, is not set to AF_INET or AF_INET6.
///
///
/// Support for IPv6 addresses using the WSAStringToAddress function was added on Windows XP with Service Pack 1 (SP1)and
/// later. IPv6 must also be installed on the local computer for the WSAStringToAddress function to support IPv6 addresses.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsastringtoaddressa INT WSAAPI WSAStringToAddressA( LPSTR
// AddressString, INT AddressFamily, LPWSAPROTOCOL_INFOA lpProtocolInfo, LPSOCKADDR lpAddress, LPINT lpAddressLength );
[DllImport(Lib.Ws2_32, SetLastError = false, CharSet = CharSet.Auto)]
[PInvokeData("winsock2.h", MSDNShortId = "7b9946c3-c8b3-45ae-9bde-03faaf604bba")]
public static extern WSRESULT WSAStringToAddress([MarshalAs(UnmanagedType.LPTStr)] string AddressString, ADDRESS_FAMILY AddressFamily, [In, Optional] IntPtr lpProtocolInfo, [Out] IntPtr lpAddress, ref int lpAddressLength);
///
/// The WSAStringToAddress function converts a network address in its standard text presentation form into its numeric binary
/// form in a sockaddr structure, suitable for passing to Windows Sockets routines that take such a structure.
///
///
/// A pointer to the zero-terminated string that contains the network address in standard text form to convert.
///
/// The address family of the network address pointed to by the AddressString parameter.
///
/// The WSAPROTOCOL_INFO structure associated with the provider to be used. If this is NULL, the call is routed to the
/// provider of the first protocol supporting the indicated AddressFamily.
///
/// A sockaddr structure for the address string if the function succeeds.
///
///
/// The WSAStringToAddress function converts a network address in standard text form into its numeric binary form in a
/// sockaddr structure.
///
///
/// Any missing components of the address will be defaulted to a reasonable value, if possible. For example, a missing port number
/// will default to zero. If the caller wants the translation to be done by a particular provider, it should supply the corresponding
/// WSAPROTOCOL_INFO structure in the lpProtocolInfo parameter.
///
///
/// The WSAStringToAddress function fails (and returns WSAEINVAL) if the sin_family member of the SOCKADDR_IN
/// structure, which is passed in the lpAddress parameter in the form of a sockaddr structure, is not set to AF_INET or AF_INET6.
///
///
/// Support for IPv6 addresses using the WSAStringToAddress function was added on Windows XP with Service Pack 1 (SP1)and
/// later. IPv6 must also be installed on the local computer for the WSAStringToAddress function to support IPv6 addresses.
///
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsastringtoaddressa INT WSAAPI WSAStringToAddressA( LPSTR
// AddressString, INT AddressFamily, LPWSAPROTOCOL_INFOA lpProtocolInfo, LPSOCKADDR lpAddress, LPINT lpAddressLength );
[PInvokeData("winsock2.h", MSDNShortId = "7b9946c3-c8b3-45ae-9bde-03faaf604bba")]
public static SOCKADDR_INET WSAStringToAddress(string AddressString, ADDRESS_FAMILY AddressFamily, [In, Optional] WSAPROTOCOL_INFO? lpProtocolInfo)
{
using var pc = lpProtocolInfo.HasValue ? new SafeCoTaskMemStruct(lpProtocolInfo.Value) : SafeCoTaskMemStruct.Null;
using var addr = new SafeCoTaskMemStruct();
int sz = addr.Size;
WSAStringToAddress(AddressString, AddressFamily, pc, addr, ref sz).ThrowIfFailed();
return addr.Value;
}
///
/// The WSAWaitForMultipleEvents function returns when one or all of the specified event objects are in the signaled state,
/// when the time-out interval expires, or when an I/O completion routine has executed.
///
///
/// The number of event object handles in the array pointed to by lphEvents. The maximum number of event object handles is
/// WSA_MAXIMUM_WAIT_EVENTS. One or more events must be specified.
///
///
///
/// A pointer to an array of event object handles. The array can contain handles of objects of different types. It may not contain
/// multiple copies of the same handle if the fWaitAll parameter is set to TRUE. If one of these handles is closed while the
/// wait is still pending, the behavior of WSAWaitForMultipleEvents is undefined.
///
/// The handles must have the SYNCHRONIZE access right. For more information, see Standard Access Rights.
///
///
/// A value that specifies the wait type. If TRUE, the function returns when the state of all objects in the lphEvents array
/// is signaled. If FALSE, the function returns when any of the event objects is signaled. In the latter case, the return
/// value minus WSA_WAIT_EVENT_0 indicates the index of the event object whose state caused the function to return. If more
/// than one event object became signaled during the call, this is the array index to the signaled event object with the smallest
/// index value of all the signaled event objects.
///
///
/// The time-out interval, in milliseconds. WSAWaitForMultipleEvents returns if the time-out interval expires, even if
/// conditions specified by the fWaitAll parameter are not satisfied. If the dwTimeout parameter is zero,
/// WSAWaitForMultipleEvents tests the state of the specified event objects and returns immediately. If dwTimeout is
/// WSA_INFINITE, WSAWaitForMultipleEvents waits forever; that is, the time-out interval never expires.
///
///
/// A value that specifies whether the thread is placed in an alertable wait state so the system can execute I/O completion
/// routines. If TRUE, the thread is placed in an alertable wait state and WSAWaitForMultipleEvents can return when
/// the system executes an I/O completion routine. In this case, WSA_WAIT_IO_COMPLETION is returned and the event that was
/// being waited on is not signaled yet. The application must call the WSAWaitForMultipleEvents function again. If
/// FALSE, the thread is not placed in an alertable wait state and I/O completion routines are not executed.
///
///
/// If the WSAWaitForMultipleEvents function succeeds, the return value upon success is one of the following values.
///
///
/// Return Value
/// Meaning
///
/// -
/// WSA_WAIT_EVENT_0 to (WSA_WAIT_EVENT_0 + cEvents - 1)
///
/// If the fWaitAll parameter is TRUE, the return value indicates that all specified event objects is signaled. If the fWaitAll
/// parameter is FALSE, the return value minus WSA_WAIT_EVENT_0 indicates the lphEvents array index of the signaled event object
/// that satisfied the wait. If more than one event object became signaled during the call, the return value indicates the lphEvents
/// array index of the signaled event object with the smallest index value of all the signaled event objects.
///
///
/// -
/// WSA_WAIT_IO_COMPLETION
///
/// The wait was ended by one or more I/O completion routines that were executed. The event that was being waited on is not signaled
/// yet. The application must call the WSAWaitForMultipleEvents function again. This return value can only be returned if the
/// fAlertable parameter is TRUE.
///
///
/// -
/// WSA_WAIT_TIMEOUT
///
/// The time-out interval elapsed and the conditions specified by the fWaitAll parameter were not satisfied. No I/O completion
/// routines were executed.
///
///
///
///
/// If the WSAWaitForMultipleEvents function fails, the return value is WSA_WAIT_FAILED. The following table lists
/// values that can be used with WSAGetLastError to get extended error information.
///
///
///
/// Error code
/// Meaning
///
/// -
/// WSANOTINITIALISED
/// A successful WSAStartup call must occur before using this function.
///
/// -
/// WSAENETDOWN
/// The network subsystem has failed.
///
/// -
/// WSAEINPROGRESS
/// A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
///
/// -
/// WSA_NOT_ENOUGH_MEMORY
/// Not enough free memory was available to complete the operation.
///
/// -
/// WSA_INVALID_HANDLE
/// One or more of the values in the lphEvents array is not a valid event object handle.
///
/// -
/// WSA_INVALID_PARAMETER
/// The cEvents parameter does not contain a valid handle count.
///
///
///
///
///
/// The WSAWaitForMultipleEvents function determines whether the wait criteria have been met. If the criteria have not been
/// met, the calling thread enters the wait state. It uses no processor time while waiting for the criteria to be met.
///
///
/// The WSAWaitForMultipleEvents function returns when any one or all of the specified objects are in the signaled state, or
/// when the time-out interval elapses.
///
///
/// When the bWaitAll parameter is TRUE, the wait operation is completed only when the states of all objects have been set to
/// signaled. The function does not modify the states of the specified objects until the states of all objects have been set to signaled.
///
///
/// When bWaitAll parameter is FALSE, WSAWaitForMultipleEvents checks the handles in the lphEvents array in order
/// starting with index 0, until one of the objects is signaled. If multiple objects become signaled, the function returns the index
/// of the first handle in the lphEvents array whose object was signaled.
///
///
/// This function is also used to perform an alertable wait by setting the fAlertable parameter to TRUE. This enables the
/// function to return when the system executes an I/O completion routine by the calling thread.
///
///
/// A thread must be in an alertable wait state in order for the system to execute I/O completion routines (asynchronous procedure
/// calls or APCs). So if an application calls WSAWaitForMultipleEvents when there are pending asynchronous operations that
/// have I/O completion routines and the fAlertable parameter is FALSE, then those I/O completion routines will not be
/// executed even if those I/O operations are completed.
///
///
/// If the fAlertable parameter is TRUE and one of the pending operations completes, the APC is executed and
/// WSAWaitForMultipleEvents will return WSA_IO_COMPLETION. The pending event is not signaled yet. The application
/// must call the WSAWaitForMultipleEvents function again.
///
///
/// Applications that require an alertable wait state without waiting for any event objects to be signaled should use the Windows
/// SleepEx function.
///
/// The current implementation of WSAWaitForMultipleEvents calls the WaitForMultipleObjectsEx function.
///
/// Note Use caution when calling the WSAWaitForMultipleEvents with code that directly or indirectly creates windows.
/// If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread
/// that uses WSAWaitForMultipleEvents with no time-out limit (the dwTimeout parameter set to WSA_INFINITE) may cause
/// the system to become deadlocked.
///
/// Example Code
/// The following code example shows how to use the WSAWaitForMultipleEvents function.
/// Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
///
/// Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows
/// Server 2012 R2, and later.
///
///
// https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsawaitformultipleevents DWORD WSAAPI
// WSAWaitForMultipleEvents( DWORD cEvents, const WSAEVENT *lphEvents, BOOL fWaitAll, DWORD dwTimeout, BOOL fAlertable );
[DllImport(Lib.Ws2_32, SetLastError = false, ExactSpelling = true)]
[PInvokeData("winsock2.h", MSDNShortId = "7a978ade-6323-455b-b655-f372f4bcadc8")]
public static extern Kernel32.WAIT_STATUS WSAWaitForMultipleEvents(uint cEvents, [In, MarshalAs(UnmanagedType.LPArray)] WSAEVENT[] lphEvents, [MarshalAs(UnmanagedType.Bool)] bool fWaitAll, uint dwTimeout, [MarshalAs(UnmanagedType.Bool)] bool fAlertable);
}
}