GetServiceA 関数 (nspapi.h)

  • [アーティクル]

GetService 関数は、一連の既定の名前空間または指定された名前空間のコンテキストで、ネットワーク サービスに関する情報を取得します。 ネットワーク サービスは、その種類と名前で指定されます。 サービスに関する情報は、 NS_SERVICE_INFO データ構造のセットとして取得されます。

メモGetService 関数は、Windows ソケット 1.1 仕様に対する Microsoft 固有の拡張機能です。 この関数は、現在使用されていません。 Windows Sockets 1.1 開発者の便宜のために、このリファレンス 資料が含まれています。
 
メモ「プロトコルに依存しない名前解決」で詳しく説明されている関数は、Windows ソケット 2 で同等の機能を提供します。
 

構文

INT GetServiceA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpGuid,
  [in]           LPSTR                lpServiceName,
  [in]           DWORD                dwProperties,
  [out]          LPVOID               lpBuffer,
  [in, out]      LPDWORD              lpdwBufferSize,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo
);

パラメーター

[in] dwNameSpace

オペレーティング システムが指定されたネットワーク サービスに関する情報を照会する名前空間または既定の名前空間のセット。

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

値 意味
NS_DEFAULT
 既定の名前空間のセット。 オペレーティング システムは、このセット内の各名前空間に対してクエリを実行します。 既定の名前空間のセットには、通常、システムにインストールされているすべての名前空間が含まれます。 ただし、システム管理者は、セットから特定の名前空間を除外できます。 NS_DEFAULTは、ほとんどのアプリケーションが dwNameSpace に使用する必要がある値です。
NS_DNS
 ホスト名解決のためにインターネットで使用されるドメイン ネーム システム。
NS_NETBT
 TCP/IP 経由の NetBIOS レイヤー。 すべてのオペレーティング システムは、コンピューター名を NetBIOS に登録します。 この名前空間は、この登録を使用してコンピューター名を IP アドレスに解決するために使用されます。 NS_NETBT WINS サーバーにアクセスして解決を実行できることに注意してください。
NS_SAP
 NetWare サービスアドバタイズ プロトコル。 これにより、必要に応じて NetWare バインダーにアクセスできます。 NS_SAPは、サービスの登録を許可する動的名前空間です。
NS_TCPIP_HOSTS
 systemroot>\system32\drivers\etc\hosts ファイルで<ホスト名と IP アドレスを検索します。
NS_TCPIP_LOCAL
 ローカル TCP/IP 名前解決メカニズム。ローカル ホスト名との比較や、ホストと IP アドレスのマッピングのキャッシュ内のホスト名と IP アドレスの検索が含まれます。
 

GetService のほとんどの呼び出しでは、特別な値NS_DEFAULTを使用する必要があります。 これにより、クライアントはインターネットワークで使用可能な名前空間を知らずに取得できます。 システム管理者が名前空間へのアクセスを決定します。 名前空間は、クライアントが変更を認識しなくても行き来できます。

[in] lpGuid

ネットワーク サービスの種類を指定するグローバル一意識別子 (GUID) へのポインター。 Svcguid.h ヘッダー ファイルには、DNS および SAP 名前空間内の多くの既知のサービスからの GUID サービスの種類が含まれています。

Svcguid.h ヘッダー ファイルは、Winsock2.h ヘッダー ファイルに自動的に含まれません。

[in] lpServiceName

サービス名を一意に表す 0 で終わる文字列へのポインター。 たとえば、"MY SNA SERVER" などです。

[in] dwProperties

関数が取得するサービス情報を指定するビット フラグのセット。 これらの各ビット フラグ定数は、PROP_ALL以外の、 SERVICE_INFO データ構造の特定のメンバーに対応します。 フラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造体の対応するメンバーに情報を格納します。 次のビット フラグが定義されています。

値 意味
PROP_COMMENT
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造の lpComment メンバーにデータを格納します。
PROP_LOCALE
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造体の lpLocale メンバーにデータを格納します。
PROP_DISPLAY_HINT
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造の dwDisplayHint メンバーにデータを格納します。
PROP_VERSION
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造の dwVersion メンバーにデータを格納します。
PROP_START_TIME
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造の dwTime メンバーにデータを格納します。
PROP_MACHINE
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造の lpMachineName メンバーにデータを格納します。
PROP_ADDRESSES
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造体の lpServiceAddress メンバーにデータを格納します。
PROP_SD
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造の ServiceSpecificInfo メンバーにデータを格納します。
PROP_ALL
 このフラグが設定されている場合、関数は *lpBuffer に格納されているデータ構造のすべてのメンバーにデータを格納します。

[out] lpBuffer

NS_SERVICE_INFO構造体と関連するサービス情報の配列を受け取るバッファーへのポインター。 各 NS_SERVICE_INFO 構造体には、特定の名前空間のコンテキストでサービス情報が含まれています。 dwNameSpace がNS_DEFAULT場合、関数は複数の構造体をバッファーに格納します。それ以外の場合は、1 つの構造体だけが格納されます。

各 NS_SERVICE_INFO 構造体には、 SERVICE_INFO 構造体が含まれています。 これらの SERVICE_INFO 構造体のメンバーには、 dwProperties パラメーターで設定されているビット フラグに基づく有効なデータが含まれます。 dwProperties でメンバーの対応するビット フラグが設定されていない場合、メンバーの値は未定義です。

関数は、バッファーの先頭から開始して、連続する配列に NS_SERVICE_INFO 構造体を格納します。 格納されている SERVICE_INFO 構造体内のポインターは、NS_SERVICE_INFO構造体の末尾とバッファーの末尾の間のバッファーに格納されている情報を指します。

[in, out] lpdwBufferSize

入力時に lpBuffer が指すバッファーのサイズ (バイト単位) を含む変数へのポインター。 出力時に、この変数には、要求された情報を格納するために必要なバイト数が含まれます。 この出力値が入力値より大きい場合、バッファー サイズが不足しているため、関数は失敗しました。

[in, optional] lpServiceAsyncInfo

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

戻り値

関数が成功した場合、戻り値は *lpBuffer に格納されているNS_SERVICE_INFO構造体の数です。 ゼロは、構造体が格納されなかったことを示します。

関数が失敗した場合、戻り値は SOCKET_ERROR ( – 1) になります。 拡張エラー情報を取得するには、次のいずれかの拡張エラー値を返す GetLastError を呼び出します。

エラー コード 意味
ERROR_INSUFFICIENT_BUFFER
 lpBuffer が指すバッファーが小さすぎて、要求されたすべての情報を受信できません。 *lpdwBufferSize で返される値と同じ以上の大きさのバッファーを使用して関数を呼び出します。
ERROR_SERVICE_NOT_FOUND
 指定したサービスが見つからなかったか、指定された名前空間が使用されていません。 この場合、関数の戻り値は 0 です。

注釈

注意

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

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー nspapi.h
Library Mswsock.lib
[DLL] Mswsock.dll

こちらもご覧ください

NS_SERVICE_INFO

SERVICE_INFO

SetService

Winsock 関数

Winsock リファレンス