WSAEnumProtocolsW

The WSAEnumProtocols function retrieves information about available transport protocols.

Syntax

int WSAEnumProtocolsW(
         LPINT lpiProtocols,
         LPWSAPROTOCOL_INFOW lpProtocolBuffer,
         LPDWORD lpdwBufferLength
)  

Parameters

lpiProtocols
Type: LPINT 

[in, optional] 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.

lpProtocolBuffer
Type: LPWSAPROTOCOL_INFOW 

[out, optional] A pointer to a buffer that is filled with WSAPROTOCOL_INFO structures.

lpdwBufferLength
Type: LPDWORD 

[in, out] 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.

Return value

Type: int 

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.

Return codes

Remarks

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: This API is supported.

Requirements

Header: Declared in winsock2.h.

Library: Use ws2_32.lib.