ホーム › Networking.WinSock › EnumProtocolsA

EnumProtocolsA

関数

システムが提供するプロトコル情報を列挙する。

DLLMSWSOCK.dll文字セットANSI (-A)呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// MSWSOCK.dll  (ANSI / -A)
#include <windows.h>

INT EnumProtocolsA(
    INT* lpiProtocols,   // optional
    void* lpProtocolBuffer,
    DWORD* lpdwBufferLength
);

パラメーター

名前

型

方向

説明

lpiProtocols

INT*

inoptional

プロトコル識別子の null 終端配列へのポインター。 EnumProtocols 関数は、この配列で指定されたプロトコルに関する情報を取得します。

lpiProtocols が NULL の場合、関数は利用可能なすべてのプロトコルに関する情報を取得します。

以下のプロトコル識別子の値が定義されています。

値	意味
IPPROTO_TCP	Transmission Control Protocol (TCP)。コネクション指向のストリームプロトコルです。
IPPROTO_UDP	User Datagram Protocol (UDP)。コネクションレスのデータグラムプロトコルです。
ISOPROTO_TP4	ISO のコネクション指向トランスポートプロトコルです。
NSPROTO_IPX	Internet Packet Exchange (IPX) プロトコル。コネクションレスのデータグラムプロトコルです。
NSPROTO_SPX	Sequenced Packet Exchange (SPX) プロトコル。コネクション指向のストリームプロトコルです。
NSPROTO_SPXII	Sequenced Packet Exchange (SPX) プロトコルバージョン 2。コネクション指向のストリームプロトコルです。

lpProtocolBuffer

void*

out

関数が PROTOCOL_INFO データ構造体の配列で埋めるバッファーへのポインター。

lpdwBufferLength

DWORD*

inout

入力時に、lpProtocolBuffer が指すバッファーのサイズ(バイト単位)を指定する変数へのポインター。

出力時に、関数はこの変数に、要求されたすべての情報を取得するために必要な最小バッファーサイズを設定します。関数が成功するには、バッファーが少なくともこのサイズである必要があります。

戻り値の型: INT

公式ドキュメント

EnumProtocols 関数は、ローカルホスト上でアクティブな、指定された一連のネットワークプロトコルに関する情報を取得します。(ANSI)

戻り値

関数が成功した場合、戻り値は lpProtocolBuffer が指すバッファーに書き込まれた PROTOCOL_INFO データ構造体の数です。

関数が失敗した場合、戻り値は SOCKET_ERROR(-1)です。拡張エラー情報を取得するには GetLastError を呼び出します。これは以下の拡張エラーコードを返します。

エラーコード	意味
ERROR_INSUFFICIENT_BUFFER	lpProtocolBuffer が指すバッファーが小さすぎて、関連するすべての PROTOCOL_INFO 構造体を受け取れませんでした。*lpdwBufferLength で返された値以上のサイズのバッファーを指定して関数を呼び出してください。

解説(Remarks)

次のサンプルコードでは、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 ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして EnumProtocols を定義します。エンコーディング中立のエイリアスを、エンコーディング中立ではないコードと混在させて使用すると、不一致が生じ、コンパイルエラーや実行時エラーを引き起こす可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// MSWSOCK.dll  (ANSI / -A)
#include <windows.h>

INT EnumProtocolsA(
    INT* lpiProtocols,   // optional
    void* lpProtocolBuffer,
    DWORD* lpdwBufferLength
);

[DllImport("MSWSOCK.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern int EnumProtocolsA(
    IntPtr lpiProtocols,   // INT* optional
    IntPtr lpProtocolBuffer,   // void* out
    ref uint lpdwBufferLength   // DWORD* in/out
);

<DllImport("MSWSOCK.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function EnumProtocolsA(
    lpiProtocols As IntPtr,   ' INT* optional
    lpProtocolBuffer As IntPtr,   ' void* out
    ByRef lpdwBufferLength As UInteger   ' DWORD* in/out
) As Integer
End Function

' lpiProtocols : INT* optional
' lpProtocolBuffer : void* out
' lpdwBufferLength : DWORD* in/out
Declare PtrSafe Function EnumProtocolsA Lib "mswsock" ( _
    ByVal lpiProtocols As LongPtr, _
    ByVal lpProtocolBuffer As LongPtr, _
    ByRef lpdwBufferLength As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

EnumProtocolsA = ctypes.windll.mswsock.EnumProtocolsA
EnumProtocolsA.restype = ctypes.c_int
EnumProtocolsA.argtypes = [
    ctypes.POINTER(ctypes.c_int),  # lpiProtocols : INT* optional
    ctypes.POINTER(None),  # lpProtocolBuffer : void* out
    ctypes.POINTER(wintypes.DWORD),  # lpdwBufferLength : DWORD* in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MSWSOCK.dll')
EnumProtocolsA = Fiddle::Function.new(
  lib['EnumProtocolsA'],
  [
    Fiddle::TYPE_VOIDP,  # lpiProtocols : INT* optional
    Fiddle::TYPE_VOIDP,  # lpProtocolBuffer : void* out
    Fiddle::TYPE_VOIDP,  # lpdwBufferLength : DWORD* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "mswsock")]
extern "system" {
    fn EnumProtocolsA(
        lpiProtocols: *mut i32,  // INT* optional
        lpProtocolBuffer: *mut (),  // void* out
        lpdwBufferLength: *mut u32  // DWORD* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("MSWSOCK.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern int EnumProtocolsA(IntPtr lpiProtocols, IntPtr lpProtocolBuffer, ref uint lpdwBufferLength);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MSWSOCK_EnumProtocolsA' -Namespace Win32 -PassThru
# $api::EnumProtocolsA(lpiProtocols, lpProtocolBuffer, lpdwBufferLength)

#uselib "MSWSOCK.dll"
#func global EnumProtocolsA "EnumProtocolsA" sptr, sptr, sptr
; EnumProtocolsA varptr(lpiProtocols), lpProtocolBuffer, varptr(lpdwBufferLength)   ; 戻り値は stat
; lpiProtocols : INT* optional -> "sptr"
; lpProtocolBuffer : void* out -> "sptr"
; lpdwBufferLength : DWORD* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "MSWSOCK.dll"
#cfunc global EnumProtocolsA "EnumProtocolsA" var, sptr, var
; res = EnumProtocolsA(lpiProtocols, lpProtocolBuffer, lpdwBufferLength)
; lpiProtocols : INT* optional -> "var"
; lpProtocolBuffer : void* out -> "sptr"
; lpdwBufferLength : DWORD* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "MSWSOCK.dll"
#cfunc global EnumProtocolsA "EnumProtocolsA" sptr, sptr, sptr
; res = EnumProtocolsA(varptr(lpiProtocols), lpProtocolBuffer, varptr(lpdwBufferLength))
; lpiProtocols : INT* optional -> "sptr"
; lpProtocolBuffer : void* out -> "sptr"
; lpdwBufferLength : DWORD* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。