EnumProtocolsA-Funktion (nspapi.h)

Artikel
08/25/2023

Die EnumProtocols-Funktion ruft Informationen zu einem angegebenen Satz von Netzwerkprotokollen ab, die auf einem lokalen Host aktiv sind.

Hinweis Die EnumProtocols-Funktion ist eine Microsoft-spezifische Erweiterung der Windows Sockets 1.1-Spezifikation. Diese Funktion ist veraltet. Zur Vereinfachung von Windows Sockets 1.1-Entwicklern ist das Referenzmaterial enthalten. Die WSAEnumProtocols-Funktion bietet entsprechende Funktionen in Windows Sockets 2.

Syntax

INT EnumProtocolsA(
  [in, optional] LPINT   lpiProtocols,
  [out]          LPVOID  lpProtocolBuffer,
  [in, out]      LPDWORD lpdwBufferLength
);

Parameter

[in, optional] lpiProtocols

Ein Zeiger auf ein Array mit NULL-Endung von Protokollbezeichnern. Die EnumProtocols-Funktion ruft Informationen zu den Protokollen ab, die von diesem Array angegeben werden.

Wenn lpiProtocolsNULL ist, ruft die Funktion Informationen zu allen verfügbaren Protokollen ab.

Die folgenden Protokollbezeichnerwerte werden definiert.

Wert	Bedeutung
IPPROTO_TCP	Das Transmission Control Protocol (TCP), ein verbindungsorientiertes Streamprotokoll.
IPPROTO_UDP	Das User Datagram Protocol (UDP), ein verbindungsloses Datagrammprotokoll.
ISOPROTO_TP4	Das verbindungsorientierte ISO-Transportprotokoll.
NSPROTO_IPX	Das IPX-Protokoll (Internet Packet Exchange), ein verbindungsloses Datagrammprotokoll.
NSPROTO_SPX	Das SPX-Protokoll (Sequenced Packet Exchange), ein verbindungsorientiertes Streamprotokoll.
NSPROTO_SPXII	Das SPX-Protokoll (Sequenced Packet Exchange, Version 2), ein verbindungsorientiertes Streamprotokoll.

[out] lpProtocolBuffer

Ein Zeiger auf einen Puffer, den die Funktion mit einem Array von PROTOCOL_INFO Datenstrukturen auffüllt.

[in, out] lpdwBufferLength

Ein Zeiger auf eine Variable, die bei der Eingabe die Größe des Puffers in Bytes angibt, auf den lpProtocolBuffer verweist.

Bei der Ausgabe legt die Funktion diese Variable auf die minimale Puffergröße fest, die zum Abrufen aller angeforderten Informationen erforderlich ist. Damit die Funktion erfolgreich ist, muss der Puffer mindestens diese Größe aufweisen.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der PROTOCOL_INFO Datenstrukturen, die in den Puffer geschrieben werden, auf den lpProtocolBuffer verweist.

Wenn die Funktion fehlschlägt, lautet der Rückgabewert SOCKET_ERROR(–1). Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Dadurch wird der folgende erweiterte Fehlercode zurückgegeben.

Fehlercode	Bedeutung
ERROR_INSUFFICIENT_BUFFER	Der Puffer, auf den lpProtocolBuffer verweist, war zu klein, um alle relevanten PROTOCOL_INFO Strukturen zu empfangen. Rufen Sie die Funktion mit einem Puffer auf, der mindestens so groß ist wie der in *lpdwBufferLength zurückgegebene Wert.

Hinweise

Im folgenden Beispielcode ruft die EnumProtocols-Funktion Informationen zu allen Protokollen ab, die auf einem System verfügbar sind. Der Code untersucht dann die einzelnen Protokolle ausführlicher.

#define WIN32_LEAN_AND_MEAN

#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <Nspapi.h>
#include <stdlib.h>
#include <stdio.h>


// Need to link with Ws2_32.lib and Mswsock.lib
#pragma comment (lib, "Ws2_32.lib")
#pragma comment (lib, "Mswsock.lib")

int FindProtocol(BOOL Reliable, 
    BOOL MessageOriented, BOOL StreamOriented, 
    BOOL Connectionless, DWORD *ProtocolUsed); 

