NPI_PROVIDER_ATTACH_CLIENT_FN callback function (netioddk.h)

  • Article

A provider module's ProviderAttachClient callback function attaches the provider module to a client module.

Syntax

NPI_PROVIDER_ATTACH_CLIENT_FN NpiProviderAttachClientFn;

NTSTATUS NpiProviderAttachClientFn(
  [in]  HANDLE NmrBindingHandle,
  [in]  PVOID ProviderContext,
  [in]  PNPI_REGISTRATION_INSTANCE ClientRegistrationInstance,
  [in]  PVOID ClientBindingContext,
  [in]  const VOID *ClientDispatch,
  [out] PVOID *ProviderBindingContext,
  [out] const VOID **ProviderDispatch
)
{...}

Parameters

[in] NmrBindingHandle

A handle used by the NMR to represent the binding between the client module and the provider module.

[in] ProviderContext

A pointer to the provider module's registration context. The provider module passes this pointer to the NMR when it calls the NmrRegisterProvider function to register itself with the NMR.

[in] ClientRegistrationInstance

A pointer to an NPI_REGISTRATION_INSTANCE structure. This structure contains the client module's registration data.

[in] ClientBindingContext

A pointer to the client module's context for the binding between the client module and the provider module. The client module uses this context to keep track of the state of the binding. The contents of the client module's binding context are opaque to the provider module. The provider module passes this pointer to the client module whenever it calls any of the client module's NPI callback functions that require the client module's binding context.

[in] ClientDispatch

A pointer to a constant structure that contains the dispatch table of NPI callback functions for the client module. The contents of the structure are NPI-specific. If the NPI does not define a client dispatch table structure, then this pointer is NULL.

[out] ProviderBindingContext

A pointer to a variable into which the provider module will store a pointer to its context for the binding between the client module and the provider module. The provider module uses this context to keep track of the state of the binding. The contents of the provider module's binding context are opaque to the client module. The client module passes this pointer to the provider module whenever it calls one of the provider module's NPI functions that require the provider module's binding context. The provider module must make sure that this context remains valid and resident in memory as long as the client module is attached to the provider module.

[out] ProviderDispatch

A pointer to a variable into which the provider module will store a pointer to a constant structure that contains the dispatch table of NPI functions for the provider module. The provider module must make sure that this structure remains valid and resident in memory as long as the client module is attached to the provider module. The contents of the structure are NPI-specific.

Return value

A provider module's ProviderAttachClient callback function returns one of the following NTSTATUS codes:

Return code Description
STATUS_SUCCESS
 The provider module successfully attached to the client module.
STATUS_NOINTERFACE
 The provider module did not attach to the client module.
Other status codes
 An error occurred.

Remarks

The NMR calls a provider module's ProviderAttachClient callback function whenever a client module calls the NmrClientAttachProvider function with a handle that represents a binding between the client module and the provider module.

A provider module can examine the client module's registration data. This data is in the structure pointed to by the ClientRegistrationInstance parameter. The provider module uses this data to determine whether it will attach to the client module:

  • If the provider module determines that it will attach to the client module, then the ProviderAttachClient callback function must do the following:
    1. Save the pointers passed in the ClientBindingContext and ClientDispatch parameters so that the provider module can make calls to the client module's NPI functions.
    2. Save the handle passed in the NmrBindingHandle parameter. The provider module passes this handle as a parameter to the NmrProviderDetachClientComplete function when it detaches from the client module.
    3. Set the ProviderBindingContext parameter to point to the provider module's binding context structure for the binding between the client module and the provider module.
    4. Set the ProviderDispatch parameter to point to a structure that contains the provider module's dispatch table of NPI functions.
    5. Return STATUS_SUCCESS.
  • If the provider module determines that it will not attach to the client module, then the ProviderAttachClient callback function must return STATUS_NOINTERFACE.
If the provider module attaches to the client module and it dynamically allocated memory for its binding context, it should free that allocated memory when the NMR calls the provider module's ProviderCleanupBindingContext callback function after the client module and provider module are detached from each other.

The NMR calls a provider module's ProviderAttachClient callback function at IRQL = PASSIVE_LEVEL.

Requirements

Requirement Value
Minimum supported client Available in Windows Vista and later versions of the Windows operating systems.
Target Platform Windows
Header netioddk.h (include Wsk.h)
IRQL PASSIVE_LEVEL

See also

NPI_PROVIDER_CHARACTERISTICS

NPI_REGISTRATION_INSTANCE

NmrClientAttachProvider

NmrProviderDetachClientComplete

NmrRegisterProvider

ProviderCleanupBindingContext

ProviderDetachClient