WSASetServiceA 関数 (winsock2.h)

[アーティクル]
08/27/2023

WSASetService 関数は、1 つ以上の名前空間内のサービスインスタンスをレジストリに登録または削除します。

構文

INT WSAAPI WSASetServiceA(
  [in] LPWSAQUERYSETA   lpqsRegInfo,
  [in] WSAESETSERVICEOP essoperation,
  [in] DWORD            dwControlFlags
);

パラメーター

[in] lpqsRegInfo

登録または登録解除のためのサービス情報へのポインター。

[in] essoperation

要求された操作を決定する値。このパラメーターには、 Winsock2.h ヘッダーファイルで定義されている WSAESETSERVICEOP 列挙型の値のいずれかを指定できます。

値	意味
RNRSERVICE_REGISTER	サービスを登録します。 SAP の場合、これは定期的なブロードキャストの送信を意味します。これは DNS 名前空間の NOP です。永続データストアの場合、これはアドレス情報を更新することを意味します。
RNRSERVICE_DEREGISTER	レジストリからサービスを削除します。 SAP の場合、これは定期的なブロードキャストの送信を停止します。これは DNS 名前空間の NOP です。永続データストアの場合、これはアドレス情報を削除することを意味します。
RNRSERVICE_DELETE	動的な名前と永続的なスペースからサービスを削除します。 (SERVICE_MULTIPLE フラグを使用して) 複数の CSADDR_INFO 構造体で表されるサービスの場合、指定されたアドレスのみが削除され、サービスの登録時に指定された対応する CSADDR_INFO 構造と完全に一致する必要があります。

[in] dwControlFlags

WSASetService 関数の実行操作をさらに制御するサービスインストールフラグの値。このパラメーターに指定できる値は、 Winsock2.h ヘッダーファイルで定義されています。

フラグ	説明
SERVICE_MULTIPLE	操作のスコープを制御します。このフラグが設定されていない場合、サービスアドレスはグループとして管理されます。レジストリからのレジスタまたは削除により、指定されたアドレスセットを追加する前に、既存のすべてのアドレスが無効になります。設定すると、アクションは指定されたアドレスセットに対してのみ実行されます。レジスタは既存のアドレスを無効にせず、レジストリから削除すると、指定されたアドレスのセットのみが無効になります。

フラグ

説明

SERVICE_MULTIPLE

操作のスコープを制御します。このフラグが設定されていない場合、サービスアドレスはグループとして管理されます。レジストリからのレジスタまたは削除により、指定されたアドレスセットを追加する前に、既存のすべてのアドレスが無効になります。設定すると、アクションは指定されたアドレスセットに対してのみ実行されます。レジスタは既存のアドレスを無効にせず、レジストリから削除すると、指定されたアドレスのセットのみが無効になります。

戻り値

操作が成功した場合、 WSASetService の戻り値は 0 です。それ以外の場合は、SOCKET_ERROR値が返され、 WSAGetLastError を呼び出すことによって特定のエラー番号を取得できます。

エラーコード	意味
WSAEACCES	呼び出し元ルーチンには、サービスをインストールするための十分な特権がありません。
WSAEINVAL	1 つ以上の必須パラメーターが無効であるか、欠落していました。
WSANOTINITIALIZED	Ws2_32.dll が初期化されていません。アプリケーションは、Windows ソケット関数を呼び出す前に、まず WSAStartup を呼び出す必要があります。
WSA_NOT_ENOUGH_MEMORY	操作を実行するためのメモリが不足していました。

注釈

WSASetService 関数を使用して、特定の名前空間プロバイダー、特定の名前空間に関連付けられているすべてのプロバイダー、またはすべての名前空間のすべてのプロバイダーに影響を与えることができます。

次の表に示すように、 essOperation と dwControlFlags で使用できる値を組み合わせて 、WSASetService 関数の操作を制御します。

操作	Flags	サービスは既に存在します	サービスが存在しない
RNRSERVICE_REGISTER	なし	オブジェクトを上書きします。指定されたアドレスのみを使用します。オブジェクトは REGISTERED です。	新しいオブジェクトを作成します。指定されたアドレスのみを使用します。オブジェクトは REGISTERED です。
RNRSERVICE_REGISTER	SERVICE_MULTIPLE	オブジェクトを更新します。既存のセットに新しいアドレスを追加します。オブジェクトは REGISTERED です。	新しいオブジェクトを作成します。指定されたすべてのアドレスを使用します。オブジェクトは REGISTERED です。
RNRSERVICE_DEREGISTER	なし	すべてのアドレスを削除しますが、名前空間からオブジェクトを削除することはありません。オブジェクトがレジストリから削除されます。	WSASERVICE_NOT_FOUND
RNRSERVICE_DEREGISTER	SERVICE_MULTIPLE	オブジェクトを更新します。指定されたアドレスのみを削除します。アドレスが存在しない場合にのみ、オブジェクトを DEREGISTERED としてマークします。名前空間からオブジェクトを削除しません。	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	なし	名前空間からオブジェクトを削除します。	WSASERVICE_NOT_FOUND
RNRSERVICE_DELETE	SERVICE_MULTIPLE	指定されたアドレスのみを削除します。アドレスが残っていない場合にのみ、名前空間からオブジェクトを削除します。	WSASERVICE_NOT_FOUND

