========================================================================
       Windows Deployment Services PXE Provider DLL : Filter Provider
========================================================================


The Windows Deployment Services PXE Server implementation can be
subdivided into two pieces  a PXE Server and a PXE Provider. The PXE
Server contains the core networking capability of the server solution.
The PXE Server supports a plug-in interface. Plug-ins are also known as
PXE Providers. The provider model allows for custom PXE solutions to
be developed while leveraging the same core PXE Server networking code
base. This sample provider allows you to create a DLL that may replace
or run in conjunction with the existing PXE Provider, WDSDCPXE, on a
Windows Deployment Services server. The sample provider uses a text file
as its data store.

This sample consists of a filter provider that illustrates how to create
an additional PXE Provider that sits before WDSDCPXE (or any other PXE
Provider) in the ordered provider list. This filter provider acts as a
gate before the next provider in the list, allowing the next provider
to service selected clients and filtering out others.

This sample consists of the following files -

FilterProv.cpp
    This is the main DLL source file.  It contains implementations for
    all required resource DLL entry points along with some helper
    functions.

FilterProv.h
    Required header file that defines helper data structures.

FilterProv.sln
    This is the solution file which should be loaded into Visual Studio
    to generate the executable for this sample.

FilterProv.vcxproj
    This is a Visual Studio file which contains information about the
    version of Visual Studio that generated the file, and information
    about the platforms, configurations, and project features.

FilterProv.def
    This file contains information about the DLL that must be provided
    to run with the Windows Deployment Services PXE Server software. It
    defines parameters such as the name and description of the DLL. It
    also exports functions from the DLL.

/////////////////////////////////////////////////////////////////////////////
Registering a Provider:

Registration of the sample provider requires two steps:
1. Create a registry key that represents your provider
    a. Create a new key at
           HKLM\System\CurrentControlSet\Services\WDSServer\Providers\WDSPXE\Providers
    b. Create a new value under this key that specifies the name of
       your provider DLL 
        TYPE=REG_SZ
        NAME=ProviderDLL
        VALUE=<full path and .DLL name of your custom provider>
2. Specify the order of your provider.
    a. Modify the key at
           HKLM\System\CurrentControlSet\Services\WDSServer\Providers\WDSPXE
        TYPE=REG_MULTI_SZ
        NAME=ProvidersOrder
        VALUE=<name of key created in 1a. above>

The Windows Deployment Services PXE Server passes incoming PXE requests
to the registered providers as ordered in this registry key. If you
would like your provider to always have the first opportunity to answer
an incoming PXE request, you should place it first in the list.

/////////////////////////////////////////////////////////////////////////////
Configuration File:

The sample code must be compiled into .dll form, e.g. filterprov.dll. The
filter provider uses a configuration file that must be named
filterprov.dll.filter.ini, and placed in the same directory as the .dll.

The .ini file has two sections  [Configuration] and [Devices]. The
[Configuration] section has one key, Policy, which defines whether
unknown devices will continue to the next provider in the ordered list
or not. The Policy key has two values 

0 = Deny. Means that all unknown devices (those not existing in the
          [Devices] section) will be denied PXE service by the sample
          provider. The net effect is that the PXE request will not be
          answered and the request will not be forwarded to the next PXE
          Provider in the ordered list.

1 = Allow. Means that all unknown devices (those not existing in the
           [Devices] section) will be allowed PXE service by the sample
           provider. The net effect is that the PXE request will be
           forwarded on to the next PXE Provider in the ordered list.


The [Devices] section lists all known devices. Devices must be listed
by MAC address and the value must be 32 characters in length (MAC address
prepended with 20 0s). For each device one can specify the desired
action Deny or Allow. Deny means that the sample provider will deny the
PXE request and will not forward the request to the next PXE Provider in
the ordered list. Allow means that the sample provider will forward on the
PXE request to the next PXE Provider in the ordered list. It is then up to
that next provider to service the incoming PXE request.


    [Configuration]
    Policy = [0  Deny | 1  Allow]

    [Devices]
    00000000000000000000FFEEDDCCBBAA=[0  Deny | 1  Allow]


The simple walkthrough of using the sample filter provider looks as follows:

1. Compile the sample code into a .dll
2. Create a .ini file per above
3. Register the sample provider as first in the ordered provider list
4. PXE boot a sample client. The following logic is used
    a. PXE Server hands the request off to the first provider in the
       ordered list. This should be the sample provider per #3 above.
    b. The sample provider looks for the booting device in the [Devices]
       section of the file. If it finds it, whatever policy is specified
       will be followed.
    c. The sample provider looks for the Policy value in the
       [Configuration] section of the file. Whatever policy specified
       will be followed.
5. Any requests not filtered by the sample provider will then be passed to
   the next registered provider in the ordered list


Example that will let only the specified devices go to the next provider:
[Configuration]
Policy = 0

[Devices]
00000000000000000000FFEEDDCCBBAA=1
000000000000000000001234567890AB=1


Example that will deny service to the specified devices:
[Configuration]
Policy = 1

[Devices]
00000000000000000000FFEEDDCCBBAA=0
000000000000000000001234567890AB=0

/////////////////////////////////////////////////////////////////////////////