int __cdecl main(int argc, char **argv)
{
    WSADATA wsaData;

    int ProtocolError = SOCKET_ERROR;
    int iResult;
    
    BOOLEAN bReliable = FALSE;
    BOOLEAN bMessageOriented = FALSE;
    BOOLEAN bStreamOriented = TRUE;
    BOOLEAN bConnectionless = FALSE;
    DWORD *pProtocols = NULL;
    
    // Validate the parameters
    if (argc != 2) {
        printf("usage: %s servicename\n", argv[0]);
        return 1;
    }

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2,2), &wsaData);
    if (iResult != 0) {
        printf("WSAStartup failed with error: %d\n", iResult);
        return 1;
    }
    
    ProtocolError = FindProtocol( bReliable, bMessageOriented,
        bStreamOriented, bConnectionless, pProtocols);
    if (ProtocolError == SOCKET_ERROR) {
        printf("Unable to find a protocol to support the parameters requested\n");
        return 1;
    }
    
    // Connect to the servicename ...    
    
    return 0;

}

#define MAX_PROTOCOLS 1024

int FindProtocol ( 
    BOOL Reliable, 
    BOOL MessageOriented, 
    BOOL StreamOriented, 
    BOOL Connectionless, 
    DWORD *ProtocolUsed 
    ) 
{ 
    // local variables 
    INT protocols[MAX_PROTOCOLS+1]; 
    BYTE buffer[2048]; 
    DWORD bytesRequired; 
    INT err; 
    PPROTOCOL_INFO protocolInfo; 
    INT protocolCount; 
    INT i; 
    DWORD protocolIndex; 
//    PCSADDR_INFO csaddrInfo; 
//    INT addressCount; 
//    SOCKET s; 
 
    // First look up the protocols installed on this computer. 
    // 
    bytesRequired = sizeof(buffer); 
    err = EnumProtocols( NULL, buffer, &bytesRequired ); 
    if ( err <= 0 ) 
        return SOCKET_ERROR; 
 
    // Walk through the available protocols and pick out the ones which 
    // support the desired characteristics. 
    // 
    protocolCount = err; 
    protocolInfo = (PPROTOCOL_INFO)buffer; 
 
    for ( i = 0, protocolIndex = 0; 
        i < protocolCount && protocolIndex < MAX_PROTOCOLS; 
        i++, protocolInfo++ ) { 
 
        // If connection-oriented support is requested, then check if 
        // supported by this protocol.  We assume here that connection- 
        // oriented support implies fully reliable service. 
        // 
 
        if ( Reliable ) { 
            // Check to see if the protocol is reliable.  It must 
            // guarantee both delivery of all data and the order in 
            // which the data arrives. 
            // 
            if ( (protocolInfo->dwServiceFlags & 
                    XP_GUARANTEED_DELIVERY) == 0 
                || 
                    (protocolInfo->dwServiceFlags & 
                    XP_GUARANTEED_ORDER) == 0 ) { 
 
                continue; 
            } 
 
            // Check to see that the protocol matches the stream/message 
            // characteristics requested. 
            // 
            if ( StreamOriented && 
                (protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED) 
                    != 0 && 
                (protocolInfo->dwServiceFlags & XP_PSEUDO_STREAM) 
                     == 0 ) { 
                continue; 
            } 
 
            if ( MessageOriented && 
                    (protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED) 
                              == 0 ) { 
                continue; 
            } 
 
        } 
        else if ( Connectionless ) { 
            // Make sure that this is a connectionless protocol. 
            // 
            if ( (protocolInfo->dwServiceFlags & XP_CONNECTIONLESS) 
                     != 0 ) 
                continue; 
        } 
 
        // This protocol fits all the criteria.  Add it to the list of 
        // protocols in which we're interested. 
        // 
        protocols[protocolIndex++] = protocolInfo->iProtocol; 
     }

     *ProtocolUsed = (INT) protocolIndex;
     return 0;
}

Hinweis

Der nspapi.h-Header definiert EnumProtocols als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	nspapi.h
Bibliothek	Mswsock.lib
DLL	Mswsock.dll

Weitere Informationen