WPUCreateSocketHandle function (ws2spi.h)
The WPUCreateSocketHandle function creates a new socket handle.
Syntax
SOCKET WPUCreateSocketHandle(
[in] DWORD dwCatalogEntryId,
[in] DWORD_PTR dwContext,
[out] LPINT lpErrno
);
Parameters
[in] dwCatalogEntryId
Descriptor identifying the calling service provider.
[in] dwContext
Context value to associate with the new socket handle.
[out] lpErrno
Pointer to the error code.
Return value
If no error occurs, WPUCreateSocketHandle returns the new socket handle. Otherwise, it returns INVALID_SOCKET, and a specific error code is available in lpErrno.
Error code | Meaning |
---|---|
There are not enough buffers available to create the new socket handle. |
Remarks
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 LPWSPRecv and LPWSPSend 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.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 2000 Professional [desktop apps only] |
Minimum supported server | Windows 2000 Server [desktop apps only] |
Target Platform | Windows |
Header | ws2spi.h |