Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function retrieves information about available transport protocols.

Syntax 

int WSAEnumProtocols(
  LPINT 
lpiProtocols,
  LPWSAPROTOCOL_INFO 
lpProtocolBuffer,
  ILPDWORD 
lpdwBufferLength
);

Parameters

lpiProtocols

[in] Null-terminated array of iProtocolvalues. This parameter is optional; if lpiProtocolsis 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_INFOstructures.

lpdwBufferLength

[in, out] On input, the count of bytes in the lpProtocolBufferbuffer passed to this function. On output, the minimum buffer size that can be passed to this function 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 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 machine is typically small.

Return Value

If no error occurs, this function returns the number of protocols to be reported. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling the WSAGetLastErrorfunction. The following table shows a list of possible error codes.

Error code Description

WSANOTINITIALISED

A successful WSAStartupcall must occur before using this function.

WSAENETDOWN

The network subsystem has failed.

WSAEINPROGRESS

A blocking Winsock call is in progress.

WSAEINVAL

One of the specified parameters was invalid.

WSAENOBUFS

The buffer length was too small to receive all the relevant WSAPROTOCOL_INFOstructures 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 lpdwBufferLengtharguments are not a valid part of the user address space.

Remarks

This function is used to discover information about the collection of transport protocols and provider chains installed on the local machine. Because layered protocols are only usable by applications when installed in provider chains, information on layered protocols is not included in lpProtocolBuffer. The lpiProtocolsparameter can be used as a filter to constrain the amount of information provided. Often, lpiProtocolswill be supplied as a NULL pointer that will cause the function to return information on all available transport protocols and provider chains.

A WSAPROTOCOL_INFOstructure is provided in the buffer pointed to by lpProtocolBufferfor each requested protocol. If the supplied buffer is not large enough (as indicated by the input value of lpdwBufferLength), the value pointed to by lpdwBufferLengthwill be updated to indicate the required buffer size. The application should then obtain a large enough buffer and call this WSAEnumProtocolsagain.

The order in which the WSAPROTOCOL_INFOstructures appear in the buffer coincides with the order in which the protocol entries were registered by the service provider using ws2.dll or with any subsequent reordering that occurred through the Windows Sockets utility or DLL supplied for establishing default TCP/IP providers.

Requirements

Header winsock2.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also