Função NetCreateProvisioningPackage (lmjoin.h)
A função NetCreateProvisioningPackage cria um pacote de provisionamento que provisiona uma conta de computador para uso posterior em uma operação de junção de domínio offline. O pacote também pode conter informações sobre certificados e políticas a serem adicionados ao computador durante o provisionamento.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
[in] PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
[out, optional] PBYTE *ppPackageBinData,
[out, optional] DWORD *pdwPackageBinDataSize,
[out, optional] LPWSTR *ppPackageTextData
);
Parâmetros
[in] pProvisioningParams
Um ponteiro para uma estrutura NETSETUP_PROVISIONING_PARAMS que contém informações sobre o pacote de provisionamento.
Os seguintes valores são definidos para os membros dessa estrutura:
| Valor | Significado |
|---|---|
|
A versão do Windows no pacote de provisionamento. Esse membro deve usar o seguinte valor definido no arquivo de cabeçalho Lmjoin.h : NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001) |
|
Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o nome do domínio em que a conta do computador é criada. |
|
Um ponteiro para uma cadeia de caracteres terminada em nulo constante que especifica o nome curto do computador do qual o atributo de conta de computador sAMAccountName é derivado acrescentando um '$'. Esse parâmetro deve conter um nome de computador DNS ou NetBIOS válido. |
|
Um ponteiro opcional para uma cadeia de caracteres terminada em nulo constante que contém o nome do formato RFC 1779 da UO (unidade organizacional) em que a conta de computador será criada. Se você especificar esse parâmetro, a cadeia de caracteres deverá conter um caminho completo, por exemplo, OU=testOU,DC=domain,DC=Domain,DC=com. Caso contrário, esse parâmetro deve ser NULL.
Se esse parâmetro for NULL, o contêiner de objeto de computador conhecido será usado conforme publicado no domínio. |
|
Um ponteiro opcional para uma cadeia de caracteres terminada em nulo constante que contém o nome do controlador de domínio a ser direcionado. |
|
Um conjunto de sinalizadores de bits que definem opções de provisionamento. Esse parâmetro pode ser um ou mais dos valores especificados para o parâmetro dwOptions passado para a função NetProvisionComputerAccount .
Esses valores possíveis são definidos no arquivo de cabeçalho Lmjoin.h . A opção NETSETUP_PROVISION_ROOT_CA_CERTS só tem suporte em Windows 8 e Windows Server 2012. |
|
Um ponteiro opcional para uma matriz de nomes de modelo de certificado terminados em NULL. |
|
Quando aCertTemplateNames não é NULL, esse membro fornece uma contagem explícita do número de itens na matriz. |
|
Um ponteiro opcional para uma matriz de nomes de política de computador terminados em NULL. |
|
Quando aMachinePolicyNames não é NULL, esse membro fornece uma contagem explícita do número de itens na matriz. |
|
Um ponteiro opcional para uma matriz de cadeias de caracteres. Cada elemento de matriz é uma cadeia de caracteres terminada em NULL que especifica o caminho completo ou parcial para um arquivo no formato Arquivo de Política do Registro. Para obter mais informações sobre o formato de arquivo de política do registro, consulte Formato de arquivo de política do registro
O caminho pode ser um caminho UNC em um servidor remoto. |
|
Quando aMachinePolicyPaths não é NULL, esse membro fornece uma contagem explícita do número de itens na matriz. |
[out, optional] ppPackageBinData
Um ponteiro opcional que receberá o pacote exigido pela função NetRequestOfflineDomainJoin para concluir uma junção de domínio offline, se a função NetProvisionComputerAccount for concluída com êxito. Os dados são retornados como um buffer binário opaco que pode ser passado para a função NetRequestOfflineDomainJoin .
Se esse parâmetro for NULL, o parâmetro pPackageTextData não deverá ser NULL. Se esse parâmetro não for NULL, o parâmetro pPackageTextData deverá ser NULL.
[out, optional] pdwPackageBinDataSize
Um ponteiro para um valor que recebe o tamanho, em bytes, do buffer retornado no parâmetro pProvisionBinData .
Esse parâmetro não deverá ser NULL se o parâmetro pPackageBinData não for NULL. Esse parâmetro deve ser NULL quando o parâmetro pPackageBinData for NULL.
[out, optional] ppPackageTextData
Um ponteiro opcional que receberá o pacote exigido pela função NetRequestOfflineDomainJoin para concluir uma junção de domínio offline, se a função NetProvisionComputerAccount for concluída com êxito. Os dados são retornados no formulário de cadeia de caracteres para inserção em um arquivo de resposta de instalação autônoma.
Se esse parâmetro for NULL, o parâmetro pPackageBinData não deverá ser NULL. Se esse parâmetro não for NULL, o parâmetro pPackageBinData deverá ser NULL.
Retornar valor
Se a função for bem-sucedida, o valor retornado será NERR_Success.
Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro ou um dos códigos de erro do sistema.
| Código de retorno | Descrição |
|---|---|
|
Acesso negado. Esse erro será retornado se o chamador não tiver privilégios suficientes para concluir a operação. |
|
Esta operação só é permitida para o Controlador de Domínio Primário do domínio. Esse erro será retornado se um nome de controlador de domínio tiver sido especificado no lpDcName do struct NETSETUP_PROVISIONING_PARAMS apontado pelo parâmetro pProvisioningParams , mas o computador especificado não pôde ser validado como um controlador de domínio para o domínio de destino especificado no lpDomain do NETSETUP_PROVISIONING_PARAMS. |
|
Um parâmetro está incorreto. Esse erro também será retornado se o parâmetro pProvisioningParams for NULL. Esse erro também será retornado se o lpDomain ou lpMachineName membro do struct NETSETUP_PROVISIONING_PARAMS apontado pelo parâmetro pProvisioningParams for NULL. |
|
O domínio especificado não existia. |
|
A solicitação não terá suporte. Esse erro será retornado se o membro lpMachineAccountOU tiver sido especificado no struct NETSETUP_PROVISIONING_PARAMS apontado pelo parâmetro pProvisioningParams e o controlador de domínio estiver em execução em versões anteriores do Windows que não dão suporte a esse parâmetro. |
|
O controlador de domínio especificado não atende ao requisito de versão para essa operação. |
|
Essa operação requer um controlador de domínio que dê suporte a LDAP. |
|
A conta já existe no domínio e o bit NETSETUP_PROVISION_REUSE_ACCOUNT não foi especificado no membro dwProvisionOptions do struct NETSETUP_PROVISIONING_PARAMS apontado pelo parâmetro pProvisioningParams . |
|
O serviço estação de trabalho não foi iniciado. |
|
Uma chamada de procedimento remoto já está em andamento para esse thread. |
|
Não há suporte para a sequência de protocolo de chamada de procedimento remoto. |
Comentários
A função NetCreateProvisioningPackage tem suporte em Windows 8 e Windows Server 2012 para operações de junção offline. Para o Windows 7, use a função NetProvisionComputerAccount .
A função NetCreateProvisioningPackage é usada para provisionar uma conta de computador para uso posterior em uma operação de junção de domínio offline usando a função NetRequestProvisioningPackageInstall .
O cenário de junção de domínio offline usa duas funções:
- NetCreateProvisioningPackage é uma função de provisionamento que é chamada primeiro para executar as operações de rede necessárias para criar e configurar o objeto de computador no Active Directory. A saída do NetCreateProvisioningPackage é um pacote usado para a próxima etapa.
- NetRequestProvisioningPackageInstall, uma função de inicialização de imagem, é chamada para injetar a saída da função de provisionamento NetCreateProvisioningPackage em uma imagem do sistema operacional Windows para uso durante a pré-instalação e pós-instalação.
Quando os ponteiros pPackageBinData e pdwPackageBinDataSize forem usados, defina o ponteiro pPackageTextData como NULL. Quando pPackageTextData for usado, defina os ponteiros pPackageBinData e pdwPackageBinDataSize como NULL.
O parâmetro pProvisioningParams especifica os dados a serem incluídos no pacote de provisionamento. O pacote inclui informações relevantes para o ingresso no domínio e também pode incluir informações sobre políticas e certificados a serem instalados no computador. O pacote de provisionamento pode ser usado de quatro maneiras:
- Ingresso no domínio
- Ingresso no domínio e instalação de certificados
- Ingresso no domínio e instalação de políticas
- Ingresso no domínio e instalação de certificados e políticas
A função NetCreateProvisioningPackage cria ou reutiliza a conta do computador no domínio, coleta todos os metadados necessários e a retorna em um pacote. O pacote pode ser consumido pela operação de solicitação de ingresso no domínio offline que fornece toda a entrada necessária para concluir a junção de domínio durante a primeira inicialização sem nenhuma operação de rede (somente atualizações de estado local).
Observação de segurança: O pacote retornado pela função NetCreateProvisioningPackage contém dados muito confidenciais. Ele deve ser tratado com a mesma segurança que uma senha de texto não criptografado. O pacote contém a senha da conta do computador e outras informações sobre o domínio, incluindo o nome de domínio, o nome de um controlador de domínio e a ID de segurança (SID) do domínio. Se o pacote estiver sendo transportado fisicamente ou pela rede, deve-se tomar cuidado para transportá-lo com segurança. O design não faz nenhuma provisão para proteger esses dados. Esse problema existe hoje com arquivos de resposta de instalação autônoma que podem conter vários segredos, incluindo senhas de usuário de domínio. O chamador deve proteger o pacote. As soluções para esse problema são variadas. Por exemplo, uma chave pré-trocada pode ser usada para criptografar uma sessão entre o consumidor e a entidade de provisionamento, permitindo uma transferência segura do pacote.
O pacote retornado no parâmetro pPackageBinData pela função NetCreateProvisioningPackage tem controle de versão para permitir cenários de interoperabilidade e de serviço entre diferentes versões do Windows (como ingressar em um cliente, provisionar um computador e usar um controlador de domínio). Um pacote criado em Windows 8 ou Windows Server 2012 pode ser usado windows 7 ou Windows Server 2008 R2, no entanto, somente as informações de ingresso no domínio entrarão em vigor (certificados e políticas não têm suporte). O cenário de junção offline atualmente não limita o tempo de vida do pacote retornado pela função NetCreateProvisioningPackage .
Para junções de domínio offline, o acesso marcar executado depende da configuração do domínio. A criação de conta de computador está habilitada usando três métodos:
- Os administradores de domínio têm direitos para criar contas de computador.
- O SD em um contêiner pode delegar os direitos para criar contas de computador.
- Por padrão, os usuários autenticados podem criar contas de computador por privilégio. Os usuários autenticados estão limitados à criação de um número limitado de contas especificadas como uma cota no domínio (o valor padrão é 10). Para obter mais informações, consulte o atributo ms-DS-MachineAccountQuota no esquema do Active Directory.
A função NetCreateProvisioningPackage funciona apenas com um controlador de domínio gravável e não funciona em um controlador de domínio somente leitura. Depois que o provisionamento é feito em um controlador de domínio gravável e a conta é replicada para um controlador de domínio somente leitura, as outras partes da operação de ingresso no domínio offline não exigem acesso a um controlador de domínio.
Se a função NetCreateProvisioningPackage for bem-sucedida, o ponteiro no parâmetro pPackageBinData ou pPackageTextData (dependendo de qual parâmetro não era NULL) será retornado com os dados serializados para uso em uma operação de junção offline ou como texto em um arquivo de instalação autônoma.
Todas as fases do processo de provisionamento acrescentam a um arquivo NetSetup.log no computador local. O processo de provisionamento pode incluir até três computadores diferentes: o computador em que o pacote de provisionamento é criado, o computador que solicita a instalação do pacote e o computador em que o pacote está instalado. Haverá NetSetup.log informações de arquivo armazenadas nos três computadores de acordo com a operação executada. A revisão do conteúdo desses arquivos é o meio mais comum de solucionar problemas de erros de provisionamento online e offline. As operações de provisionamento realizadas pelos administradores são registradas no arquivo NetSetup.log no %WINDIR%\Debug. As operações de provisionamento executadas por não administradores são registradas no arquivo NetSetup.log na pasta %USERPROFILE%\Debug .
Para obter mais informações sobre operações de ingresso no domínio offline, consulte o Guia passo a passo de ingresso no domínio offline.
A junção (e desassociamento) de um computador a um domínio usando NetJoinDomain e NetUnjoinDomain é executada somente por um membro do grupo local Administradores no computador de destino. Observe que o administrador de domínio pode definir requisitos adicionais para ingressar no domínio usando delegação e atribuição de privilégios.
Requisitos
| Cliente mínimo com suporte | Windows 8 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2012 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | lmjoin.h (inclua Lm.h) |
| Biblioteca | Netapi32.lib |
| DLL | Netapi32.dll |
Confira também
NetRequestProvisioningPackageInstall
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de