ホーム › Networking.ActiveDirectory › DsMakeSpnA

DsMakeSpnA

関数

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

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

シグネチャ

// DSPARSE.dll  (ANSI / -A)
#include <windows.h>

DWORD DsMakeSpnA(
    LPCSTR ServiceClass,
    LPCSTR ServiceName,
    LPCSTR InstanceName,   // optional
    WORD InstancePort,
    LPCSTR Referrer,   // optional
    DWORD* pcSpnLength,
    LPSTR pszSpn   // optional
);

パラメーター

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

戻り値の型: DWORD

公式ドキュメント

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

戻り値

関数が 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 ヘッダーは DsMakeSpn を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義しています。エンコード中立のエイリアスと、エンコード中立でないコードを混在させて使用すると、不一致が生じ、コンパイルエラーや実行時エラーの原因となることがあります。詳細については、「Conventions for Function Prototypes」を参照してください。

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

各言語での呼び出し定義

// DSPARSE.dll  (ANSI / -A)
#include <windows.h>

DWORD DsMakeSpnA(
    LPCSTR ServiceClass,
    LPCSTR ServiceName,
    LPCSTR InstanceName,   // optional
    WORD InstancePort,
    LPCSTR Referrer,   // optional
    DWORD* pcSpnLength,
    LPSTR pszSpn   // optional
);

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

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

' ServiceClass : LPCSTR
' ServiceName : LPCSTR
' InstanceName : LPCSTR optional
' InstancePort : WORD
' Referrer : LPCSTR optional
' pcSpnLength : DWORD* in/out
' pszSpn : LPSTR optional, out
Declare PtrSafe Function DsMakeSpnA Lib "dsparse" ( _
    ByVal ServiceClass As String, _
    ByVal ServiceName As String, _
    ByVal InstanceName As String, _
    ByVal InstancePort As Integer, _
    ByVal Referrer As String, _
    ByRef pcSpnLength As Long, _
    ByVal pszSpn As String) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('DSPARSE.dll')
DsMakeSpnA = Fiddle::Function.new(
  lib['DsMakeSpnA'],
  [
    Fiddle::TYPE_VOIDP,  # ServiceClass : LPCSTR
    Fiddle::TYPE_VOIDP,  # ServiceName : LPCSTR
    Fiddle::TYPE_VOIDP,  # InstanceName : LPCSTR optional
    -Fiddle::TYPE_SHORT,  # InstancePort : WORD
    Fiddle::TYPE_VOIDP,  # Referrer : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # pcSpnLength : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # pszSpn : LPSTR optional, out
  ],
  -Fiddle::TYPE_INT)

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

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

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

出力引数:

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