WSCEnumProtocols

The WSCEnumProtocols function retrieves information about available transport protocols.

int WSCEnumProtocols (
  LPINT                  lpiProtocols,                     
  LPWSAPROTOCOL_INFOW    lpProtocolBuffer,   
  LPDWORD                lpdwBufferLength,               
  LPINT                  lpErrno                           
);

Parameters

lpiProtocols

[in] Null-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

[out] Buffer that is filled with WSAPROTOCOL_INFOW structures.

lpdwBufferLength

[in/out] On input, the count of bytes in the lpProtocolBuffer buffer passed to WSCEnumProtocols. On output, the minimum buffer size that can be passed to WSCEnumProtocols to retrieve all the requested information.

lpErrno

[out] Pointer to the error code.

Return Values

If no error occurs, WSCEnumProtocols returns the number of protocols to be reported on. Otherwise, a value of SOCKET_ERROR is returned and a specific error code is available in lpErrno.

Remarks

This function is used to discover information about the collection of transport protocols installed on the local machine. This function differs from its API counterpart (WSAEnumProtocols) in that WSAPROTOCOL_INFOW structures for all installed protocols, including layered protocols, can be obtained. (WSAEnumProtocols only returns information on base protocols and protocol chains.) The lpiProtocols parameter can be used as a filter to constrain the amount of information provided. Typically, a NULL pointer is supplied so the function will return information on all available transport protocols.

A WSAPROTOCOL_INFOW structure is provided in the buffer pointed to by lpProtocolBuffer for each requested protocol. If the supplied 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 Windows Sockets SPI client should then obtain a large enough buffer and call this function again. The WSCEnumProtocols function cannot enumerate over multiple calls; the passed-in buffer must be large enough to hold all expected entries in order for the function to succeed. This reduces the complexity of the function and should not pose a problem because the number of protocols loaded on a machine is typically small.

The order in which the WSAPROTOCOL_INFOW structures appear in the buffer coincides with the order in which the protocol entries were registered by the service provider with the Ws2_32.dll, or with any subsequent reordering that may have occurred through the Windows Sockets applet supplied for establishing default transport providers.

Error Codes

Requirements

  Version: Requires Windows Sockets 2.0.
  Header: Declared in Ws2spi.h.
  Library: Use Ws2_32.lib.