WSPStartupEx function

WSPStartupEx initiates use by the Windows Sockets switchof a SAN service provider.

Syntax

int WSPStartupEx(
  _In_  WORD                wVersionRequested,
  _Out_ LPWSPDATA           lpWSPData,
  _In_  LPWSAPROTOCOL_INFOW lpProtocolInfo,
  _In_  LPWSPUPCALLTABLEEX  lpUpcallTable,
  _Out_ LPWSPPROC_TABLE     lpProcTable
);

Parameters

• wVersionRequested [in]
  Highest version of Windows Sockets SPI supported by the switch. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

• lpWSPData [out]
  Pointer to a WSPDATA structure in which the SAN service provider returns information about itself.

• lpProtocolInfo [in]
  Pointer to a WSAPROTOCOL_INFOW structure that specifies the characteristics of the protocol required for transferring data. Note that the switch passes the protocol information structure of the TCP/IP protocol, not the protocol information structure of the SAN service provider itself.

• lpUpcallTable [in]
  Pointer to a WSPUPCALLTABLEEX structure that specifies the extended upcall dispatch table of the Windows Sockets Direct interface.

• lpProcTable [out]
  Pointer to a WSPPROC_TABLE structure that receives a table of pointers to the SAN service provider's entry points.

Return value

Returns zero if successful; otherwise, returns one of the following error codes:

Remarks

WSPUPCALLTABLEEX

The WSPUPCALLTABLEEX structure is defined as:

typedef struct _WSPUPCALLTABLEEX {
    LPWPUCLOSEEVENT                lpWPUCloseEvent;
    LPWPUCLOSESOCKETHANDLE         lpWPUCloseSocketHandle;
    LPWPUCREATEEVENT               lpWPUCreateEvent;
    LPWPUCREATESOCKETHANDLE        lpWPUCreateSocketHandle;
    LPWPUFDISSET                   lpWPUFDIsSet;
    LPWPUGETPROVIDERPATH           lpWPUGetProviderPath;
    LPWPUMODIFYIFSHANDLE           lpWPUModifyIFSHandle;
    LPWPUPOSTMESSAGE               lpWPUPostMessage;
    LPWPUQUERYBLOCKINGCALLBACK     lpWPUQueryBlockingCallback;
    LPWPUQUERYSOCKETHANDLECONTEXT  lpWPUQuerySocketHandleContext;
    LPWPUQUEUEAPC                  lpWPUQueueApc;
    LPWPURESETEVENT                lpWPUResetEvent;
    LPWPUSETEVENT                  lpWPUSetEvent;
    LPWPUOPENCURRENTTHREAD         lpWPUOpenCurrentThread;
    LPWPUCLOSETHREAD               lpWPUCloseThread;
    LPWPUCOMPLETEOVERLAPPEDREQUEST lpWPUCompleteOverlappedRequest;
} WSPUPCALLTABLEEX, FAR * LPWSPUPCALLTABLEEX;

The switch calls a SAN service provider's WSPStartupEx function before calling any of the SAN service provider's other functions. The switch does not call a SAN service provider's other functions until the WSPStartupEx function returns successfully.

In the call to the WSPStartupEx function, the switch passes the following to the SAN service provider:

• The highest version of Windows Sockets SPI that the switch supports.

• A pointer to a WSAPROTOCOL_INFOW structure. Note that the switch passes information about the TCP/IP protocol rather than information for the SAN service provider. The SAN service provider uses this information to determine whether it was loaded by the switch, by another layered service provider, or by the Windows Sockets interface (Ws2_32.dll). A SAN service provider could expose one set of entry points to the switch and another set to applications that load the SAN service provider directly.

• A pointer to the switch's upcall dispatch table. The SAN service provider uses this table to make upcalls. Up-calls are calls to Windows Sockets SPI functions that are prefixed with WPU. The switch intercepts and processes these upcalls. A SAN service provider must use the WPUCompleteOverlappedRequest function referenced in the extended upcall dispatch table to complete overlapped I/O. For more information about WPUCompleteOverlappedRequest, see the Microsoft Windows SDK documentation.

If the WSPStartupEx function succeeds, the SAN service provider passes the following back to the switch:

• A pointer to a WSPDATA structure in which the SAN service provider returns information about itself.

• A table of pointers to most of the SAN service provider's functions through lpProcTable. For a list of these functions, see Windows Sockets SPI Functions Required for SANs. To retrieve pointers to a SAN service provider's extension functions, the switch calls the SAN service provider's WSPIoctl function. For a list of the extension functions, see Windows Sockets Direct Extensions.

If the version specified by the switch in wVersionRequested is equal to or later than the lowest version that the SAN service provider supports, the SAN service provider returns zero (for success) and its version information in a WSPDATA structure at lpWSPData. The SAN service provider specifies its version information in the wVersion member of this structure; it does not assign a value to the wHighVersion member of this structure. The switch only examines the value that the SAN service provider returns in the wVersion member. If the value in the wVersion member of WSPDATA is unacceptable to the switch, it immediately calls the SAN service provider's WSPCleanup function. In this case, the switch continues to use the TCP/IP service provider and could initiate and use other SAN service providers.

Note that SAN service providers must specify version 2.2 or later in the wVersion member of WSPDATA.

The switch can call the WSPStartupEx function for the SAN service provider multiple times if the switch requires that the SAN service provider return information in a pointer to the WSPDATA structure more than once. On each such call, the switch can specify any version number that the SAN service provider supports. For each successful WSPStartupEx call that the switch makes, the switch makes a corresponding WSPCleanup call. For example, if the switch calls WSPStartupEx three times, the switch makes three corresponding calls to WSPCleanup. In the first two WSPCleanup calls, the SAN service provider should do nothing except decrement an internal counter. In the final WSPCleanup call, the SAN service provider should release all previously allocated resources.

Requirements

See also

WSAPROTOCOL_INFOW

WSPCleanup

WSPDATA

WSPIoctl

Send comments about this topic to Microsoft