Winsock Catalog | Network Programming for Microsoft Windows (Microsoft Professional Series)

Winsock Catalog

The Winsock catalog is a database that contains the different protocols available on the system. Winsock provides a method for determining which protocols are installed on a given workstation and returning a variety of characteristics for each protocol. If a protocol is capable of multiple behaviors, each distinct behavior type has its own catalog entry within the system. For example, if you install TCP/IP on your system, there will be two IP entries: one for TCP, which is reliable and connection-oriented, and one for UDP, which is unreliable and connectionless.

The function call to obtain information on installed network protocols is WSAEnumProtocols and is defined as:

int WSAEnumProtocols (     LPINT lpiProtocols,      LPWSAPROTOCOL_INFO lpProtocolBuffer,      LPDWORD lpdwBufferLength );

This function supersedes the Winsock 1.1 function EnumProtocols, the necessary function for Windows CE. The only difference is that WSAEnumProtocols returns an array of WSAPROTOCOL_INFO structures, whereas EnumProtocols returns an array of PROTOCOL_INFO structures that contain fewer fields than the WSAPROTOCOL_INFO structure (but more or less the same information). The WSAPROTOCOL_INFO structure is defined as

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, FAR * LPWSAPROTOCOL_INFO;

The easiest way to call WSAEnumProtocols is to make the first call with lpProtocolBuffer equal to NULL and set lpdwBufferLength to 0. The call fails with WSAENOBUFS, but lpdwBufferLength then contains the correct size of the buffer required to return all the protocol information. Once you allocate the correct buffer size and make another call with the supplied buffer, the function returns the number of WSAPROTOCOL_INFO structures returned. At this point, you can step through the structures to find the protocol entry with your required attributes. The sample program called ENUMCAT.C on the companion CD enumerates all installed protocols and prints out each protocol's characteristics.

The most commonly used field of the WSAPROTOCOL_INFO structure is dwServiceFlags1, which is a bit field for the various protocol attributes. Table 2-1 lists the various bit flags that can be set in the field and briefly describes the meaning of each property.

**Table 2-1** *Protocol Flags*
Property	Meaning
XP1_CONNECTIONLESS	This protocol provides connectionless service. If not set, the protocol supports connection-oriented data transfers.
XP1_GUARANTEED_DELIVERY	This protocol guarantees that all data sent will reach the intended recipient.
XP1_GUARANTEED_ORDER	This protocol guarantees that the data will arrive in the order in which it was sent and that it will not be duplicated. However, this does not guarantee delivery.
XP1_MESSAGE_ORIENTED	This protocol honors message boundaries.
XP1_PSEUDO_STREAM	This protocol is message-oriented, but the message boundaries are ignored on the receiver side.
XP1_GRACEFUL_CLOSE	This protocol supports two-phase closes: each party is notified of the other's intent to close the communication channel. If not set, only abortive closes are performed.
XP1_EXPEDITED_DATA	This protocol supports urgent data (out-of-band data).
XP1_CONNECT_DATA	This protocol supports transferring data with the connection request.
XP1_DISCONNECT_DATA	This protocol supports transferring data with the disconnect request.
XP1_SUPPORT_BROADCAST	This protocol supports the broadcast mechanism.
XP1_SUPPORT_MULTIPOINT	This protocol supports multipoint or multicast mechanisms. Multipoint communication is covered in Chapter 9.
XP1_MULTIPOINT_CONTROL_ PLANE	If this flag is set, the control plane is rooted. Otherwise, it is nonrooted.
XP1_MULTIPOINT_DATA_PLANE	If this flag is set, the data plane is rooted. Otherwise, it is nonrooted.
XP1_QOS_SUPPORTED	This protocol supports QOS requests. QOS is covered in Chapter 10.
XP1_UNI_SEND	This protocol is unidirectional in the send direction.
XP1_UNI_RECV	This protocol is unidirectional in the receive direction.
XP1_IFS_HANDLES	The socket descriptors returned by the provider are Installable File System (IFS) handles and can be used in API functions such as ReadFile and WriteFile.
XP1_PARTIAL_MESSAGE	The MSG_PARTIAL flag is supported in WSASend and WSASendTo.
XP1_INTERRUPT	Reserved flag.

Most of these flags will be discussed in one or more of the following chapters, so we won't go into detail about the full meaning of each flag now. The other fields of importance are iProtocol, iSocketType, and iAddressFamily. The iProtocol field defines which protocol an entry belongs to. The iSocketType field is important if the protocol is capable of multiple behaviors, such as stream-oriented connections or datagram connections. Finally, iAddressFamily is used to distinguish the correct addressing structure to use for a given protocol.

Winsock Catalog and Win64

On 64-bit Windows, it is possible to run 32-bit applications under the WOW64 (Windows on Windows) subsystem. Because both 32-bit and 64-bit applications may need to access the Winsock catalog, the system maintains two separate catalogs. When a 64-bit Winsock application runs and calls WSAEnumProtocols, the 64-bit catalog is used. Likewise, when a 32-bit Winsock application calls WSAEnumProtocols, the 32-bit catalog is used. This will become more important when dealing with the Winsock Service Provider Interface, which is discussed in Chapter 12.

Creating Sockets

In Chapter 1 we saw simple examples of how to create a socket using the socket function. This function takes three parameters: address family, socket type, and protocol. When an application creates a socket, the Winsock catalog is consulted and an attempt is made to match the supplied parameters with those contained in each WSAPROTOCOL_INFO structure. If the parameters match, then a socket is created from that provider. Note that in some instances the protocol parameter can be 0. If the dwProviderFlags field of the WSAPROTOCOL_INFO structure is PFL_MATCHES_PROTOCOL_ZERO and if the requested address family and socket type match its entries, then that provider is used to create a socket. For example, consider the following call:

SOCKET s; s = socket(AF_INET, SOCK_STREAM, 0);

Winsock will enumerate the catalog and first match the address family followed by the socket type. Since the protocol value is 0 and the MSAFD TCP provider contains the PFL_MATCHES_PROTOCOL_ZERO flag, this call will create a TCP socket from the MSAFD TCP provider. The system will not attempt to match the request to any further providers.

In some instances, multiple providers may share the same address family, socket type, and protocol. This is the case with the RSVP provider. The RSVP provider offers QOS over TCP/IP and UDP/IP. Because multiple providers share the same address family, socket type, and protocol, there is no way to use the socket API to create a socket from the RSVP provider. To do so, you must use the Winsock 2 function WSASocket, which is defined as

SOCKET WSASocket( int af,  int type,  int protocol, LPWSAPROTOCOL_INFO lpProtocolInfo, GROUP g, DWORD dwFlags);

The first three parameters are the same as those of socket but the fourth parameter takes a WSAPROTOCOL_INFO structure. If lpProtocolInfo references a provider entry and each of the first three parameters is the predefined value FROM_PROTOCOL_INFO, then a socket is created from the given provider. An application can create an RSVP socket using this method.

The fourth parameter deals with socket groups that are discussed in the Winsock specification but are not implemented in Windows. The last parameter is optional flags that may be passed. For now, the only flag of importance is WSA_FLAG_OVERLAPPED. If you plan on using overlapped IO (as described in Chapter 5), then this flag needs to be present when creating the socket. Note that when using the socket API, the overlapped flag is always implied. The other socket flags pertain to multicasting and are covered in Chapter 9.