Installing an LSP

Other versions of this page are also available for the following:

Windows Mobile SupportedWindows Embedded CE Supported

8/28/2008

To avoid an error when you install an LSP, you must understand how LSPs are installed and how they work with Winsock. For information about provider chains, including illustrations of how multiple LSPs are installed, see Layered Protocols and Provider Chains.

Windows Embedded CE includes sample code for an LSP as well as the corresponding LSP installer code in the %_WINCEROOT%\Public\Common\SDK\Samples\TSP\LSP folder. For more information on LSP, see the article Unraveling the Mysteries of Writing a Winsock 2 Layered Service Provider, which is published on MSDN.

Note

This topic provides information about installing LSPs on Windows CE 5.0 and later. In earlier releases, LSP chain order on CE is solely determined by the order of installation.

LSP Implementation in Windows Embedded CE

The following list shows the differences between the implementation of LSPs in Windows Embedded CE and desktop.

  • All LSP Installers run on device startup. The catalog of all the installed service providers is not persisted across reboots.
  • The order of LSP chains is determined by the order in which installation routines run.
  • The WSCWriteProviderOrder function is not supported on Windows Embedded CE.
  • The Sporder.exe utility is not supported on Windows Embedded CE.
  • The WSCEnumerateProviders function returns the current catalog and not the catalog from the time the application was started.
  • LSPs have cooperative installers.

Best Practices for installing an LSP

For select to work with sockets of type TCP/IPv4, TCP/IPv6, UDP/IPv4, and UDP/IPv6 simultaneously, you must follow LSP installation guidelines.

By design, if you call select with sockets created by different provider chains, the call fails. However, using the Microsoft installed providers, Winsock determines that TCP/IPv4, TCP/IPv6, UDP/IPv4, and UDP/IPv6 are from the same provider because they are all handled by the same ProviderId.

Failure to follow the LSP installation guidelines results in unexpected errors because networking code often expects that select will not fail.

The following list shows the LSP installation guidelines you must follow:

  • If you install an LSP over TCP, you must also install it over UDP.
  • If you install an LSP for IPv4, you must also install it for IPv6
  • Use the same chain identifier (GUID) for each of these installations. For example, you should install an LSP over all chains of type TCPv4, TCPv6, UDPv4, and UDPv6 with the same GUID
  • Use a different chain identifier for all other installations.
  • On Windows Embedded CE, installing LSPs on demand must be avoided because changes in the LSP may not have been applied for all applications. Sockets that have already been opened will not use the new LSP. The LSP caches the catalog of installed services providers and any change that has been affected after bootup will only be visible to the LSP on the next reboot. For example, if a server application creates a socket, the socket will use the LSP that was installed at boot time. If the LSP is installed again, all new sockets that the application creates will use the new LSP. If the application calls the select function on these two sockets, then the call will fail because the sockets have two different providers.

Each service provider DLL should load itself. This is done by implementing the installation code in an exported DllRegisterServer function and then adding a new value to the registry to specify the load order. The following procedure explains how to install an LSP with each protocol loading itself.

To install the LSP

  1. Copy the LSP installation code into a DllRegisterServer function.

  2. Add a registry subkey to the HKEY_LOCAL_MACHINE\COMM\WS2\LSP registry key.

    Using the SSL LSP as an example, you would add the HKEY_LOCAL_MACHINE\Comm\WS2\LSP\SSL registry subkey .

  3. To this subkey, add the registry entries shown in the following table.

    Value: type Description

    Dll: REG_SZ

    No default. The name of the DLL to load.

    Order: DWORD

    Default is 0xffffffff. The order in which the LSP loads, relative to the other providers. The LSP with the lower value loads first.

    Entry: REG_SZ

    Default is DllRegisterServer. The DLL entry point for the installation function.

    Using the SSL LSP as an example, the following example shows the registry settings you would add:

    [HKEY_LOCAL_MACHINE\Comm\WS2\LSP\SSL]

        "Dll"="ssllsp.dll"

        "Flags"=dword:1

        "Order"=dword:200

  4. When Winsock loads, it enumerates all keys under the HKEY_LOCAL_MACHINE\COMM\WS2\LSP subkey. For each subkey that has a DLL property, it performs a LoadLibrary function call on the value in that property.

    If successful, Winsock calls the DLL entry point as specified in the Entry value.

    If a registry entry is not in the subkey, Winsock calls the default value for that entry.

See Also

Concepts

Multiple Transport Protocols