WSAEnumProtocols
The Windows
Sockets WSAEnumProtocols function retrieves information about available
transport protocols.
int WSAEnumProtocols (
|
LPINT lpiProtocols, |
|
|
LPWSAPROTOCOL_INFO lpProtocolBuffer, |
|
|
ILPDWORD lpdwBufferLength |
|
|
); |
|
Parameters
lpiProtocols
[in] A
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] A
buffer which is filled with WSAPROTOCOL_INFO structures. See below for a
detailed description of the contents of the WSAPROTOCOL_INFO structure.
lpdwBufferLength
[in/out] On
input, the count 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 machine is typically small.
Remarks
This function
is used to discover information about the collection of transport protocols and
protocol chains installed on the local machine. Since layered protocols are
only usable by applications when installed in protocol chains, information on
layered protocols is not included in lpProtocolBuffer. The lpiProtocols
parameter can be used as a filter to constrain the amount of information
provided. Normally it will be supplied as a NULL pointer which will cause the
routine to return information on all available transport protocols and protocol
chains.
A WSAPROTOCOL_INFO 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 application should then obtain a large
enough buffer and call this function 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
with the Windows Sockets DLL, or with any subsequent re-ordering that may have
occurred through the Windows Sockets applet supplied for establishing default
TCP/IP providers.
Return Values
If no error
occurs, WSAEnumProtocols returns the number of protocols to be reported
on. Otherwise, a value of SOCKET_ERROR is returned and a specific error code
may be retrieved by calling WSAGetLastError.
Error Codes
|
WSANOTINITIALISED |
A successful
WSAStartup 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. |