Handling Socket Options and Control Codes for a SAN

The Windows Sockets switch, in conjunction with the TCP/IP provider, handles most WSPGetSockOpt, WSPSetSockOpt, and WSPIoctl calls initiated by applications. These requests are generally to set and retrieve options and operating parameters associated with an application's socket. The switch does not generally forward these calls to a SAN service provider except as described in the following sections.

Retrieving SAN socket options

The Windows Sockets switch calls a SAN service provider's WSPGetSockOpt function and passes one of the following socket options to retrieve the current value of that option, if the SAN service provider supports that option:

SO_DEBUG
SAN service providers are not required to support this option. They are encouraged, but not required, to supply output debug information if applications set the SO_DEBUG option.

SO_MAX_MSG_SIZE
A SAN service provider must support this option if the underlying SAN transport is message-oriented and the transport limits the amount of data that the switch can send in a call to the SAN service provider's WSPSend function. The switch does not subsequently pass send requests to the SAN service provider that exceed the size that the SAN service provider returns for the value of this option.

SO_MAX_RDMA_SIZE
A SAN service provider must support this option if the underlying SAN transport limits the amount of data that the switch can transfer in calls to either the SAN service provider's WSPRdmaRead or WSPRdmaWrite function. The switch does not subsequently pass RDMA transfer requests to the SAN service provider that exceed the size that the SAN service provider returns for the value of this option.

SO_RDMA_THRESHOLD_SIZE
A SAN service provider supports this option to indicate its preference for the minimum amount of data that the switch can transfer in calls to either the SAN service provider's WSPRdmaRead or WSPRdmaWrite function. However, the switch can set the actual threshold to a value different from the value returned by the SAN service provider. The switch subsequently calls the WSPRdmaRead or WSPRdmaWrite function to transfer data blocks (RDMA transfers) that exceed the size of this threshold and the WSPSend or WSPRecv function to transfer data blocks (message-oriented transfers) that are less than or equal to the size of this threshold.

SO_GROUP_ID, SO_GROUP_PRIORITY
A SAN service provider must support these options if it supports quality of service (QoS). Otherwise, the switch forwards these options to the TCP/IP provider, which maintains default values. A SAN service provider indicates that it supports QoS by setting the XP1_QOS_SUPPORTED bit in the dwServiceFlags member of the WSAPROTOCOL_INFO structure.

Setting SAN socket options

The Windows Sockets switch calls a SAN service provider's WSPSetSockOpt function and passes one of the following socket options to set a value for that option, if the SAN service provider supports that option:

SO_DEBUG
For a description of this socket option, see the preceding list.

SO_GROUP_PRIORITY
For a description of this socket option, see the preceding list.

Accessing SAN socket information

The Windows Sockets switch calls a SAN service provider's WSPIoctl function and passes one of the following control codes to set or retrieve information for that SAN service provider, if the SAN service provider supports that control code:

SIO_GET_EXTENSION_FUNCTION_POINTER
Retrieves a pointer to an extension function that a SAN service provider must support. For more information about extension functions, see Windows Sockets SPI Extensions for SANs. The input buffer of the WSPIoctl call contains the GUID whose value identifies the specified extension function. The SAN service provider returns the pointer to the requested function in WSPIoctl's output buffer. The following table contains GUIDs for extension functions that a SAN service provider can support:

Extension function	GUID
WSPRegisterMemory	{C0B422F5-F58C-11d1-AD6C-00C04FA34A2D}
WSPDeregisterMemory	{C0B422F6-F58C-11d1-AD6C-00C04FA34A2D}
WSPRegisterRdmaMemory	{C0B422F7-F58C-11d1-AD6C-00C04FA34A2D}
WSPDeregisterRdmaMemory	{C0B422F8-F58C-11d1-AD6C-00C04FA34A2D}
WSPRdmaWrite	{C0B422F9-F58C-11d1-AD6C-00C04FA34A2D}
WSPRdmaRead	{C0B422FA-F58C-11d1-AD6C-00C04FA34A2D}
WSPMemoryRegistrationCacheCallback	{E5DA4AF8-D824-48CD-A799-6337A98ED2AF}

SIO_GET_QOS, SIO_GET_GROUP_QOS, SIO_SET_QOS, SIO_SET_GROUP_QOS
A SAN service provider must support these control codes if it supports QoS. Otherwise, the switch forwards these options to the TCP/IP provider, which maintains default values. A provider indicates that it supports QoS by setting the XP1_QOS_SUPPORTED bit in the dwServiceFlags member of the WSAPROTOCOL_INFO structure.

SIO_ADDRESS_LIST_QUERY
Retrieves the list of local IP addresses that are assigned to the network interface cards (NICs) that the SAN service provider controls. The SAN service provider uses a SOCKET_ADDRESS_LIST structure, defined as follows, to return the list in WSPIoctl's output buffer:

typedef struct _SOCKET_ADDRESS_LIST {
    INT             iAddressCount; 
    SOCKET_ADDRESS  Address[1]; 
} SOCKET_ADDRESS_LIST, FAR * LPSOCKET_ADDRESS_LIST;

The members of this structure contain the following information:

iAddressCount
Specifies the number of address structures in the list.

Address
Array of IP address structures.

The switch uses this IOCTL code internally to decide whether to use a given SAN service provider to execute an application's requests to make connections or to listen for incoming connections. The switch forwards actual application requests for the list of local IP addresses to the TCP/IP provider. The switch also uses the TCP/IP provider to detect changes in address lists that all SAN service providers service. After TCP/IP reports a change, the switch queries all SAN service providers to refresh their lists.