Freigeben über


WSAPROTOCOL_INFO Structure

The WSAPROTOCOL_INFO structure is used to store or retrieve complete information for a given protocol.

Syntax

typedef struct _WSAPROTOCOL_INFO {
  DWORD            dwServiceFlags1;
  DWORD            dwServiceFlags2;
  DWORD            dwServiceFlags3;
  DWORD            dwServiceFlags4;
  DWORD            dwProviderFlags;
  GUID             ProviderId;
  DWORD            dwCatalogEntryId;
  WSAPROTOCOLCHAIN ProtocolChain;
  int              iVersion;
  int              iAddressFamily;
  int              iMaxSockAddr;
  int              iMinSockAddr;
  int              iSocketType;
  int              iProtocol;
  int              iProtocolMaxOffset;
  int              iNetworkByteOrder;
  int              iSecurityScheme;
  DWORD            dwMessageSize;
  DWORD            dwProviderReserved;
  TCHAR            szProtocol[WSAPROTOCOL_LEN+1];
} WSAPROTOCOL_INFO, *LPWSAPROTOCOL_INFO;

Mitglieder

  • dwServiceFlags1
    Typ: DWORD

    A bitmask that describes the services provided by the protocol. The possible values for this member are defined in the Winsock2.h header file.

    The following values are possible.

    Wert Bedeutung
    XP1_CONNECTIONLESS 0x00000001

    Provides connectionless (datagram) service. If not set, the protocol supports connection-oriented data transfer.

    XP1_GUARANTEED_DELIVERY 0x00000002

    Guarantees that all data sent will reach the intended destination.

    XP1_GUARANTEED_ORDER 0x00000004

    Guarantees that data only arrives in the order in which it was sent and that it is not duplicated. This characteristic does not necessarily mean that the data is always delivered, but that any data that is delivered is delivered in the order in which it was sent.

    XP1_MESSAGE_ORIENTED 0x00000008

    Honors message boundaries—as opposed to a stream-oriented protocol where there is no concept of message boundaries.

    XP1_PSEUDO_STREAM 0x00000010

    A message-oriented protocol, but message boundaries are ignored for all receipts. This is convenient when an application does not desire message framing to be done by the protocol.

    XP1_GRACEFUL_CLOSE 0x00000020

    Supports two-phase (graceful) close. If not set, only abortive closes are performed.

    XP1_EXPEDITED_DATA 0x00000040

    Supports expedited (urgent) data.

    XP1_CONNECT_DATA 0x00000080

    Supports connect data.

    XP1_DISCONNECT_DATA 0x00000100

    Supports disconnect data.

    XP1_SUPPORT_BROADCAST 0x00000200

    Supports a broadcast mechanism.

    XP1_SUPPORT_MULTIPOINT 0x00000400

    Supports a multipoint or multicast mechanism. Control and data plane attributes are indicated below.

    XP1_MULTIPOINT_CONTROL_PLANE 0x00000800

    Indicates whether the control plane is rooted (value = 1) or nonrooted (value = 0).

    XP1_MULTIPOINT_DATA_PLANE 0x00001000

    Indicates whether the data plane is rooted (value = 1) or nonrooted (value = 0).

    XP1_QOS_SUPPORTED 0x00002000

    Supports quality of service requests.

    XP1_INTERRUPT

    Bit is reserved.

    XP1_UNI_SEND 0x00008000

    Protocol is unidirectional in the send direction.

    XP1_UNI_RECV 0x00010000

    Protocol is unidirectional in the recv direction.

    XP1_IFS_HANDLES 0x00020000

    Socket descriptors returned by the provider are operating system Installable File System (IFS) handles.

    XP1_PARTIAL_MESSAGE 0x00040000

    The MSG_PARTIAL flag is supported in WSASend and WSASendTo.

    XP1_SAN_SUPPORT_SDP 0x00080000

    The protocol provides support for SAN.

    This value is supported on Windows 7 and Windows Server 2008 R2.

     

    Hinweis  Only one of XP1_UNI_SEND or XP1_UNI_RECV values may be set. If a protocol can be unidirectional in either direction, two WSAPROTOCOL_INFOW structures should be used. When neither bit is set, the protocol is considered to be bidirectional.

  • dwServiceFlags2
    Typ: DWORD

    Reserved for additional protocol-attribute definitions.

  • dwServiceFlags3
    Typ: DWORD

    Reserved for additional protocol-attribute definitions.

  • dwServiceFlags4
    Typ: DWORD

    Reserved for additional protocol-attribute definitions.

  • dwProviderFlags
    Typ: DWORD

    A set of flags that provides information on how this protocol is represented in the Winsock catalog. The possible values for this member are defined in the Winsock2.h header file.

    The following flag values are possible.

    Wert Bedeutung
    PFL_MULTIPLE_PROTO_ENTRIES 0x00000001

    Indicates that this is one of two or more entries for a single protocol (from a given provider) which is capable of implementing multiple behaviors. An example of this is SPX which, on the receiving side, can behave either as a message-oriented or a stream-oriented protocol.

    PFL_RECOMMENDED_PROTO_ENTRY 0x00000002

    Indicates that this is the recommended or most frequently used entry for a protocol that is capable of implementing multiple behaviors.

    PFL_HIDDEN 0x00000004

    Set by a provider to indicate to the Ws2_32.dll that this protocol should not be returned in the result buffer generated by WSAEnumProtocols. Obviously, a Windows Sockets 2 application should never see an entry with this bit set.

    PFL_MATCHES_PROTOCOL_ZERO 0x00000008

    Indicates that a value of zero in the protocol parameter of socket or WSASocket matches this protocol entry.

    PFL_NETWORKDIRECT_PROVIDER 0x00000010

    Set by a provider to indicate support for network direct access.

    This value is supported on Windows 7 and Windows Server 2008 R2.

     

  • ProviderId
    Typ: GUID

    A globally unique identifier (GUID) assigned to the provider by the service provider vendor. This value is useful for instances where more than one service provider is able to implement a particular protocol. An application can use the ProviderId member to distinguish between providers that might otherwise be indistinguishable.

  • dwCatalogEntryId
    Typ: DWORD

    A unique identifier assigned by the WS2_32.DLL for each WSAPROTOCOL_INFO structure.

  • ProtocolChain
    Typ: WSAPROTOCOLCHAIN

    The WSAPROTOCOLCHAIN structure associated with the protocol. If the length of the chain is 0, this WSAPROTOCOL_INFO entry represents a layered protocol which has Windows Sockets 2 SPI as both its top and bottom edges. If the length of the chain equals 1, this entry represents a base protocol whose Catalog Entry identifier is in the dwCatalogEntryId member of the WSAPROTOCOL_INFO structure. If the length of the chain is larger than 1, this entry represents a protocol chain which consists of one or more layered protocols on top of a base protocol. The corresponding Catalog Entry identifiers are in the ProtocolChain.ChainEntries array starting with the layered protocol at the top (the zero element in the ProtocolChain.ChainEntries array) and ending with the base protocol. Refer to the Windows Sockets 2 Service Provider Interface specification for more information on protocol chains.

  • iVersion
    Typ: int

    The protocol version identifier.

  • iAddressFamily
    Typ: int

    A value to pass as the address family parameter to the socket or WSASocket function in order to open a socket for this protocol. This value also uniquely defines the structure of a protocol address for a sockaddr used by the protocol.

    On the Windows SDK released for Windows Vista and later, the possible values for the address family are defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

    On versions of the Platform SDK for Windows Server 2003 and older, the possible values for the address family are defined in the Winsock2.h header file.

    The values currently supported are AF_INET or AF_INET6, which are the Internet address family formats for IPv4 and IPv6. Other options for address family (AF_NETBIOS for use with NetBIOS, for example) are supported if a Windows Sockets service provider for the address family is installed. Note that the values for the AF_ address family and PF_ protocol family constants are identical (for example, AF_INET and PF_INET), so either constant can be used.

    The table below lists common values for address family although many other values are possible.

    iAddressFamily Bedeutung
    AF_INET 2

    The Internet Protocol version 4 (IPv4) address family.

    AF_IPX 6

    The IPX/SPX address family. This address family is only supported if the NWLink IPX/SPX NetBIOS Compatible Transport protocol is installed.

    This address family is not supported on Windows Vista and later.

    AF_APPLETALK 16

    The AppleTalk address family. This address family is only supported if the AppleTalk protocol is installed.

    This address family is not supported on Windows Vista and later.

    AF_NETBIOS 17

    The NetBIOS address family. This address family is only supported if the Windows Sockets provider for NetBIOS is installed.

    The Windows Sockets provider for NetBIOS is supported on 32-bit versions of Windows. This provider is installed by default on 32-bit versions of Windows.

    The Windows Sockets provider for NetBIOS is not supported on 64-bit versions of windows including Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, or Windows XP.

    The Windows Sockets provider for NetBIOS only supports sockets where the type parameter is set to SOCK_DGRAM.

    The Windows Sockets provider for NetBIOS is not directly related to the NetBIOS programming interface. The NetBIOS programming interface is not supported on Windows Vista, Windows Server 2008, and later.

    AF_INET6 23

    The Internet Protocol version 6 (IPv6) address family.

    AF_IRDA 26

    The Infrared Data Association (IrDA) address family.

    This address family is only supported if the computer has an infrared port and driver installed.

    AF_BTH 32

    The Bluetooth address family.

    This address family is supported on Windows XP mit SP2 or later if the computer has a Bluetooth adapter and driver installed.

     

  • iMaxSockAddr
    Typ: int

    The maximum address length, in bytes.

  • iMinSockAddr
    Typ: int

    The minimum address length, in bytes.

  • iSocketType
    Typ: int

    A value to pass as the socket type parameter to the socket or WSASocket function in order to open a socket for this protocol. Possible values for the socket type are defined in the Winsock2.h header file.

    The following table lists the possible values for the iSocketType member supported for Windows Sockets 2:

    iSocketType Bedeutung
    SOCK_STREAM 1

    A socket type that provides sequenced, reliable, two-way, connection-based byte streams with an OOB data transmission mechanism. This socket type uses the Transmission Control Protocol (TCP) for the Internet address family (AF_INET or AF_INET6).

    SOCK_DGRAM 2

    A socket type that supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. This socket type uses the User Datagram Protocol (UDP) for the Internet address family (AF_INET or AF_INET6).

    SOCK_RAW 3

    A socket type that provides a raw socket that allows an application to manipulate the next upper-layer protocol header. To manipulate the IPv4 header, the IP_HDRINCL socket option must be set on the socket. To manipulate the IPv6 header, the IPV6_HDRINCL socket option must be set on the socket.

    SOCK_RDM 4

    A socket type that provides a reliable message datagram. An example of this type is the Pragmatic General Multicast (PGM) multicast protocol implementation in Windows, often referred to as reliable multicast programming.

    This value is only supported if the Reliable Multicast Protocol is installed.

    SOCK_SEQPACKET 5

    A socket type that provides a pseudo-stream packet based on datagrams.

     

  • iProtocol
    Typ: int

    A value to pass as the protocol parameter to the socket or WSASocket function in order to open a socket for this protocol. The possible options for the iProtocol member are specific to the address family and socket type specified.

    On the Windows SDK released for Windows Vista and later, this member can be one of the values from the IPPROTO enumeration type defined in the Ws2def.h header file. Note that the Ws2def.h header file is automatically included in Winsock2.h, and should never be used directly.

    On versions of the Platform SDK for Windows Server 2003 and earlier, the possible values for the iProtocol member are defined in the Winsock2.h and Wsrm.h header files.

    The table below lists common values for the iProtocol although many other values are possible.

    iProtocol Bedeutung
    IPPROTO_ICMP 1

    The Internet Control Message Protocol (ICMP).

    This value is supported on Windows XP and later.

    IPPROTO_IGMP 2

    The Internet Group Management Protocol (IGMP).

    This value is supported on Windows XP and later.

    BTHPROTO_RFCOMM 3

    The Bluetooth Radio Frequency Communications (Bluetooth RFCOMM) protocol.

    This value is supported on Windows XP mit SP2 or later.

    IPPROTO_TCP 6

    The Transmission Control Protocol (TCP).

    IPPROTO_UDP 17

    The User Datagram Protocol (UDP).

    IPPROTO_ICMPV6 58

    The Internet Control Message Protocol Version 6 (ICMPv6).

    This value is supported on Windows XP and later.

    IPPROTO_RM 113

    The PGM protocol for reliable multicast. On the Windows SDK released for Windows Vista and later, this protocol is also called IPPROTO_PGM.

    This value is only supported if the Reliable Multicast Protocol is installed.

     

  • iProtocolMaxOffset
    Typ: int

    The maximum value that may be added to iProtocol when supplying a value for the protocol parameter to socket or WSASocket function. Not all protocols allow a range of values. When this is the case iProtocolMaxOffset is zero.

  • iNetworkByteOrder
    Typ: int

    Currently these values are manifest constants (BIGENDIAN and LITTLEENDIAN) that indicate either big-endian or little-endian with the values 0 and 1 respectively.

  • iSecurityScheme
    Typ: int

    The type of security scheme employed (if any). A value of SECURITY_PROTOCOL_NONE (0) is used for protocols that do not incorporate security provisions.

  • dwMessageSize
    Typ: DWORD

    The maximum message size, in bytes, supported by the protocol. This is the maximum size that can be sent from any of the host's local interfaces. For protocols that do not support message framing, the actual maximum that can be sent to a given address may be less. There is no standard provision to determine the maximum inbound message size. The following special values are defined.

    Wert Bedeutung
    0

    The protocol is stream-oriented and hence the concept of message size is not relevant.

    0x1

    The maximum outbound (send) message size is dependent on the underlying network MTU (maximum sized transmission unit) and hence cannot be known until after a socket is bound. Applications should use getsockopt to retrieve the value of SO_MAX_MSG_SIZE after the socket has been bound to a local address.

    0xFFFFFFFF

    The protocol is message-oriented, but there is no maximum limit to the size of messages that may be transmitted.

     

  • dwProviderReserved
    Typ: DWORD

    Reserved for use by service providers.

  • szProtocol
    Typ: TCHAR[WSAPROTOCOL_LEN+1]

    An array of characters that contains a human-readable name identifying the protocol, for example "MSAFD Tcpip [UDP/IP]". The maximum number of characters allowed is WSAPROTOCOL_LEN, which is defined to be 255.

