SetServiceW

関数

ネットワークサービスの登録や登録解除を行う。

DLLMSWSOCK.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

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

INT SetServiceW(
    DWORD dwNameSpace,
    SET_SERVICE_OPERATION dwOperation,
    DWORD dwFlags,
    SERVICE_INFOW* lpServiceInfo,
    SERVICE_ASYNC_INFO* lpServiceAsyncInfo,   // optional
    DWORD* lpdwStatusFlags
);

パラメーター

名前

型

方向

説明

dwNameSpace

DWORD

関数が動作する対象の名前空間、または既定の名前空間のセット。

名前空間を指定するには、次の定数のいずれかを使用します。

値	意味
NS_DEFAULT	既定の名前空間のセット。関数はこのセット内の各名前空間に対して問い合わせを行います。既定の名前空間のセットには、通常、システムにインストールされているすべての名前空間が含まれます。ただし、システム管理者は特定の名前空間をセットから除外できます。NS_DEFAULT は、ほとんどのアプリケーションが dwNameSpace に使用すべき値です。
NS_DNS	インターネットでホスト名を解決するために使用される Domain Name System。
NS_NDS	NetWare 4 プロバイダー。
NS_NETBT	NetBIOS over TCP/IP 層。すべての Windows システムは、コンピューター名を NetBIOS に登録します。この名前空間は、この登録を使用してコンピューター名を IP アドレスに変換するために使用されます。
NS_SAP	NetWare Service Advertising Protocol。必要に応じて NetWare バインダリにアクセスできます。NS_SAP は、サービスの登録を可能にする動的な名前空間です。
NS_TCPIP_HOSTS	<systemroot>\system32\drivers\etc\posts ファイル内の検索値。
NS_TCPIP_LOCAL	ローカルのホスト名との比較や、ホストと IP アドレスのマッピングのキャッシュ内の検索値を含む、ローカルの TCP/IP 名前解決メカニズム。

dwOperation

SET_SERVICE_OPERATION

関数が実行する操作。操作を指定するには、次の値のいずれかを使用します。

値	意味
SERVICE_REGISTER	ネットワークサービスを名前空間に登録します。この操作は、SERVICE_FLAG_DEFER および SERVICE_FLAG_HARD ビットフラグと組み合わせて使用できます。
SERVICE_DEREGISTER	ネットワークサービスを名前空間からレジストリ上で削除します。この操作は、SERVICE_FLAG_DEFER および SERVICE_FLAG_HARD ビットフラグと組み合わせて使用できます。
SERVICE_FLUSH	SERVICE_FLAG_DEFER ビットフラグを 1 に設定して呼び出された操作を実行します。
SERVICE_ADD_TYPE	名前空間にサービスの種類を追加します。この操作では、lpServiceInfo が指す SERVICE_INFO 構造体の ServiceSpecificInfo メンバーを使用して、 SERVICE_TYPE_INFO_ABS 構造体を渡します。また、 SERVICE_INFO 構造体の ServiceType メンバーも設定する必要があります。その他の SERVICE_INFO メンバーは無視されます。
SERVICE_DELETE_TYPE	SERVICE_ADD_TYPE 操作を指定した以前の呼び出しによって追加されたサービスの種類を、名前空間から削除します。

dwFlags

DWORD

関数の動作を変更するビットフラグのセット。次のビットフラグの 1 つ以上を設定できます。

値

意味

SERVICE_FLAG_DEFER

このビットフラグは、操作が SERVICE_REGISTER または SERVICE_DEREGISTER の場合にのみ有効です。

このビットフラグが 1 で、かつ有効である場合、名前空間プロバイダーは、SERVICE_FLUSH 操作が要求されるまで登録または登録解除の操作を遅延させる必要があります。

SERVICE_FLAG_HARD

このビットフラグは、操作が SERVICE_REGISTER または SERVICE_DEREGISTER の場合にのみ有効です。

このビットフラグが 1 で、かつ有効である場合、名前空間プロバイダーは、操作の実行時に関連する永続ストアの情報を更新します。

例: 永続ストアを使用する名前空間で登録解除を伴う操作の場合、名前空間プロバイダーは関連する永続ストアの情報を削除します。

lpServiceInfo

SERVICE_INFOW*

ネットワークサービスまたはサービスの種類に関する情報を含む SERVICE_INFO 構造体へのポインター。

lpServiceAsyncInfo

SERVICE_ASYNC_INFO*

inoptional

将来の使用のために予約されています。NULL に設定する必要があります。

lpdwStatusFlags

DWORD*

out

関数のステータス情報を受け取るビットフラグのセット。次のビットフラグが定義されています。

値	意味
SET_SERVICE_ PARTIAL_SUCCESS	1 つ以上の名前空間プロバイダーが、要求された操作を正常に実行できませんでした。

戻り値の型: INT

公式ドキュメント

SetService 関数は、1 つ以上の名前空間内でネットワークサービスをレジストリに登録、またはレジストリから削除します。(Unicode)

戻り値

関数が失敗した場合、戻り値は SOCKET_ERROR です。詳細なエラー情報を取得するには、 GetLastError を呼び出します。GetLastError は、次の詳細なエラー値を返すことがあります。

エラーコード	意味
ERROR_ALREADY_ REGISTERED	関数が、すでに登録されているサービスを登録しようとしました。

解説(Remarks)

メモ

nspapi.h ヘッダーは、SetService を、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)

各言語での呼び出し定義

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

INT SetServiceW(
    DWORD dwNameSpace,
    SET_SERVICE_OPERATION dwOperation,
    DWORD dwFlags,
    SERVICE_INFOW* lpServiceInfo,
    SERVICE_ASYNC_INFO* lpServiceAsyncInfo,   // optional
    DWORD* lpdwStatusFlags
);

