This function is used to log the user on to this network. The NP may use the provided user name and password as defaults, obtain them and additional logon information from the password cache subsystem, or display a dialog box to the user. Displaying a dialog box is not recommended, since if multiple networks are loaded, the logon process could become quite lengthy.
NPLogon is actually called twice, once to log the user on to the network and once to indicate that the logon process is complete. NPs may use the two calls to maintain internal state in order to control different behavior during the course of a logon. Persistent connections are restored after the initial NPLogon call and before the corresponding call with the LOGON_DONE flag. If an NP does not maintain internal state in this way, it should ignore the call that has the LOGON_DONE flag set.
The user may have a User Profile (per-user portion of the registry) stored on a network server. Since logon to that network is probably necessary to gain access to that profile, the NP for that network may be designated the Primary Logon Provider (PLP). This NP's NPLogon entrypoint is called before the user profile is loaded, and is passed the LOGON_PRIMARY flag. The PLP is responsible for displaying the main logon dialog box, possibly with customizations such as a domain or server to log in to. When the user successfully logs on, the PLP should return the user name and password that the user typed into the dialog box in the lpUsername and lpPassword buffers of the LOGONINFO structure.
Because the system does not maintain logon state, this function may be called when the user is already logged on (for example, when the user inserts a removable network card). In this case, the provider should perform any logon operations necessary for the additional media. If all necessary logon operations have already been performed for an existing network adapter, the provider may simply return WN_SUCCESS. In these extra logon requests, the LOGON_PRIMARY flag will never be set. There will still be two notifications, one without LOGON_DONE and one with.
The provider should also check to see whether it is running on any active networks before taking any action. If no network adapters or other media are available, the provider should return WN_NO_NETWORK without displaying any UI. This way, the user will not receive a network logon dialog box when not connected to a network.