Active Directory サービスなどのディレクトリへのサービスの発行は、アクセス制御リスト (ACL) に基づいて制限されます。詳細については、「サービスパブリケーションのセキュリティの問題」を参照してください。

dwControlFlags パラメーターが SERVICE_MULTIPLE に設定されている場合、アプリケーションはそのアドレスを個別に管理できます。これは、アプリケーションがプロトコルを個別に管理する場合や、サービスが複数のコンピューターに存在する場合に便利です。たとえば、サービスで複数のプロトコルが使用されている場合、1 つのリッスンしているソケットが中止されますが、他のソケットは操作可能なままになります。この場合、サービスは、他のアドレスに影響を与えることなく、中止されたアドレスをレジストリから削除できます。

dwControlFlags パラメーターが SERVICE_MULTIPLE に設定されている場合、アプリケーションは古いアドレスをオブジェクトに残してはなりません。これは、DEREGISTER 要求を発行せずにアプリケーションが中止された場合に発生する可能性があります。サービスが登録するときは、そのアドレスを格納する必要があります。次の呼び出しで、サービスは新しいアドレスを登録する前に、これらの古い古いアドレスをレジストリから明示的に削除する必要があります。

メモANSI 文字列を使用する場合、lpqsRegInfo 内の WSAQUERYSET データに、この関数が戻った後に結果が含まれていない可能性があります。これは、このメソッドの ANSI バージョン である WSASetServiceA は、 WSAQUERYSET の ANSI データを内部的に Unicode に変換しますが、結果を ANSI に変換しないためです。これは主に、レコードを一意に識別するために使用される "サービスレコードハンドル" を返すトランスポートに影響します。この問題を回避するには、アプリケーションでこの関数を呼び出すときに WSAQUERYSET で Unicode 文字列データを使用する必要があります。

サービスのプロパティ

次の表では、 WSAQUERYSET 構造体でのサービスプロパティデータの表現方法について説明します。 (省略可能) としてラベル付けされたフィールドには、null ポインターを含めることができます。

WSAQUERYSET メンバー	サービスプロパティの説明
dwSize	sizeof (WSAQUERYSET) に設定する必要があります。これはバージョン管理メカニズムです。
dwOutputFlags	適用されず、無視されます。
lpszServiceInstanceName	参照される文字列には、サービスインスタンス名が含まれています。
lpServiceClassId	このサービスクラスに対応する GUID。
lpVersion	(省略可能)サービスインスタンスのバージョン番号を提供します。
lpszComment	(省略可能)省略可能なコメント文字列。
dwNameSpace	次の表を参照してください。
lpNSProviderId	次の表を参照してください。
lpszContext	(省略可能)階層型名前空間内のクエリの開始点を指定します。
dwNumberOfProtocols	無視されます。
lpafpProtocols	無視されます。
lpszQueryString	無視されます。
dwNumberOfCsAddrs	lpcsaBuffer によって参照されるCSADDR_INFO構造体の配列内の要素の数。
lpcsaBuffer	サービスがリッスンしているアドレスを含む CSADDR_INFO 構造体の配列へのポインター。
lpBlob	(省略可能)これは、プロバイダー固有のエンティティへのポインターです。

次に示すように、 dwNameSpace メンバーと lpNSProviderId メンバーの組み合わせによって、名前空間プロバイダーがこの関数の影響を受けるかどうかを判断します。

dwNameSpace	lpNSProviderId	影響の範囲
無視	Null 以外	指定したネームスペースプロバイダー。
有効な名前- スペース識別子	Null	指定された名前空間をサポートするすべての名前空間プロバイダー。
NS_ALL	Null	すべてのネームスペースプロバイダー。

Windows Phone 8:WSASetServiceW 関数は、Windows Phone 8 以降のWindows Phone ストアアプリでサポートされています。

Windows 8.1およびWindows Server 2012 R2: WSASetServiceW 関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされています。

注意

winsock2.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして WSASetService を定義します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 8.1、 Windows Vista [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	winsock2.h
Library	Ws2_32.lib
[DLL]	Ws2_32.dll