EnumProtocolsW 函式 (nspapi.h)

發行項
03/05/2024

EnumProtocols 函式會擷取本機主機上作用中之指定網路協定集的相關信息。

注意EnumProtocols 函式是 Windows Sockets 1.1 規格的 Microsoft 特定延伸模組。此函式已過時。為了方便 Windows Sockets 1.1 開發人員使用，包含參考數據。 WSAEnumProtocols 函式在 Windows Sockets 2 中提供對等的功能。

語法

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

參數

[in, optional] lpiProtocols

通訊協議標識碼 之 Null 終止數位的指標。 EnumProtocols 函式會擷取此陣列所指定的通訊協定相關信息。

如果 lpiProtocols 為 NULL，函式會擷取所有可用通訊協議的相關信息。

定義下列通訊協議標識碼值。

值	意義
IPPROTO_TCP	傳輸控制通訊協定 (TCP) ，這是連線導向數據流通訊協定。
IPPROTO_UDP	用戶數據報通訊協定 (UDP) ，這是無連線的數據報通訊協定。
ISOPROTO_TP4	ISO 連線導向傳輸通訊協定。
NSPROTO_IPX	因特網封包交換 (IPX) 通訊協定，這是無連線的數據報通訊協定。
NSPROTO_SPX	循序封包交換 (SPX) 通訊協定，這是聯機導向數據流通訊協定。
NSPROTO_SPXII	循序封包交換 (SPX) 通訊協定第 2 版，這是連線導向數據流通訊協定。

[out] lpProtocolBuffer

函式填滿 PROTOCOL_INFO數據結構數位之緩衝區的指標。

[in, out] lpdwBufferLength

在輸入時，變數的指標會指定 lpProtocolBuffer 所指向之緩衝區的大小，以位元組為單位。

在輸出時，函式會將此變數設定為擷取所有要求資訊所需的最小緩衝區大小。若要讓函式成功，緩衝區必須至少是這個大小。

傳回值

如果函式成功，傳回值就是寫入 lpProtocolBuffer 所指向之緩衝區的PROTOCOL_INFO數據結構數目。

如果函式失敗，傳回值會SOCKET_ERROR (–1) 。若要取得擴充錯誤資訊，請呼叫 GetLastError，這會傳回下列擴充錯誤碼。

錯誤碼	意義
ERROR_INSUFFICIENT_BUFFER	lpProtocolBuffer 所指向的緩衝區太小，無法接收所有相關PROTOCOL_INFO結構。使用緩衝區至少與 *lpdwBufferLength 中所傳回的值一樣大來呼叫函式。

備註

在下列範例程式代碼中， EnumProtocols 函 式會擷取系統上所有可用通訊協議的相關信息。然後，程式代碼會更詳細地檢查每個通訊協定。

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

注意

nspapi.h 標頭會將 EnumProtocols 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	nspapi.h
程式庫	Mswsock.lib
Dll	Mswsock.dll

另請參閱

EnumProtocolsW 函式 (nspapi.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

意見反應

其他資源