Função RpcNsBindingImportNext (rpcnsi.h)

Artigo
08/25/2023

A função RpcNsBindingImportNext pesquisa uma interface (e, opcionalmente, um objeto de um banco de dados name-service) e retorna um identificador de associação de um servidor compatível, se encontrado.

Nota Essa função não tem suporte no Windows Vista e em sistemas operacionais posteriores.

Sintaxe

RPC_STATUS RpcNsBindingImportNext(
  RPC_NS_HANDLE      ImportContext,
  RPC_BINDING_HANDLE *Binding
);

Parâmetros

ImportContext

Identificador nome-serviço retornado da função RpcNsBindingImportBegin .

Binding

Retorna um ponteiro para um identificador de associação de servidor compatível com o cliente para um servidor.

Valor retornado

Valor	Significado
RPC_S_OK	A chamada foi bem-sucedida.
RPC_S_NO_MORE_BINDINGS	Não há mais associações.
RPC_S_NAME_SERVICE_UNAVAILABLE	O serviço de nome está indisponível.

Nota Para obter uma lista de códigos de erro válidos, consulte RPC Return Values.

Comentários

A função RpcNsBindingImportNext retorna um identificador de associação de servidor compatível com o cliente para um servidor que oferece a interface e o objeto UUID especificados pelos parâmetros IfSpec e ObjUuid na função RpcNsBindingImportBegin . A função se comunica apenas com o banco de dados name-service, não diretamente com servidores.

Em vigor com o Windows 2000, o ambiente RPC usa o Active Directory como seu banco de dados name-service e a ordem na qual o ambiente de tempo de execução executa a pesquisa é a seguinte:

Pesquise no cache local. Se não houver nenhuma entrada,
Pesquise no Active Directory. Se não houver nenhuma entrada,
Envie solicitações de transmissão para todos os outros serviços de diretório no domínio.
Observe que, se a entrada existir no Active Directory, mas não houver informações associadas à entrada, o ambiente de tempo de execução não emitirá essa solicitação de transmissão.

O identificador de associação compatível retornado sempre contém um UUID de objeto, cujo valor depende do parâmetro ObjUuid na função RpcNsBindingImportBegin . Se um UUID de objeto não nulo tiver sido especificado, o identificador de associação retornado conterá esse objeto UUID. Se, no entanto, um objeto nulo UUID ou valor nulo tiver sido especificado, o UUID do objeto retornado será resultado das seguintes possibilidades:

Se o servidor não exportar UUIDs de objeto, o identificador de associação retornado conterá um UUID de objeto nulo.
Se o servidor exportou um objeto UUID, o identificador de associação retornado contém esse objeto UUID.
Se o servidor exportou vários UUIDs de objeto, o identificador de associação retornado conterá um dos UUIDs do objeto. A operação import-next seleciona o UUID do objeto retornado de forma não determinística. Como resultado, um UUID de objeto diferente pode ser retornado para cada identificador de associação compatível de uma única entrada de servidor.

A função RpcNsBindingImportNext seleciona e retorna um identificador de associação de servidor dos identificadores de associação compatíveis encontrados. O aplicativo cliente pode usar esse identificador de associação para tentar uma chamada de procedimento remoto para o servidor. Se o cliente não estabelecer uma relação com o servidor, ele poderá chamar RpcNsBindingImportNext novamente.

Sempre que o cliente chama RpcNsBindingImportNext, a função retorna outro identificador de associação de servidor. Os identificadores de associação retornados não são ordenados. Um aplicativo cliente chama a função RpcNsBindingInqEntryName para obter o banco de dados name-service no nome de entrada do qual o identificador de associação veio. Quando a pesquisa atinge o final do banco de dados name-service, RpcNsBindingInqEntryName retorna uma status de RPC_S_NO_MORE_BINDINGS e retorna um valor de parâmetro de associação NULL.

A função RpcNsBindingImportNext aloca armazenamento para os dados referenciados pelo parâmetro Binding retornado. Quando um aplicativo cliente termina com o identificador de associação, ele deve chamar RpcBindingFree para desalocar o armazenamento. Cada chamada para RpcNsBindingImportNext requer uma chamada correspondente para RpcBindingFree.

O cliente é responsável por chamar a função RpcNsBindingImportDone , que exclui o contexto de importação. O cliente também chama RpcNsBindingImportDone antes de chamar RpcNsBindingImportBegin para iniciar uma nova pesquisa por servidores compatíveis. Como a ordem dos identificadores de associação retornados é diferente para cada nova pesquisa, a ordem na qual os identificadores de associação são retornados a um aplicativo pode ser diferente sempre que o aplicativo é executado.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	rpcnsi.h (inclua Rpc.h)
Biblioteca	Rpcns4.lib
DLL	Rpcns4.dll