WPUModifyIFSHandle

The WPUModityIFSHandle function receives (possibly) modified IFS handle from WS2_32.DLL.

SOCKET WPUModifyIFSHandle (
  DWORD dwCatalogEntryId,   
  SOCKET ProposedHandle,   
  LPINT lpErrno            
);
 

Parameters

dwCatalogEntryId
[in] A descriptor identifying the calling service provider.
ProposedHandle
[in] An Installable File System(IFS) handle allocated by the provider.
lpErrno
[out] A pointer to the error code.

Remarks

The WPUModityIFSHandle handle allows the WS2_32.DLL to streamline its internal operations by returning a possibly modified version of the supplied IFS handle. It is guaranteed that the returned handle is indistinguishable from the proposed handle as far as the operating system is concerned. IFS providers must call this function before returning any newly created socket descriptor to a service provider. The service provider will only use the modified handle for any subsequent socket operations.

This routine is only used by IFS providers whose socket descriptors are real Installable File System handles.

Layered Service Provider Considerations

This procedure may also be used by a layered provider that is layered on top of a base IFS provider and wants to expose the base provider's socket handles as its own instead of creating them with the WPUCreateSocketHandle call. A layered provider that wishes to "pass through" the IFS socket handles it receives from the next layer in the chain can call WPUModifyIFSHandle, passing its own catalog entry Id as dwCatalogEntryId. This informs the Windows Sockets DLL that this layer, and not the next layer, should be the target for SPI calls involving that socket handle.

There are several limitations a layered provider should observe if it takes this approach.

Return Values

If no error occurs, WPUModifyIFSHandle returns the modified socket handle. Otherwise, it returns INVALID_SOCKET, and a specific error code is available in lpErrno.

Error Codes

WSAEINVAL The proposed handle is invalid.

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Unsupported.
  Header: Declared in ws2spi.h.

See Also

WPUCreateSocketHandle