The WPUCreateSocketHandle function creates a new socket handle.
SOCKET WPUCreateSocketHandle( _In_ DWORD dwCatalogEntryId, _In_ DWORD_PTR dwContext, _Out_ LPINT lpErrno );
- dwCatalogEntryId [in]
Descriptor identifying the calling service provider.
- dwContext [in]
Context value to associate with the new socket handle.
- lpErrno [out]
Pointer to the error code.
If no error occurs, WPUCreateSocketHandle returns the new socket handle. Otherwise, it returns INVALID_SOCKET, and a specific error code is available in lpErrno.
There are not enough buffers available to create the new socket handle.
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 I/O completion.
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 I/O 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 I/O goes through this layer is a requirement for layers that need to process the I/O stream either before or after the actual I/O operation. Creating socket handles using WPUCreateSocketHandle and specifying an appropriate service provider interface procedure dispatch table at the time of WSPStartup ensures that the layer has the chance to get involved in starting each I/O operation. When the client requests overlapped I/O operations, this service provider layer will usually have to arrange to get into the path of I/O 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 I/O 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 I/O 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 I/O structure and different overlapped I/O parameters when invoking an I/O operation in the next layer. The substitute overlapped I/O 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 I/O information it stored on behalf of the client, discards the substitute structures, and forwards an appropriate completion notification to the client.
Minimum supported client
Windows 2000 Professional [desktop apps only]
Minimum supported server
Windows 2000 Server [desktop apps only]