The WPUCreateSocketHandle function creates a new socket handle.
SOCKET WPUCreateSocketHandle (
DWORD dwCatalogEntryId,
DWORD dwContext,
LPINT lpErrno
);
The WPUCreateSocketHandle function creates a new socket handle for the specified provider. The handles created by WPUCreateSocketHandle are indistinguishable from true file system handles. This is significant in two respects. First, the Windows Socket 2 architecture takes care of redirecting the file system functions ReadFile and WriteFile to this service provider's WSPRecv and WSPSend functions, respectively. Second, in operating systems that support completion ports, the Windows Sockets 2 architecture supports associating a completion port with the socket handle and using it to report overlapped IO completion.
Note, however, that the mechanism for redirecting ReadFile and WriteFile necessarily involves a user-to-kernel transition to get to the redirector, followed by a kernel-to-user transition to get to WSPRecv or WSPSend. On return, these transitions are retraced in reverse. This can be a significant performance penalty. Any service provider that uses WPUCreateSocketHandle to create its socket handles should not set XP1_IFS_HANDLES in its WSAPROTOCOL_INFOW structure. Clients should take the absence of XP1_IFS_HANDLES as guidance to avoid the use of ReadFile and WriteFile.
There is no exceptional performance penalty for using the completion port mechanism with socket handles created with WPUCreateSocketHandle. A service provider should use WPUCompleteOverlappedRequest to announce completion of overlapped IO operations that may involve a completion port. Clients may freely use operating system functions to create, associate, and use a completion port for completion notification (for example, CreateIoCompletionPort, GetQueuedCompletionStatus, see relevant OS documentation for details). Note that completion ports are not integrated with the other asynchronous notification mechanisms offered by Windows Sockets 2. That is, a client can do a multiple-wait that includes multiple events and completion callbacks, but there is no predefined way for the multiple-wait to include completion ports.
This procedure is of particular interest to Layered Service Providers. A layered service provider may use this procedure, instead of WPUModifyIFSHandle to create the socket handles it exposes to its client. The advantage of using this procedure is that all IO requests involving the socket can be guaranteed to go through this service provider. This is true even if the client assumes that the sockets are file system handles and calls the file system functions ReadFile and WriteFile (although it would pay a performance penalty for this assumption).
The guarantee that all IO goes through this layer is a requirement for layers that need to process the IO stream either before or after the actual IO operation. Creating socket handles using WPUCreateSocketHandle and specifying an appropriate service provider interface procedure dispatch table at the time of WSPStartup makes sure that the layer has the chance to get involved in starting each IO operation. When the client requests overlapped IO operations this service provider layer will usually have to arrange to get into the path of IO completion notification as well.
To see why this is true, consider what happens if the client associates a completion port with the socket handle for the purpose of overlapped IO completion notification. The port is associated with the socket handle exposed by this layer, not the next layer's socket handle. There is no way for this layer to determine if a completion port has been associated or what the port is. When this layer calls the next layer's IO operation, it uses the next layer's socket handle. The next layer's socket handle will not have the same completion port association. The client's expected completion-port notification will not happen without some extra help.
The usual way a layered service provider takes care of this is to substitute a different overlapped IO structure and different overlapped IO parameters when invoking an IO operation in the next layer. The substitute overlapped IO structure references the client's stored overlapped structure and parameters. The invocation of the next layer sets up a callback notification. When the callback notification occurs, this layer performs any post-processing desired, retrieves the overlapped IO information it stored on behalf of the client, discards the substitute structures, and forwards an appropriate completion notification to the client.
If no error occurs, WPUCreateSocketHandle returns the new socket handle. Otherwise, it returns INVALID_SOCKET, and a specific error code is available in lpErrno.
| WSAENOBUFS | Not enough buffers available, too many sockets. |
Windows NT: Yes
Windows: Yes
Windows CE: Unsupported.
Header: Declared in ws2spi.h.
WPUCloseSocketHandle, WPUQuerySocketHandleContext, WPUModifyIFSHandle, WPUCompleteOverlappedRequest