NPI_PROVIDER_ATTACH_CLIENT_FN função de retorno de chamada (netioddk.h)

Artigo
02/07/2025

A função ProviderAttachClient de um módulo de provedor anexa o módulo do provedor a um módulo cliente.

Sintaxe

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
)
{...}

Parâmetros

[in] NmrBindingHandle

Um identificador usado pela NMR para representar a associação entre o módulo cliente e o módulo do provedor.

[in] ProviderContext

Um ponteiro para o contexto de registro do módulo do provedor. O módulo do provedor passa esse ponteiro para a NMR quando chama a função NmrRegisterProvider para se registrar na NMR.

[in] ClientRegistrationInstance

Um ponteiro para um NPI_REGISTRATION_INSTANCE estrutura. Essa estrutura contém os dados de registro do módulo cliente.

[in] ClientBindingContext

Um ponteiro para o contexto do módulo cliente para a associação entre o módulo cliente e o módulo do provedor. O módulo cliente usa esse contexto para acompanhar o estado da associação. O conteúdo do contexto de associação do módulo cliente é opaco para o módulo do provedor. O módulo do provedor passa esse ponteiro para o módulo cliente sempre que ele chama qualquer uma das funções de NPI de retorno de chamada do módulo cliente que exigem o contexto de associação do módulo cliente.

[in] ClientDispatch

Um ponteiro para uma estrutura constante que contém a tabela de expedição de NPI funções de retorno de chamada para o módulo cliente. O conteúdo da estrutura é específico de NPI. Se a NPI não definir uma estrutura de tabela de expedição do cliente, esse ponteiro será NULL.

[out] ProviderBindingContext

Um ponteiro para uma variável na qual o módulo do provedor armazenará um ponteiro para seu contexto para a associação entre o módulo cliente e o módulo do provedor. O módulo do provedor usa esse contexto para acompanhar o estado da associação. O conteúdo do contexto de associação do módulo do provedor é opaco para o módulo cliente. O módulo cliente passa esse ponteiro para o módulo do provedor sempre que ele chama uma das funções de de NPI do módulo do provedor que exigem o contexto de associação do módulo do provedor. O módulo do provedor deve garantir que esse contexto permaneça válido e resida na memória, desde que o módulo cliente esteja anexado ao módulo do provedor.

[out] ProviderDispatch

Um ponteiro para uma variável na qual o módulo do provedor armazenará um ponteiro para uma estrutura constante que contém a tabela de expedição de NPI funções para o módulo do provedor. O módulo do provedor deve garantir que essa estrutura permaneça válida e resida na memória, desde que o módulo cliente esteja anexado ao módulo do provedor. O conteúdo da estrutura é específico de NPI.

Valor de retorno

A função ProviderAttachClient de um módulo de provedor retorna um dos seguintes códigos NTSTATUS:

Código de retorno	Descrição
STATUS_SUCCESS	O módulo do provedor anexado com êxito ao módulo cliente.
STATUS_NOINTERFACE	O módulo do provedor não foi anexado ao módulo cliente.
Outros códigos de status	Ocorreu um erro.

Observações

O NMR chama a função ProviderAttachClient de um módulo de provedor sempre que um módulo cliente chama a função NmrClientAttachProvider com um identificador que representa uma associação entre o módulo cliente e o módulo do provedor.

Um módulo de provedor pode examinar os dados de registro do módulo cliente. Esses dados estão na estrutura apontada pelo parâmetro ClientRegistrationInstance. O módulo do provedor usa esses dados para determinar se ele será anexado ao módulo cliente:

Se o módulo do provedor determinar que ele será anexado ao módulo cliente, a função ProviderAttachClient de retorno de chamada deverá fazer o seguinte:
1. Salve os ponteiros passados nos parâmetros ClientBindingContext e ClientDispatch para que o módulo do provedor possa fazer chamadas para as funções de de NPI do módulo cliente.
2. Salve o identificador passado no parâmetro NmrBindingHandle. O módulo do provedor passa esse identificador como um parâmetro para o função NmrProviderDetachClientComplete quando ela se desanexa do módulo cliente.
3. Defina o parâmetro ProviderBindingContext para apontar para a estrutura de contexto de associação do módulo do provedor para a associação entre o módulo cliente e o módulo do provedor.
4. Defina o parâmetro ProviderDispatch para apontar para uma estrutura que contém a tabela de expedição do módulo de provedor de funções de NPI.
5. Retornar STATUS_SUCCESS.
Se o módulo do provedor determinar que ele não será anexado ao módulo cliente, a função de retorno de chamada ProviderAttachClient deverá retornar STATUS_NOINTERFACE.

Se o módulo do provedor for anexado ao módulo cliente e ele alocar dinamicamente memória para seu contexto de associação, ele deverá liberar essa memória alocada quando o NMR chamar o módulo do provedor ProviderCleanupBindingContext função de retorno de chamada depois que o módulo cliente e o módulo do provedor são desanexados uns dos outros.

A NMR chama a função de retorno de chamada ProviderAttachClient de um módulo de provedor no IRQL = PASSIVE_LEVEL.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows.
da Plataforma de Destino	Windows
cabeçalho	netioddk.h (inclua Wsk.h)
IRQL	PASSIVE_LEVEL