ホーム › Networking.ActiveDirectory › DsMakeSpnW

DsMakeSpnW

関数

構成要素からサービスプリンシパル名を生成する(Unicode版)。

DLLDSPARSE.dll文字セットUnicode (-W)呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// DSPARSE.dll  (Unicode / -W)
#include <windows.h>

DWORD DsMakeSpnW(
    LPCWSTR ServiceClass,
    LPCWSTR ServiceName,
    LPCWSTR InstanceName,   // optional
    WORD InstancePort,
    LPCWSTR Referrer,   // optional
    DWORD* pcSpnLength,
    LPWSTR pszSpn   // optional
);

パラメーター

名前	型	方向	説明
ServiceClass	LPCWSTR	in	サービスのクラスを指定する、null で終わる定数文字列へのポインター。このパラメーターには、そのサービスに固有の任意の文字列を指定できます。プロトコル名 (たとえば ldap) や、GUID の文字列形式などを使用できます。
ServiceName	LPCWSTR	in	DNS 名、NetBIOS 名、または識別名 (DN) を指定する、null で終わる定数文字列へのポインター。このパラメーターは NULL 以外である必要があります。 ServiceName、InstanceName、InstancePort の各パラメーターを使用して SPN を構成する方法の詳細については、後述の「解説」セクションを参照してください。
InstanceName	LPCWSTR	inoptional	サービスのインスタンスをホストするコンピューターの DNS 名または IP アドレスを指定する、null で終わる定数文字列へのポインター。 ServiceName がサービスのホストコンピューターの DNS 名または NetBIOS 名を指定している場合、InstanceName パラメーターは NULL である必要があります。 ServiceName が DNS ドメイン名、DNS SRV レコードの名前、またはサービス接続ポイントの DN のような識別名を指定している場合、InstanceName パラメーターにはサービスのホストコンピューターの DNS 名または NetBIOS 名を指定する必要があります。
InstancePort	WORD	in	サービスのインスタンスのポート番号。既定のポートを使用する場合は 0 を指定します。このパラメーターが 0 の場合、SPN にポート番号は含まれません。
Referrer	LPCWSTR	inoptional	IP アドレスの参照 (リファーラル) を提供したホストの DNS 名を指定する、null で終わる定数文字列へのポインター。ServiceName パラメーターが IP アドレスを指定している場合を除き、このパラメーターは無視されます。
pcSpnLength	DWORD*	inout	構築された新しい SPN を受け取るバッファーの長さ (文字数) を格納する変数へのポインター。最終的に必要なバッファーサイズを事前に取得するために、この値を 0 にすることもできます。 pcSpnLength パラメーターは、終端の null 文字を含む、作成された SPN の実際の長さも受け取ります。
pszSpn	LPWSTR	outoptional	構築された SPN を受け取る、null で終わる文字列へのポインター。このバッファーは pcSpnLength で指定された長さである必要があります。最終的に必要なバッファーサイズを事前に取得するために、pszSpn パラメーターを NULL にすることもできます。

戻り値の型: DWORD

公式ドキュメント

サービスインスタンスを識別するサービスプリンシパル名 (SPN) を構築します。(Unicode)

戻り値

関数が SPN を返した場合、戻り値は ERROR_SUCCESS です。関数が失敗した場合、戻り値は次のエラーコードのいずれかになります。

解説(Remarks)

DsMakeSpn 関数が生成する SPN の形式は、入力パラメーターによって異なります。基本的な形式は 2 つあります。どちらの形式も、ServiceClass 文字列で始まり、その後にホストコンピューター名と、省略可能な InstancePort コンポーネントが続きます。

メモこの形式はホストベースのサービスで使用されます。

"<ServiceClass>/<host>" 形式の SPN を生成するには

ServiceName パラメーターに、サービスインスタンスのホストコンピューターの DNS 名を設定します。これが SPN のホストコンポーネントになります。
InstanceName パラメーターと Referrer パラメーターを NULL に設定します。
InstancePort パラメーターを 0 に設定します。InstancePort が 0 以外の場合、SPN は次の形式になります。
```
<service class>/<host>:<instance port>/<referrer>
```

メモこの形式はレプリケーション可能なサービスで使用されます。