Beispiele

The following example demonstrates the use of the WSAEnumProtocols function to retrieve an array of WSAPROTOCOL_INFO structures for available transport protocols.

#ifndef UNICODE
#define UNICODE 1
#endif

#include <winsock2.h>
#include <ws2tcpip.h>
#include <objbase.h>
#include <stdio.h>

// Link with ws2_32.lib and ole32.lib
#pragma comment (lib, "Ws2_32.lib")
#pragma comment (lib, "ole32.lib")

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
// Note: could also use malloc() and free()

int wmain()
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult = 0;

    int iError = 0;
    INT iNuminfo = 0;

    int i;

    // Allocate a 16K buffer to retrieve all the protocol providers
    DWORD dwBufferLen = 16384;

    LPWSAPROTOCOL_INFO lpProtocolInfo = NULL;

    // variables needed for converting provider GUID to a string
    int iRet = 0;
    WCHAR GuidString[40] = { 0 };

    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed: %d\n", iResult);
        return 1;
    }

    lpProtocolInfo = (LPWSAPROTOCOL_INFO) MALLOC(dwBufferLen);
    if (lpProtocolInfo == NULL) {
        wprintf(L"Memory allocation for providers buffer failed\n");
        WSACleanup();
        return 1;
    }

    iNuminfo = WSAEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen);
    if (iNuminfo == SOCKET_ERROR) {
        iError = WSAGetLastError();
        if (iError != WSAENOBUFS) {
            wprintf(L"WSAEnumProtocols failed with error: %d\n", iError);
            if (lpProtocolInfo) {
                FREE(lpProtocolInfo);
                lpProtocolInfo = NULL;
            }
            WSACleanup();
            return 1;
        } else {
            wprintf(L"WSAEnumProtocols failed with error: WSAENOBUFS (%d)\n",
                    iError);
            wprintf(L"  Increasing buffer size to %d\n\n", dwBufferLen);
            if (lpProtocolInfo) {
                FREE(lpProtocolInfo);
                lpProtocolInfo = NULL;
            }
            lpProtocolInfo = (LPWSAPROTOCOL_INFO) MALLOC(dwBufferLen);
            if (lpProtocolInfo == NULL) {
                wprintf(L"Memory allocation increase for buffer failed\n");
                WSACleanup();
                return 1;
            }
            iNuminfo = WSAEnumProtocols(NULL, lpProtocolInfo, &dwBufferLen);
            if (iNuminfo == SOCKET_ERROR) {
                iError = WSAGetLastError();
                wprintf(L"WSAEnumProtocols failed with error: %d\n", iError);
                if (lpProtocolInfo) {
                    FREE(lpProtocolInfo);
                    lpProtocolInfo = NULL;
                }
                WSACleanup();
                return 1;
            }

        }
    }

    wprintf(L"WSAEnumProtocols succeeded with protocol count = %d\n\n",
            iNuminfo);
    for (i = 0; i < iNuminfo; i++) {
        wprintf(L"Winsock Catalog Provider Entry #%d\n", i);
        wprintf
            (L"----------------------------------------------------------\n");
        wprintf(L"Entry type:\t\t\t ");
        if (lpProtocolInfo[i].ProtocolChain.ChainLen = 1)
            wprintf(L"Base Service Provider\n");
        else
            wprintf(L"Layered Chain Entry\n");

        wprintf(L"Protocol:\t\t\t %ws\n", lpProtocolInfo[i].szProtocol);

        iRet =
            StringFromGUID2(lpProtocolInfo[i].ProviderId,
                            (LPOLESTR) & GuidString, 39);
        if (iRet == 0)
            wprintf(L"StringFromGUID2 failed\n");
        else
            wprintf(L"Provider ID:\t\t\t %ws\n", GuidString);

        wprintf(L"Catalog Entry ID:\t\t %u\n",
                lpProtocolInfo[i].dwCatalogEntryId);

        wprintf(L"Version:\t\t\t %d\n", lpProtocolInfo[i].iVersion);

        wprintf(L"Address Family:\t\t\t %d\n",
                lpProtocolInfo[i].iAddressFamily);
        wprintf(L"Max Socket Address Length:\t %d\n",
                lpProtocolInfo[i].iMaxSockAddr);
        wprintf(L"Min Socket Address Length:\t %d\n",
                lpProtocolInfo[i].iMinSockAddr);

        wprintf(L"Socket Type:\t\t\t %d\n", lpProtocolInfo[i].iSocketType);
        wprintf(L"Socket Protocol:\t\t %d\n", lpProtocolInfo[i].iProtocol);
        wprintf(L"Socket Protocol Max Offset:\t %d\n",
                lpProtocolInfo[i].iProtocolMaxOffset);

        wprintf(L"Network Byte Order:\t\t %d\n",
                lpProtocolInfo[i].iNetworkByteOrder);
        wprintf(L"Security Scheme:\t\t %d\n",
                lpProtocolInfo[i].iSecurityScheme);
        wprintf(L"Max Message Size:\t\t %u\n", lpProtocolInfo[i].dwMessageSize);

        wprintf(L"ServiceFlags1:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags1);
        wprintf(L"ServiceFlags2:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags2);
        wprintf(L"ServiceFlags3:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags3);
        wprintf(L"ServiceFlags4:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwServiceFlags4);
        wprintf(L"ProviderFlags:\t\t\t 0x%x\n",
                lpProtocolInfo[i].dwProviderFlags);

        wprintf(L"Protocol Chain length:\t\t %d\n",
                lpProtocolInfo[i].ProtocolChain.ChainLen);

        wprintf(L"\n");
    }

    if (lpProtocolInfo) {
        FREE(lpProtocolInfo);
        lpProtocolInfo = NULL;
    }
    WSACleanup();

    return 0;
}

Anforderungen

Mindestens unterstützter Client

Windows 2000 Professional

Mindestens unterstützter Server

Windows 2000 Server

Header

Winsock2.h

Unicode- und ANSI-Namen

WSAPROTOCOL_INFOW (Unicode) and WSAPROTOCOL_INFOA (ANSI)

Siehe auch

getsockopt

socket

WSAEnumProtocols

WSAPROTOCOL_INFOW

WSAPROTOCOLCHAIN

WSASend

WSASendTo

WSASocket

WSCInstallProvider

WSCInstallProvider64_32

WSCUpdateProvider

WSCUpdateProvider32