LPNSPV2SETSERVICEEX コールバック関数 (ws2spi.h)

[アーティクル]
03/13/2024

NSPv2SetServiceEx 関数は、名前空間サービスプロバイダーバージョン 2 (NSPv2) プロバイダーの名前空間内の名前またはサービスインスタンスを登録または登録解除します。

構文

LPNSPV2SETSERVICEEX Lpnspv2setserviceex;

void Lpnspv2setserviceex(
  [in] HANDLE hAsyncCall,
  [in] LPGUID lpProviderId,
  [in] LPWSAQUERYSET2W lpqsRegInfo,
  [in] WSAESETSERVICEOP essOperation,
  [in] DWORD dwControlFlags,
  [in] LPVOID lpvClientSessionArg
)
{...}

パラメーター

[in] hAsyncCall

非同期呼び出しに使用された NSPv2LookupServiceBegin の前の呼び出しから返されたハンドル。

[in] lpProviderId

名前またはサービスが登録されている特定の名前空間プロバイダーの GUID へのポインター。

[in] lpqsRegInfo

登録時に更新されるプロパティ情報。

[in] essOperation

要求された操作の種類。

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

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

[in] dwControlFlags

要求された操作を制御するフラグのセット。

このパラメーターに指定できる値は、 Winsock2.h ヘッダーファイルで定義されています。

値	意味
SERVICE_MULTIPLE 0x00000001	操作のスコープを制御します。この値が設定されている場合、アクションは指定されたアドレスセットに対してのみ実行されます。登録操作では既存のアドレスは無効になりません。登録解除操作では、指定されたアドレスのセットのみが無効になります。この値がない場合、サービスアドレスはグループとして管理されます。レジスタまたは登録解除は、指定されたアドレスセットを追加する前に、既存のすべてのアドレスを無効にします。

値

意味

SERVICE_MULTIPLE

0x00000001

操作のスコープを制御します。

この値が設定されている場合、アクションは指定されたアドレスセットに対してのみ実行されます。登録操作では既存のアドレスは無効になりません。登録解除操作では、指定されたアドレスのセットのみが無効になります。

この値がない場合、サービスアドレスはグループとして管理されます。レジスタまたは登録解除は、指定されたアドレスセットを追加する前に、既存のすべてのアドレスを無効にします。

[in] lpvClientSessionArg

クライアントセッションへのポインター。

戻り値

ルーチンが成功した場合、関数は NO_ERROR (ゼロ) を返す必要があります。ルーチンが失敗し、 WSASetLastError を使用して適切なエラーコードを設定する必要がある場合は、SOCKET_ERROR (つまり 1) を返す必要があります。

エラーコード	意味
WSA_NOT_ENOUGH_MEMORY	この操作を実行するのに十分なメモリがありません。
WSAEACCES	呼び出し元ルーチンには、サービスをインストールするための十分な特権がありません。
WSAEINVAL	このプロバイダーに対して、1 つ以上のパラメーターが無効であるか、不足しています。
WSAEOPNOTSUPP	この操作はサポートされていません。名前空間プロバイダーがこの関数を実装していない場合、このエラーが返されます。このエラーは、指定された dwControlCode が認識されないコマンドである場合にも返すことができます。
WSASERVICE_NOT_FOUND	サービスが不明です。指定した名前空間にサービスが見つかりません。

注釈

NSPv2SetServiceEx 関数は、Windows Vista 以降で使用できる名前空間サービスプロバイダーバージョン 2 (NSPv2) アーキテクチャの一部として使用されます。

Windows Vista および Windows Server 2008 では、 NSPv2SetServiceEx 関数は、NS_EMAIL名前空間プロバイダーに対する操作にのみ使用できます。

NSPv2Startup 関数は、新しいクライアントプロセスが名前空間プロバイダーの使用を開始するたびに呼び出されます。プロバイダーは、 ppvClientSessionArg パラメーターが指すクライアントセッション引数を使用して、このセッションに関する情報を格納できます。このクライアントセッション引数は、lpvClientSessionArg パラメーターの NSPv2SetServiceEx 関数に渡すことができます。

NSPv2SetServiceEx 関数は、NSPv2 プロバイダーの要件に応じて省略可能です。 NSPv2SetServiceEx 関数が実装されていない場合は、常にNO_ERRORを返すスタブ関数への NSPv2 関数ポインターを指定できます。

次の表に、 essOperation パラメーターと dwControlFlags パラメーターの値の組み合わせを示します。

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

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

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

NSPv2SetServiceEx 関数が実装されていない場合、その関数の呼び出しは、WSAEOPNOTSUPP を返すスタブ関数によってインターセプトされる必要があります。 NSPV2_ROUTINE構造体の実装されていない NSPv2SetServiceEx 関数への NSPv2 関数ポインターは、スタブ関数を指している必要があります。

サービスのプロパティ

次の表 WSAQUERYSET2 メンバー名の一覧と、サービスプロパティデータの表現方法について説明します。省略可能としてラベル付けされ、NSPv2 プロバイダーの要件に依存するメンバーは、名前空間プロバイダーで使用されていない場合は**NULL** ポインターとして指定できます。

メンバー名WSAQUERYSET2	サービスプロパティの説明
Dwsize	sizeof(WSAQUERYSET2) に設定します。これはバージョン管理メカニズムです。
lpszServiceInstanceName	サービスインスタンス名を含む文字列。
lpVersion	サービスインスタンスのバージョン番号。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
lpszComment	コメント文字列。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
dwNameSpace	名前空間識別子。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
lpNSProviderId	プロバイダー識別子。名前空間プロバイダー識別子も lpProviderId パラメーターで渡されることに注意してください。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
lpszContext	階層型名前空間内のクエリの開始点。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
dwNumberOfProtocols	プロトコル制約配列内のエントリ数のサイズ (バイト単位)。このメンバーは 0 にすることができます。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
lpafpProtocols	AFPROTOCOLS 構造体の配列。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
lpszQueryString	一部の名前空間 (whois++など) では、単純なテキスト文字列に含まれる豊富な SQL のようなクエリがサポートされています。このパラメーターは、その文字列を指定するために使用されます。このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
dwNumberOfCsAddrs	lpcsaBuffer によって参照されるCSADDR_INFO構造体の配列内の要素の数。
lpcsaBuffer	サービスがリッスンしているアドレスを含む CSADDR_INFO 構造体の配列へのポインター。
dwOutputFlags	このメンバーは、NSPv2 サービスプロバイダーの要件に応じて省略可能です。
lpBlob	プロバイダー固有のエンティティへのポインター。このメンバーは、NS_EMAIL名前空間に必要です。このメンバーは省略可能であり、他の NSPv2 サービスプロバイダーの要件に応じて異なります。

**注** ワイルドカード値を示すマニフェスト定数 **IPROTOCOL_ANY** を含むには、 CSADDR_INFO 構造体の **iProtocol** メンバーを使用できます。名前空間プロバイダーは、指定されたアドレスファミリとソケットの種類に許容される値を置き換える必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	ws2spi.h