"<ServiceClass>/<host>:<InstancePort>" 形式の SPN を生成するには

InstanceName パラメーターに、サービスインスタンスのホストコンピューターの DNS 名を設定します。これがホストコンポーネントになります。
ServiceName パラメーターに、サービスのインスタンスを識別する文字列を設定します。たとえば、そのサービスインスタンスのサービス接続ポイントの識別名などを指定できます。
Referrer パラメーターを NULL に設定します。
InstancePort パラメーターを 0 に設定します。InstancePort が 0 以外の場合、SPN は次の形式になります。
```
<service class>/<host>:<instance port>/<service name>
```

Referrer パラメーターは、ServiceName パラメーターがサービスのホストコンピューターの IP アドレスを指定している場合にのみ使用されます。この場合、Referrer には、その IP アドレスを参照 (リファーラル) として提供したコンピューターの DNS 名を指定します。SPN は次の形式になります。

<service class>/<host>:<instance port>/<referrer>

ここで、ホストコンポーネントは InstanceName 文字列 (InstanceName が NULL の場合は ServiceName 文字列) であり、InstancePort コンポーネントは省略可能です。

スラッシュ (/) 文字は SPN の各コンポーネントを区切るために使用されるため、文字列パラメーターにこの文字を含めることはできません。

メモ

dsparse.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして、DsMakeSpn を定義しています。エンコーディング中立のエイリアスと、エンコーディング中立でないコードを混在させると、不一致が生じ、コンパイルエラーや実行時エラーの原因になることがあります。詳細については、関数プロトタイプの表記規則を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// DSPARSE.dll  (Unicode / -W)
#include <windows.h>

DWORD DsMakeSpnW(
    LPCWSTR ServiceClass,
    LPCWSTR ServiceName,
    LPCWSTR InstanceName,   // optional
    WORD InstancePort,
    LPCWSTR Referrer,   // optional
    DWORD* pcSpnLength,
    LPWSTR pszSpn   // optional
);

