Функция DsGetSpnA (ntdsapi.h)

Статья
08/25/2023

Функция DsGetSpn создает массив из одного или нескольких имен субъектов-служб. Каждое имя в массиве определяет экземпляр службы. Эти имена субъектов-служб можно зарегистрировать в службе каталогов (DS) с помощью функции DsWriteAccountSpn .

Синтаксис

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
);

Параметры

[in] ServiceType

Определяет формат имен субъектов-служб для создания. Параметр ServiceType может иметь одно из следующих значений.

DS_SPN_DNS_HOST, DS_SPN_DN_HOST DS_SPN_NB_HOST

Имена субъектов-служб имеют следующий формат.

ServiceClass/ InstanceName: InstancePort

Параметр ServiceName должен иметь значение NULL. Это формат имени субъекта-службы для службы на основе узла, которая предоставляет службы, идентифицированные с главного компьютера. Компонент InstancePort является необязательным.

DS_SPN_DOMAIN, DS_SPN_NB_DOMAIN

Имена субъектов-служб имеют следующий формат.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Параметр ServiceName должен быть DNS-именем или DN домена. Этот формат используется для реплицируемой службы, которая предоставляет службы указанному домену.

DS_SPN_SERVICE

Имена субъектов-служб имеют следующий формат.

ServiceClass/ InstanceName: InstancePort/ ServiceName

Параметр ServiceName должен быть каноническим DN или DNS-именем, которое идентифицирует экземпляр службы. Например, это может быть DNS-имя записи SRV или различающееся имя точки подключения службы для этого экземпляра службы.

[in] ServiceClass

Указатель на константную строку, завершающуюся null, которая указывает класс службы; например http. Как правило, это может быть любая строка, уникальная для службы.

[in, optional] ServiceName

Указатель на константную строку, завершающуюся null, которая указывает DNS-имя или различающееся имя (DN) службы. ServiceName не требуется для службы на основе узла. Дополнительные сведения см. в описании параметра ServiceType для возможных значений ServiceName.

[in] InstancePort

Указывает номер порта экземпляра службы. Если это значение равно нулю, имя субъекта-службы не включает номер порта.

[in] cInstanceNames

Указывает количество элементов в массивах pInstanceNames и pInstancePorts . Если это значение не равно нулю, pInstanceNames должен указывать на массив строк cInstanceNames , а pInstancePorts может иметь значение NULL или указатель на массив номеров портов cInstanceNames . Если это значение равно нулю, DsGetSpn возвращает только одно имя субъекта-службы в массиве prpszSpn , а pInstanceNames и pInstancePorts игнорируются.

[in, optional] pInstanceNames

Указатель на массив строк, заканчивающихся нулевым значением, которые указывают дополнительные имена экземпляров (не используются для имен узлов). Этот параметр игнорируется, если cInstanceNames равно нулю. В этом случае компонент InstanceName имени субъекта-службы по умолчанию использует полное DNS-имя локального компьютера или NetBIOS-имя, если указано DS_SPN_NB_HOST или DS_SPN_NB_DOMAIN .

[in, optional] pInstancePorts

Указатель на массив дополнительных портов экземпляра. Если это значение не равно NULL, оно должно указывать на массив номеров портов cInstanceNames . Если это значение равно NULL, имена субъектов-служб не включают номер порта. Этот параметр игнорируется, если cInstanceNames равно нулю.

[out] pcSpn

Указатель на переменную, которая получает количество имен субъектов-служб, содержащихся в prpszSpn.

[out] prpszSpn

Указатель на переменную, которая получает указатель на массив имен субъектов-служб. Этот массив должен быть освобожден с помощью DsFreeSpnArray.

Возвращаемое значение

Если функция возвращает массив имен субъектов-служб, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов ошибок.

Задайте для cInstanceNames число экземпляров.
Задайте для каждой записи в массиве pInstanceNames DNS-имя главного компьютера.
Используйте параметр pInstancePorts , чтобы указать массив уникальных номеров портов для каждого экземпляра, чтобы устранить неоднозначность имен субъектов-служб.

Строковые параметры не могут включать косую черту (/), которая используется для разделения компонентов имени субъекта-службы.

Приложение с соответствующими привилегиями, которые обычно являются привилегиями администратора домена, может вызвать функцию DsWriteAccountSpn , чтобы зарегистрировать одно или несколько имен субъектов-служб в учетной записи пользователя или компьютера, в которой запущена служба. Затем клиенты могут использовать имена субъектов-служб для проверки подлинности службы.

Примечание

Заголовок ntdsapi.h определяет DsGetSpn в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Целевая платформа	Windows
Header	ntdsapi.h
Библиотека	Ntdsapi.lib
DLL	Ntdsapi.dll