[DllImport("MSWSOCK.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern int SetServiceW(
    uint dwNameSpace,   // DWORD
    uint dwOperation,   // SET_SERVICE_OPERATION
    uint dwFlags,   // DWORD
    IntPtr lpServiceInfo,   // SERVICE_INFOW*
    IntPtr lpServiceAsyncInfo,   // SERVICE_ASYNC_INFO* optional
    out uint lpdwStatusFlags   // DWORD* out
);

<DllImport("MSWSOCK.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function SetServiceW(
    dwNameSpace As UInteger,   ' DWORD
    dwOperation As UInteger,   ' SET_SERVICE_OPERATION
    dwFlags As UInteger,   ' DWORD
    lpServiceInfo As IntPtr,   ' SERVICE_INFOW*
    lpServiceAsyncInfo As IntPtr,   ' SERVICE_ASYNC_INFO* optional
    <Out> ByRef lpdwStatusFlags As UInteger   ' DWORD* out
) As Integer
End Function

' dwNameSpace : DWORD
' dwOperation : SET_SERVICE_OPERATION
' dwFlags : DWORD
' lpServiceInfo : SERVICE_INFOW*
' lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional
' lpdwStatusFlags : DWORD* out
Declare PtrSafe Function SetServiceW Lib "mswsock" ( _
    ByVal dwNameSpace As Long, _
    ByVal dwOperation As Long, _
    ByVal dwFlags As Long, _
    ByVal lpServiceInfo As LongPtr, _
    ByVal lpServiceAsyncInfo As LongPtr, _
    ByRef lpdwStatusFlags As Long) 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

SetServiceW = ctypes.windll.mswsock.SetServiceW
SetServiceW.restype = ctypes.c_int
SetServiceW.argtypes = [
    wintypes.DWORD,  # dwNameSpace : DWORD
    wintypes.DWORD,  # dwOperation : SET_SERVICE_OPERATION
    wintypes.DWORD,  # dwFlags : DWORD
    ctypes.c_void_p,  # lpServiceInfo : SERVICE_INFOW*
    ctypes.c_void_p,  # lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional
    ctypes.POINTER(wintypes.DWORD),  # lpdwStatusFlags : DWORD* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MSWSOCK.dll')
SetServiceW = Fiddle::Function.new(
  lib['SetServiceW'],
  [
    -Fiddle::TYPE_INT,  # dwNameSpace : DWORD
    -Fiddle::TYPE_INT,  # dwOperation : SET_SERVICE_OPERATION
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # lpServiceInfo : SERVICE_INFOW*
    Fiddle::TYPE_VOIDP,  # lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional
    Fiddle::TYPE_VOIDP,  # lpdwStatusFlags : DWORD* out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "mswsock")]
extern "system" {
    fn SetServiceW(
        dwNameSpace: u32,  // DWORD
        dwOperation: u32,  // SET_SERVICE_OPERATION
        dwFlags: u32,  // DWORD
        lpServiceInfo: *mut SERVICE_INFOW,  // SERVICE_INFOW*
        lpServiceAsyncInfo: *mut SERVICE_ASYNC_INFO,  // SERVICE_ASYNC_INFO* optional
        lpdwStatusFlags: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("MSWSOCK.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern int SetServiceW(uint dwNameSpace, uint dwOperation, uint dwFlags, IntPtr lpServiceInfo, IntPtr lpServiceAsyncInfo, out uint lpdwStatusFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MSWSOCK_SetServiceW' -Namespace Win32 -PassThru
# $api::SetServiceW(dwNameSpace, dwOperation, dwFlags, lpServiceInfo, lpServiceAsyncInfo, lpdwStatusFlags)

#uselib "MSWSOCK.dll"
#func global SetServiceW "SetServiceW" wptr, wptr, wptr, wptr, wptr, wptr
; SetServiceW dwNameSpace, dwOperation, dwFlags, varptr(lpServiceInfo), varptr(lpServiceAsyncInfo), varptr(lpdwStatusFlags)   ; 戻り値は stat
; dwNameSpace : DWORD -> "wptr"
; dwOperation : SET_SERVICE_OPERATION -> "wptr"
; dwFlags : DWORD -> "wptr"
; lpServiceInfo : SERVICE_INFOW* -> "wptr"
; lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional -> "wptr"
; lpdwStatusFlags : DWORD* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "MSWSOCK.dll"
#cfunc global SetServiceW "SetServiceW" int, int, int, var, var, var
; res = SetServiceW(dwNameSpace, dwOperation, dwFlags, lpServiceInfo, lpServiceAsyncInfo, lpdwStatusFlags)
; dwNameSpace : DWORD -> "int"
; dwOperation : SET_SERVICE_OPERATION -> "int"
; dwFlags : DWORD -> "int"
; lpServiceInfo : SERVICE_INFOW* -> "var"
; lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional -> "var"
; lpdwStatusFlags : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "MSWSOCK.dll"
#cfunc global SetServiceW "SetServiceW" int, int, int, sptr, sptr, sptr
; res = SetServiceW(dwNameSpace, dwOperation, dwFlags, varptr(lpServiceInfo), varptr(lpServiceAsyncInfo), varptr(lpdwStatusFlags))
; dwNameSpace : DWORD -> "int"
; dwOperation : SET_SERVICE_OPERATION -> "int"
; dwFlags : DWORD -> "int"
; lpServiceInfo : SERVICE_INFOW* -> "sptr"
; lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional -> "sptr"
; lpdwStatusFlags : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。