Compartilhar via


Função EnumProtocolsA (nspapi.h)

A função EnumProtocols recupera informações sobre um conjunto especificado de protocolos de rede que estão ativos em um host local.

Nota A função EnumProtocols é uma extensão específica da Microsoft para a especificação do Windows Sockets 1.1. Essa função está obsoleta. Para a conveniência dos desenvolvedores do Windows Sockets 1.1, o material de referência está incluído. A função WSAEnumProtocols fornece funcionalidade equivalente no Windows Sockets 2.
 

Sintaxe

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

Parâmetros

[in, optional] lpiProtocols

Um ponteiro para uma matriz terminada em nulo de identificadores de protocolo. A função EnumProtocols recupera informações sobre os protocolos especificados por essa matriz.

Se lpiProtocols for NULL, a função recuperará informações sobre todos os protocolos disponíveis.

Os valores de identificador de protocolo a seguir são definidos.

Valor Significado
IPPROTO_TCP
O protocolo TCP, um protocolo de fluxo orientado à conexão.
IPPROTO_UDP
O UDP (User Datagram Protocol), um protocolo de datagrama sem conexão.
ISOPROTO_TP4
O protocolo de transporte orientado à conexão ISO.
NSPROTO_IPX
O protocolo IPX (Internet Packet Exchange), um protocolo de datagrama sem conexão.
NSPROTO_SPX
O protocolo SPX (Sequenced Packet Exchange), um protocolo de fluxo orientado a conexão.
NSPROTO_SPXII
O protocolo SPX (Sequenced Packet Exchange) versão 2, um protocolo de fluxo orientado para conexão.

[out] lpProtocolBuffer

Um ponteiro para um buffer que a função preenche com uma matriz de estruturas de dados PROTOCOL_INFO.

[in, out] lpdwBufferLength

Um ponteiro para uma variável que, na entrada, especifica o tamanho, em bytes, do buffer apontado por lpProtocolBuffer.

Na saída, a função define essa variável como o tamanho mínimo do buffer necessário para recuperar todas as informações solicitadas. Para que a função tenha êxito, o buffer deve ter pelo menos esse tamanho.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o número de PROTOCOL_INFO estruturas de dados gravadas no buffer apontado por lpProtocolBuffer.

Se a função falhar, o valor retornado será SOCKET_ERROR(–1). Para obter informações de erro estendidas, chame GetLastError, que retorna o código de erro estendido a seguir.

Código do erro Significado
ERROR_INSUFFICIENT_BUFFER
O buffer apontado por lpProtocolBuffer era muito pequeno para receber todas as estruturas de PROTOCOL_INFO relevantes. Chame a função com um buffer pelo menos tão grande quanto o valor retornado em *lpdwBufferLength.

Comentários

No código de exemplo a seguir, a função EnumProtocols recupera informações sobre todos os protocolos disponíveis em um sistema. Em seguida, o código examina cada um dos protocolos com mais detalhes.

#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;
}

Observação

O cabeçalho nspapi.h define EnumProtocols como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho nspapi.h
Biblioteca Mswsock.lib
DLL Mswsock.dll

Confira também

GetAddressByName

PROTOCOL_INFO

Funções Winsock

Referência de Winsock