Función DsGetSpnA (ntdsapi.h)

Artículo
03/08/2023

La función DsGetSpn construye una matriz de uno o varios nombres de entidad de seguridad de servicio (SPN). Cada nombre de la matriz identifica una instancia de un servicio. Estos SPN se pueden registrar con el servicio de directorio (DS) mediante la función DsWriteAccountSpn .

Sintaxis

NTDSAPI DWORD DsGetSpnA(
  [in]           DS_SPN_NAME_TYPE ServiceType,
  [in]           LPCSTR           ServiceClass,
  [in, optional] LPCSTR           ServiceName,
  [in]           USHORT           InstancePort,
  [in]           USHORT           cInstanceNames,
  [in, optional] LPCSTR           *pInstanceNames,
  [in, optional] const USHORT     *pInstancePorts,
  [out]          DWORD            *pcSpn,
  [out]          LPSTR            **prpszSpn
);

Parámetros

[in] ServiceType

Identifica el formato de los SPN que se van a componer. El parámetro ServiceType puede tener uno de los valores siguientes.

DS_SPN_DNS_HOST, DS_SPN_DN_HOST, DS_SPN_NB_HOST

Los SPN tienen el formato siguiente.

ServiceClass/ InstanceName: InstancePort

El parámetro ServiceName debe ser NULL. Este es el formato SPN de un servicio basado en host, que proporciona servicios identificados con su equipo host. El componente InstancePort es opcional.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

Los SPN tienen el formato siguiente.

ServiceClass/ InstanceName: InstancePort/ ServiceName

El parámetro ServiceName debe ser el nombre DNS o el DN de un dominio. Este formato se usa para un servicio replicable que proporciona servicios al dominio especificado.

DS_SPN_SERVICE

Los SPN tienen el formato siguiente.

ServiceClass/ InstanceName: InstancePort/ ServiceName

El parámetro ServiceName debe ser un nombre DNS o DN canónico que identifique una instancia del servicio. Por ejemplo, podría ser un nombre DNS de un registro SRV o el nombre distintivo del punto de conexión de servicio para esta instancia de servicio.

[in] ServiceClass

Puntero a una cadena terminada en null constante que especifica la clase del servicio; por ejemplo, http. Por lo general, puede ser cualquier cadena que sea única para el servicio.

[in, optional] ServiceName

Puntero a una cadena terminada en null constante que especifica el nombre DNS o el nombre distintivo (DN) del servicio. ServiceName no es necesario para un servicio basado en host. Para obtener más información, consulte la descripción del parámetro ServiceType para conocer los posibles valores de ServiceName.

[in] InstancePort

Especifica el número de puerto de la instancia de servicio. Si este valor es cero, el SPN no incluye un número de puerto.

[in] cInstanceNames

Especifica el número de elementos de las matrices pInstanceNames y pInstancePorts . Si este valor no es cero, pInstanceNames debe apuntar a una matriz de cadenas cInstanceNames y pInstancePorts puede ser NULL o un puntero a una matriz de números de puerto cInstanceNames . Si este valor es cero, DsGetSpn devuelve solo un SPN en la matriz prpszSpn y pInstanceNames y pInstancePorts se omiten.

[in, optional] pInstanceNames

Puntero a una matriz de cadenas terminadas en null que especifican nombres de instancia adicionales (no se usan para nombres de host). Este parámetro se omite si cInstanceNames es cero. En ese caso, el componente InstanceName del SPN tiene como valor predeterminado el nombre DNS completo del equipo local o el nombre NetBIOS si se especifica DS_SPN_NB_HOST o DS_SPN_NB_DOMAIN .

[in, optional] pInstancePorts

Puntero a una matriz de puertos de instancia adicionales. Si este valor no es NULL, debe apuntar a una matriz de números de puerto cInstanceNames . Si este valor es NULL, los SPN no incluyen un número de puerto. Este parámetro se omite si cInstanceNames es cero.

[out] pcSpn

Puntero a una variable que recibe el número de SPN contenidos en prpszSpn.

[out] prpszSpn

Puntero a una variable que recibe un puntero a una matriz de SPN. Esta matriz debe liberarse con DsFreeSpnArray.

Valor devuelto

Si la función devuelve una matriz de SPN, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error.

Comentarios

Para crear SPN para varias instancias de un servicio replicado que se ejecuta en varios equipos host

Establezca cInstanceNames en el número de instancias.
Especifique los nombres de los equipos host en la matriz pInstanceNames .

Para crear SPN para varias instancias de un servicio que se ejecuta en el mismo equipo host

Establezca cInstanceNames en el número de instancias.
Establezca cada entrada de la matriz pInstanceNames en el nombre DNS del equipo host.
Use el parámetro pInstancePorts para especificar una matriz de números de puerto únicos para cada instancia para eliminar la ambigüedad de los SPN.

Los parámetros de cadena no pueden incluir la barra diagonal (/), que se usa para separar los componentes del SPN.

Una aplicación con los privilegios adecuados, que suelen ser los de un administrador de dominio, puede llamar a la función DsWriteAccountSpn para registrar uno o varios SPN en la cuenta de usuario o equipo donde se ejecuta el servicio. A continuación, los clientes pueden usar los SPN para autenticar el servicio.

Nota

El encabezado ntdsapi.h define DsGetSpn como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	ntdsapi.h
Library	Ntdsapi.lib
Archivo DLL	Ntdsapi.dll