Función NetCreateProvisioningPackage (lmjoin.h)
La función NetCreateProvisioningPackage crea un paquete de aprovisionamiento que aprovisiona una cuenta de equipo para su uso posterior en una operación de unión a un dominio sin conexión. El paquete también puede contener información sobre los certificados y las directivas que se van a agregar a la máquina durante el aprovisionamiento.
Sintaxis
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
Puntero a una estructura de NETSETUP_PROVISIONING_PARAMS que contiene información sobre el paquete de aprovisionamiento.
Los valores siguientes se definen para los miembros de esta estructura:
| Valor | Significado |
|---|---|
|
Versión de Windows en el paquete de aprovisionamiento. Este miembro debe usar el siguiente valor definido en el archivo de encabezado Lmjoin.h : NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001) |
|
Puntero a una cadena de caracteres terminada en NULL constante que especifica el nombre del dominio donde se crea la cuenta de equipo. |
|
Puntero a una cadena de caracteres terminada en null constante que especifica el nombre corto de la máquina desde la que se deriva el atributo de cuenta de equipo sAMAccountName anexando "$". Este parámetro debe contener un nombre de equipo DNS o NetBIOS válido. |
|
Puntero opcional a una cadena de caracteres terminada en null constante que contiene el nombre de formato RFC 1779 de la unidad organizativa (OU) donde se creará la cuenta de equipo. Si especifica este parámetro, la cadena debe contener una ruta de acceso completa, por ejemplo, OU=testOU,DC=domain,DC=Domain,DC=com. De lo contrario, este parámetro debe ser NULL.
Si este parámetro es NULL, el contenedor de objetos de equipo conocido se usará como publicado en el dominio. |
|
Puntero opcional a una cadena de caracteres terminada en NULL constante que contiene el nombre del controlador de dominio que se va a seleccionar como destino. |
|
Conjunto de marcas de bits que definen las opciones de aprovisionamiento. Este parámetro puede ser uno o varios de los valores especificados para el parámetro dwOptions pasado a la función NetProvisionComputerAccount .
Estos valores posibles se definen en el archivo de encabezado Lmjoin.h . La opción NETSETUP_PROVISION_ROOT_CA_CERTS solo se admite en Windows 8 y Windows Server 2012. |
|
Puntero opcional a una matriz de nombres de plantilla de certificado terminadas en NULL. |
|
Cuando aCertTemplateNames no es NULL, este miembro proporciona un recuento explícito del número de elementos de la matriz. |
|
Puntero opcional a una matriz de nombres de directiva de máquina terminadas en NULL. |
|
Cuando aMachinePolicyNames no es NULL, este miembro proporciona un recuento explícito del número de elementos de la matriz. |
|
Puntero opcional a una matriz de cadenas de caracteres. Cada elemento de matriz es una cadena de caracteres terminada en NULL que especifica la ruta de acceso completa o parcial a un archivo en el formato de archivo de directiva del Registro. Para obtener más información sobre el formato de archivo de directiva del Registro, vea Formato de archivo de directiva del Registro.
La ruta de acceso podría ser una ruta de acceso UNC en un servidor remoto. |
|
Cuando aMachinePolicyPaths no es NULL, este miembro proporciona un recuento explícito del número de elementos de la matriz. |
[out, optional] ppPackageBinData
Puntero opcional que recibirá el paquete requerido por la función NetRequestOfflineDomainJoin para completar una unión a un dominio sin conexión, si la función NetProvisionComputerAccount se completa correctamente. Los datos se devuelven como un búfer binario opaco que se puede pasar a la función NetRequestOfflineDomainJoin .
Si este parámetro es NULL, el parámetro pPackageTextData no debe ser NULL. Si este parámetro no es NULL, el parámetro pPackageTextData debe ser NULL.
[out, optional] pdwPackageBinDataSize
Puntero a un valor que recibe el tamaño, en bytes, del búfer devuelto en el parámetro pProvisionBinData .
Este parámetro no debe ser NULL si el parámetro pPackageBinData no es NULL. Este parámetro debe ser NULL cuando el parámetro pPackageBinData es NULL.
[out, optional] ppPackageTextData
Puntero opcional que recibirá el paquete requerido por la función NetRequestOfflineDomainJoin para completar una unión a un dominio sin conexión, si la función NetProvisionComputerAccount se completa correctamente. Los datos se devuelven en forma de cadena para insertarlos en un archivo de respuesta de instalación desatendida.
Si este parámetro es NULL, el parámetro pPackageBinData no debe ser NULL. Si este parámetro no es NULL, el parámetro pPackageBinData debe ser NULL.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto se NERR_Success.
Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error o uno de los códigos de error del sistema.
| Código devuelto | Descripción |
|---|---|
|
Acceso denegado. Este error se devuelve si el autor de la llamada no tiene suficientes privilegios para completar la operación. |
|
Esta operación solo está disponible para el controlador de dominio principal del dominio. Este error se devuelve si se especificó un nombre de controlador de dominio en el lpDcName del NETSETUP_PROVISIONING_PARAMS struct al que apunta el parámetro pProvisioningParams , pero el equipo especificado no se pudo validar como controlador de dominio para el dominio de destino especificado en el lpDomain del NETSETUP_PROVISIONING_PARAMS. |
|
Un parámetro es incorrecto. Este error también se devuelve si el parámetro pProvisioningParams es NULL. Este error también se devuelve si el miembro lpDomain o lpMachineName del NETSETUP_PROVISIONING_PARAMS struct al que apunta el parámetro pProvisioningParams es NULL. |
|
El dominio especificado no existía. |
|
No se admite la solicitud. Este error se devuelve si el miembro lpMachineAccountOU se especificó en la estructura de NETSETUP_PROVISIONING_PARAMS a la que apunta el parámetro pProvisioningParams y el controlador de dominio se ejecuta en una versión anterior de Windows que no admite este parámetro. |
|
El controlador de dominio especificado no cumple el requisito de versión de esta operación. |
|
Esta operación requiere un controlador de dominio que admita LDAP. |
|
La cuenta ya existe en el dominio y el bit de NETSETUP_PROVISION_REUSE_ACCOUNT no se especificó en el miembro dwProvisionOptions del NETSETUP_PROVISIONING_PARAMS struct al que apunta el parámetro pProvisioningParams . |
|
No se ha iniciado el servicio Workstation. |
|
Ya hay una llamada a procedimiento remoto en curso para este subproceso. |
|
No se admite la secuencia de protocolo de llamada a procedimiento remoto. |
Comentarios
La función NetCreateProvisioningPackage se admite en Windows 8 y Windows Server 2012 para las operaciones de unión sin conexión. Para Windows 7, use la función NetProvisionComputerAccount .
La función NetCreateProvisioningPackage se usa para aprovisionar una cuenta de equipo para su uso posterior en una operación de unión a un dominio sin conexión mediante la función NetRequestProvisioningPackageInstall .
El escenario de unión a un dominio sin conexión usa dos funciones:
- NetCreateProvisioningPackage es una función de aprovisionamiento a la que se llama primero para realizar las operaciones de red necesarias para crear y configurar el objeto de equipo en Active Directory. La salida de NetCreateProvisioningPackage es un paquete que se usa para el paso siguiente.
- NetRequestProvisioningPackageInstall, una función de inicialización de imagen, se llama para insertar la salida de la función de aprovisionamiento NetCreateProvisioningPackage en una imagen de sistema operativo Windows para su uso durante la instalación previa y posterior a la instalación.
Cuando se usan los punteros de salida pPackageBinData y pdwPackageBinDataSize , establezca el puntero de salida pPackageTextData en NULL. Cuando se usa pPackageTextData , establezca los punteros de salida pPackageBinData y pdwPackageBinDataSize en NULL.
El parámetro pProvisioningParams especifica los datos que se van a incluir en el paquete de aprovisionamiento. El paquete incluye información relevante para la unión a un dominio y también puede incluir información sobre las directivas y los certificados que se van a instalar en el equipo. El paquete de aprovisionamiento se puede usar de cuatro maneras:
- Unión a un dominio
- Unión a un dominio e instalación de certificados
- Unión a un dominio e instalación de directivas
- Unión a un dominio e instalación de certificados y directivas
La función NetCreateProvisioningPackage crea o reutiliza la cuenta de máquina en el dominio, recopila todos los metadatos necesarios y los devuelve en un paquete. La operación de solicitud de unión a un dominio sin conexión puede consumir el paquete que proporciona toda la entrada necesaria para completar la unión al dominio durante el primer arranque sin ninguna operación de red (solo actualizaciones de estado local).
Nota de seguridad: El paquete devuelto por la función NetCreateProvisioningPackage contiene datos muy confidenciales. Debe tratarse de forma tan segura como una contraseña de texto no cifrado. El paquete contiene la contraseña de la cuenta de máquina y otra información sobre el dominio, incluido el nombre de dominio, el nombre de un controlador de dominio y el identificador de seguridad (SID) del dominio. Si el paquete se transporta físicamente o a través de la red, se debe tener cuidado para transportarlo de forma segura. El diseño no hace ninguna disposición para proteger estos datos. Este problema existe hoy en día con archivos de respuesta de instalación desatendida que pueden llevar varios secretos, incluidas las contraseñas de usuario de dominio. El autor de la llamada debe proteger el paquete. Las soluciones a este problema son variadas. Por ejemplo, se podría usar una clave intercambiada previamente para cifrar una sesión entre el consumidor y la entidad de aprovisionamiento, lo que permite una transferencia segura del paquete.
El paquete devuelto en el parámetro pPackageBinData por la función NetCreateProvisioningPackage tiene versiones para permitir escenarios de interoperabilidad y capacidad de servicio entre diferentes versiones de Windows (como unir un cliente, aprovisionar una máquina y usar un controlador de dominio). Un paquete creado en Windows 8 o Windows Server 2012 se puede usar Windows 7 o Windows Server 2008 R2, pero solo la información de unión a un dominio surtirá efecto (no se admiten certificados y directivas). Actualmente, el escenario de combinación sin conexión no limita la duración del paquete devuelto por la función NetCreateProvisioningPackage .
Para las combinaciones de dominio sin conexión, la comprobación de acceso realizada depende de la configuración del dominio. La creación de cuentas de equipo está habilitada con tres métodos:
- Los administradores de dominio tienen derechos para crear cuentas de equipo.
- El SD en un contenedor puede delegar los derechos para crear cuentas de equipo.
- De forma predeterminada, los usuarios autenticados pueden crear cuentas de equipo con privilegios. Los usuarios autenticados se limitan a crear un número limitado de cuentas que se especifican como una cuota en el dominio (el valor predeterminado es 10). Para obtener más información, vea el atributo ms-DS-MachineAccountQuota en el esquema de Active Directory.
La función NetCreateProvisioningPackage solo funciona con un controlador de dominio grabable y no funciona con un controlador de dominio de solo lectura. Una vez que el aprovisionamiento se realiza en un controlador de dominio grabable y la cuenta se replica en un controlador de dominio de solo lectura, las demás partes de la operación de unión a un dominio sin conexión no requieren acceso a un controlador de dominio.
Si la función NetCreateProvisioningPackage es correcta, el puntero del parámetro pPackageBinData o pPackageTextData (dependiendo del parámetro que no era NULL) se devuelve con los datos serializados para su uso en una operación de combinación sin conexión o como texto en un archivo de instalación desatendido.
Todas las fases del proceso de aprovisionamiento se anexan a un archivo NetSetup.log en el equipo local. El proceso de aprovisionamiento puede incluir hasta tres equipos diferentes: el equipo donde se crea el paquete de aprovisionamiento, el equipo que solicita la instalación del paquete y el equipo donde está instalado el paquete. Habrá NetSetup.log información de archivo almacenada en los tres equipos según la operación realizada. Revisar el contenido de estos archivos es el medio más común para solucionar errores de aprovisionamiento en línea y sin conexión. Las operaciones de aprovisionamiento realizadas por los administradores se registran en el archivo NetSetup.log en %WINDIR%\Debug. Las operaciones de aprovisionamiento realizadas por los no administradores se registran en el archivo NetSetup.log en la carpeta %USERPROFILE%\Debug .
Para obtener más información sobre las operaciones de unión a un dominio sin conexión, consulte la Guía paso a paso de unión a un dominio sin conexión.
La unión (y desenlace) de un equipo a un dominio mediante NetJoinDomain y NetUnjoinDomain solo la realiza un miembro del grupo local Administradores en el equipo de destino. Tenga en cuenta que el administrador de dominio puede establecer requisitos adicionales para unir el dominio mediante la delegación y la asignación de privilegios.
Requisitos
| Cliente mínimo compatible | Windows 8 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2012 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | lmjoin.h (include Lm.h) |
| Library | Netapi32.lib |
| Archivo DLL | Netapi32.dll |
Consulte también
NetRequestProvisioningPackageInstall