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

Artigo
08/07/2023

A função de retorno de chamada 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 do 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 retorno de chamada NPI 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 funções de retorno de chamada NPI 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 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 residente 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 funções NPI para o módulo do provedor. O módulo do provedor deve garantir que essa estrutura permaneça válida e residente 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.

Retornar valor

A função de retorno de chamada 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 status	Ocorreu um erro.

Comentários

A NMR chama a função de retorno de chamada 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 do 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 do cliente:

Se o módulo do provedor determinar que ele será anexado ao módulo cliente, a função de retorno de chamada ProviderAttachClient 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 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 é desanexada 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 de funções NPI do módulo do provedor.
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 se anexar ao módulo cliente e 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 provedorFunção de retorno de chamada ProviderCleanupBindingContext depois que o módulo cliente e o módulo do provedor são desanexados um do outro.

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

Requisitos

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