[DllImport("DSPARSE.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern uint DsMakeSpnW(
    [MarshalAs(UnmanagedType.LPWStr)] string ServiceClass,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string ServiceName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string InstanceName,   // LPCWSTR optional
    ushort InstancePort,   // WORD
    [MarshalAs(UnmanagedType.LPWStr)] string Referrer,   // LPCWSTR optional
    ref uint pcSpnLength,   // DWORD* in/out
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pszSpn   // LPWSTR optional, out
);

<DllImport("DSPARSE.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function DsMakeSpnW(
    <MarshalAs(UnmanagedType.LPWStr)> ServiceClass As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> ServiceName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> InstanceName As String,   ' LPCWSTR optional
    InstancePort As UShort,   ' WORD
    <MarshalAs(UnmanagedType.LPWStr)> Referrer As String,   ' LPCWSTR optional
    ByRef pcSpnLength As UInteger,   ' DWORD* in/out
    <MarshalAs(UnmanagedType.LPWStr)> pszSpn As System.Text.StringBuilder   ' LPWSTR optional, out
) As UInteger
End Function

' ServiceClass : LPCWSTR
' ServiceName : LPCWSTR
' InstanceName : LPCWSTR optional
' InstancePort : WORD
' Referrer : LPCWSTR optional
' pcSpnLength : DWORD* in/out
' pszSpn : LPWSTR optional, out
Declare PtrSafe Function DsMakeSpnW Lib "dsparse" ( _
    ByVal ServiceClass As LongPtr, _
    ByVal ServiceName As LongPtr, _
    ByVal InstanceName As LongPtr, _
    ByVal InstancePort As Integer, _
    ByVal Referrer As LongPtr, _
    ByRef pcSpnLength As Long, _
    ByVal pszSpn As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

DsMakeSpnW = ctypes.windll.dsparse.DsMakeSpnW
DsMakeSpnW.restype = wintypes.DWORD
DsMakeSpnW.argtypes = [
    wintypes.LPCWSTR,  # ServiceClass : LPCWSTR
    wintypes.LPCWSTR,  # ServiceName : LPCWSTR
    wintypes.LPCWSTR,  # InstanceName : LPCWSTR optional
    ctypes.c_ushort,  # InstancePort : WORD
    wintypes.LPCWSTR,  # Referrer : LPCWSTR optional
    ctypes.POINTER(wintypes.DWORD),  # pcSpnLength : DWORD* in/out
    wintypes.LPWSTR,  # pszSpn : LPWSTR optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('DSPARSE.dll')
DsMakeSpnW = Fiddle::Function.new(
  lib['DsMakeSpnW'],
  [
    Fiddle::TYPE_VOIDP,  # ServiceClass : LPCWSTR
    Fiddle::TYPE_VOIDP,  # ServiceName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # InstanceName : LPCWSTR optional
    -Fiddle::TYPE_SHORT,  # InstancePort : WORD
    Fiddle::TYPE_VOIDP,  # Referrer : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # pcSpnLength : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # pszSpn : LPWSTR optional, out
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "dsparse")]
extern "system" {
    fn DsMakeSpnW(
        ServiceClass: *const u16,  // LPCWSTR
        ServiceName: *const u16,  // LPCWSTR
        InstanceName: *const u16,  // LPCWSTR optional
        InstancePort: u16,  // WORD
        Referrer: *const u16,  // LPCWSTR optional
        pcSpnLength: *mut u32,  // DWORD* in/out
        pszSpn: *mut u16  // LPWSTR optional, out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("DSPARSE.dll", CharSet = CharSet.Unicode)]
public static extern uint DsMakeSpnW([MarshalAs(UnmanagedType.LPWStr)] string ServiceClass, [MarshalAs(UnmanagedType.LPWStr)] string ServiceName, [MarshalAs(UnmanagedType.LPWStr)] string InstanceName, ushort InstancePort, [MarshalAs(UnmanagedType.LPWStr)] string Referrer, ref uint pcSpnLength, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pszSpn);
"@
$api = Add-Type -MemberDefinition $sig -Name 'DSPARSE_DsMakeSpnW' -Namespace Win32 -PassThru
# $api::DsMakeSpnW(ServiceClass, ServiceName, InstanceName, InstancePort, Referrer, pcSpnLength, pszSpn)

#uselib "DSPARSE.dll"
#func global DsMakeSpnW "DsMakeSpnW" wptr, wptr, wptr, wptr, wptr, wptr, wptr
; DsMakeSpnW ServiceClass, ServiceName, InstanceName, InstancePort, Referrer, varptr(pcSpnLength), varptr(pszSpn)   ; 戻り値は stat
; ServiceClass : LPCWSTR -> "wptr"
; ServiceName : LPCWSTR -> "wptr"
; InstanceName : LPCWSTR optional -> "wptr"
; InstancePort : WORD -> "wptr"
; Referrer : LPCWSTR optional -> "wptr"
; pcSpnLength : DWORD* in/out -> "wptr"
; pszSpn : LPWSTR optional, out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "DSPARSE.dll"
#cfunc global DsMakeSpnW "DsMakeSpnW" wstr, wstr, wstr, int, wstr, var, var
; res = DsMakeSpnW(ServiceClass, ServiceName, InstanceName, InstancePort, Referrer, pcSpnLength, pszSpn)
; ServiceClass : LPCWSTR -> "wstr"
; ServiceName : LPCWSTR -> "wstr"
; InstanceName : LPCWSTR optional -> "wstr"
; InstancePort : WORD -> "int"
; Referrer : LPCWSTR optional -> "wstr"
; pcSpnLength : DWORD* in/out -> "var"
; pszSpn : LPWSTR optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "DSPARSE.dll"
#cfunc global DsMakeSpnW "DsMakeSpnW" wstr, wstr, wstr, int, wstr, sptr, sptr
; res = DsMakeSpnW(ServiceClass, ServiceName, InstanceName, InstancePort, Referrer, varptr(pcSpnLength), varptr(pszSpn))
; ServiceClass : LPCWSTR -> "wstr"
; ServiceName : LPCWSTR -> "wstr"
; InstanceName : LPCWSTR optional -> "wstr"
; InstancePort : WORD -> "int"
; Referrer : LPCWSTR optional -> "wstr"
; pcSpnLength : DWORD* in/out -> "sptr"
; pszSpn : LPWSTR optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。