SetServiceA

関数

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

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

シグネチャ

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

INT SetServiceA(
    DWORD dwNameSpace,
    SET_SERVICE_OPERATION dwOperation,
    DWORD dwFlags,
    SERVICE_INFOA* 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	ローカルの TCP/IP 名前解決メカニズム。ローカルホスト名との比較や、ホストから 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_INFOA*

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

lpServiceAsyncInfo

SERVICE_ASYNC_INFO*

inoptional

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

lpdwStatusFlags

DWORD*

out

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

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

戻り値の型: INT

公式ドキュメント

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

戻り値

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

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

解説(Remarks)

メモ

nspapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして SetService を定義します。エンコーディング中立のエイリアスの使用と、エンコーディング中立でないコードを混在させると、コンパイルエラーや実行時エラーを引き起こす不整合につながる可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

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

各言語での呼び出し定義

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

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

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

<DllImport("MSWSOCK.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function SetServiceA(
    dwNameSpace As UInteger,   ' DWORD
    dwOperation As UInteger,   ' SET_SERVICE_OPERATION
    dwFlags As UInteger,   ' DWORD
    lpServiceInfo As IntPtr,   ' SERVICE_INFOA*
    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_INFOA*
' lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional
' lpdwStatusFlags : DWORD* out
Declare PtrSafe Function SetServiceA 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
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SetServiceA = ctypes.windll.mswsock.SetServiceA
SetServiceA.restype = ctypes.c_int
SetServiceA.argtypes = [
    wintypes.DWORD,  # dwNameSpace : DWORD
    wintypes.DWORD,  # dwOperation : SET_SERVICE_OPERATION
    wintypes.DWORD,  # dwFlags : DWORD
    ctypes.c_void_p,  # lpServiceInfo : SERVICE_INFOA*
    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')
SetServiceA = Fiddle::Function.new(
  lib['SetServiceA'],
  [
    -Fiddle::TYPE_INT,  # dwNameSpace : DWORD
    -Fiddle::TYPE_INT,  # dwOperation : SET_SERVICE_OPERATION
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # lpServiceInfo : SERVICE_INFOA*
    Fiddle::TYPE_VOIDP,  # lpServiceAsyncInfo : SERVICE_ASYNC_INFO* optional
    Fiddle::TYPE_VOIDP,  # lpdwStatusFlags : DWORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "mswsock")]
extern "system" {
    fn SetServiceA(
        dwNameSpace: u32,  // DWORD
        dwOperation: u32,  // SET_SERVICE_OPERATION
        dwFlags: u32,  // DWORD
        lpServiceInfo: *mut SERVICE_INFOA,  // SERVICE_INFOA*
        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.Ansi, SetLastError = true)]
public static extern int SetServiceA(uint dwNameSpace, uint dwOperation, uint dwFlags, IntPtr lpServiceInfo, IntPtr lpServiceAsyncInfo, out uint lpdwStatusFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MSWSOCK_SetServiceA' -Namespace Win32 -PassThru
# $api::SetServiceA(dwNameSpace, dwOperation, dwFlags, lpServiceInfo, lpServiceAsyncInfo, lpdwStatusFlags)

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

出力引数:

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