WSAPROTOCOL_INFOW structure

The Windows Sockets WSAPROTOCOL_INFOW structure is used to store or retrieve complete information for a given protocol.

Syntax

typedef struct _WSAPROTOCOL_INFOW {
  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;
  WCHAR            szProtocol[WSAPROTOCOL_LEN+1];
} WSAPROTOCOL_INFOW, *LPWSAPROTOCOL_INFOW;

Members

  • dwServiceFlags1
    Bitmask describing the services provided by the protocol. The bitmask can be set with one or more (ORed) of the following flags:

    • XP1_CONNECTIONLESS
      Protocol provides connectionless (datagram) service. This flag is not set by a SAN service provider, because it only provides connection-oriented data transfers.

    • XP1_GUARANTEED_DELIVERY
      Protocol guarantees that all data that it sends reaches the intended destination.

    • XP1_GUARANTEED_ORDER
      Protocol guarantees that data arrives in the order in which the protocol sent it and that it is not duplicated. The protocol does not guarantee that the data was delivered.

    • XP1_MESSAGE_ORIENTED
      Protocol honors message boundaries, as opposed to a stream-oriented protocol, which does not honor message boundaries.

    • XP1_PSEUDO_STREAM
      Although the protocol is message-oriented, it ignores message boundaries for all receives. This is convenient when an application does not require that the protocol frame messages.

    • XP1_GRACEFUL_CLOSE
      Protocol supports two-phase (graceful) socket closures. If not set, the protocol performs only abortive closures.

    • XP1_EXPEDITED_DATA
      Protocol supports expedited (urgent) data.

    • XP1_CONNECT_DATA
      Protocol supports data related to a connection request.

    • XP1_DISCONNECT_DATA
      Protocol supports data related to a connection shutdown.

    • XP1_SUPPORT_BROADCAST
      Protocol supports a broadcast mechanism.

    • XP1_SUPPORT_MULTIPOINT
      Protocol supports a multipoint or multicast mechanism. Control and data plane attributes are indicated in the following values.

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

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

    • XP1_QOS_SUPPORTED
      Set by a SAN service provider if it supports quality of service requests.

    • XP1_RESERVED
      Reserved.

    • XP1_UNI_SEND
      Protocol is unidirectional in the send direction.

    • XP1_UNI_RECV
      Protocol is unidirectional in the receive direction.

    • XP1_IFS_HANDLES
      Socket descriptors returned by the provider are handles to installable file system (IFS) objects. This flag is not set by a SAN service provider, because the socket descriptors it returns are not handles to IFS objects.

    • XP1_PARTIAL_MESSAGE
      The MSG_PARTIAL flag is supported in WSPSend.

    • XP1_SAN_SUPPORT_SDP
      Reserved.

    Note that XP1_UNI_SEND and XP1_UNI_RECV are mutually exclusive. The switch sets neither bit for SAN service providers to indicate that the protocol is bidirectional.

  • dwServiceFlags2
    Reserved for additional protocol-defined attributes.

  • dwServiceFlags3
    Reserved for additional protocol-defined attributes.

  • dwServiceFlags4
    Reserved for additional protocol-defined attributes.

  • dwProviderFlags
    Provides information about how this protocol is represented in the protocol catalog. The following flag values are possible:

    • PFL_MULTIPLE_PROTO_ENTRIES
      Indicates that this is one of two or more entries for a single protocol (from a given provider) that 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
      Indicates that this is the recommended or most frequently used entry for a protocol that is capable of implementing multiple behaviors.

    • PFL_HIDDEN
      Set by a SAN service provider to indicate that it is only indirectly exposed to applications through the Windows Sockets switch.

    • PFL_MATCHES_PROTOCOL_ZERO
      Indicates that a value of zero in the protocol parameter of WSPSocket matches this protocol entry.

  • ProviderId
    Unique identifier assigned to the SAN service provider by the SAN NIC vendor. This value is useful when more than one service provider is able to implement a particular protocol. An application can use the ProviderId value to distinguish between providers that might otherwise be indistinguishable.

  • dwCatalogEntryId
    Unique identifier assigned by the Windows Sockets interface ( Ws2_32.dll) for each WSAPROTOCOL_INFOW structure. This identifier can be set anywhere in the range from 0 to 0xFFFFFFFF.

  • ProtocolChain
    A WSAPROTOCOLCHAIN structure that contains a numbered list of Catalog Entry IDs that comprise a protocol chain.

    If the length of the chain is zero, this WSAPROTOCOL_INFOW entry represents a layered protocol that has Windows Sockets 2 SPI as both its top and bottom edges (for example, the Windows Sockets switch). 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_INFOW structure. If the length of the chain is larger than 1, this entry represents a protocol chain that 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 about protocol chains.

  • iVersion
    Protocol version identifier.

  • iAddressFamily
    Value to pass as the address family parameter to the WSPSocket function to open a socket for this protocol. This value also uniquely defines the structure of protocol addresses (sockaddr structure) used by the protocol (for example, the sockaddr_in structure for TCP/IP). The Windows Sockets switch sets the address family to one of the WSK address families.

  • iMaxSockAddr
    Maximum address length, in bytes.

  • iMinSockAddr
    Minimum address length, in bytes.

  • iSocketType
    Value to pass as the socket type parameter to the Socket function to open a socket for this protocol. The Windows Sockets switch sets the socket type to SOCK_STREAM.

  • iProtocol
    Value to pass as the protocol parameter to the WSPSocket function to open a socket for this protocol.

  • iProtocolMaxOffset
    Maximum value that may be added to iProtocol when supplying a value for the protocol parameter to the WSPSocket function. Not all protocols allow a range of values. When this is the case, iProtocolMaxOffset is zero.

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

  • iSecurityScheme
    Type of security scheme employed, if any. A value of SECURITY_PROTOCOL_NONE is used for protocols that do not incorporate security provisions.

  • dwMessageSize
    Maximum message size 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:

    • 0
      Protocol is stream-oriented; therefore, message size is irrelevant.

    • 0x1
      Maximum outbound (send) message size is dependent on the underlying network MTU (maximum transmission unit) and, therefore, cannot be known until after a socket is bound. The switch should use the WSPGetSockOpt function to retrieve the value of SO_MAX_MSG_SIZE after the socket has been bound to a local address.

    • 0xFFFFFFFF
      Protocol is message-oriented, but there is no maximum limit to the size of messages that may be transmitted.

  • dwProviderReserved
    Reserved for use by service providers. WSD-SAN service providers use this member during socket duplication. A SAN service provider in the destination process uses the value of the dwProviderReserved member to identify the socket context that the SAN provider in source process supplied through a private interface. For more information about how a WSD-SAN provider uses the value of the dwProviderReserved member, see Duplicating Socket Handles for a SAN.

  • szProtocol
    Array of null-terminated characters that contains a human-readable name that identifies the protocol (for example, "TCP"). The maximum number of characters allowed is WSAPROTOCOL_LEN, which is defined to be 256.

Requirements

Version

Requires Windows Sockets version 2.0.

Header

Winsock2.h (include Winsock2.h)

See also

WSAPROTOCOLCHAIN

WSPGetSockOpt

WSPSend

WSPSocket

WSPStartupEx

Send comments about this topic to Microsoft