GetAddressByNameA 関数 (nspapi.h)

  • [アーティクル]

[GetAddressByName は、Windows ソケット 2 以降では使用できません。 代わりに、「 プロトコルに依存しない名前解決」で詳しく説明されている関数を使用してください。

GetAddressByName 関数は、名前空間または既定の名前空間のセットに対してクエリを実行して、指定されたネットワーク サービスのネットワーク アドレス情報を取得します。 このプロセスは、サービス名解決と呼ばれます。 ネットワーク サービスでは、 関数を使用して、 バインド 関数で使用できるローカル アドレス情報を取得することもできます。

構文

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

パラメーター

[in] dwNameSpace

オペレーティング システムがネットワーク アドレス情報を照会する必要がある名前空間 (既定の名前空間のセット)。

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

値 意味
NS_DEFAULT
 既定の名前空間のセット。 関数は、このセット内の各名前空間に対してクエリを実行します。 既定の名前空間のセットには、通常、システムにインストールされているすべての名前空間が含まれます。 ただし、システム管理者は、セットから特定の名前空間を除外できます。 これは、ほとんどのアプリケーションが dwNameSpace に使用する必要がある値です。
NS_DNS
 ホスト名解決のためにインターネットで使用されるドメイン ネーム システム (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 ファイル内<の参照値。
NS_TCPIP_LOCAL
 ローカル TCP/IP 名前解決メカニズム。ローカル ホスト名との比較や、ホストと IP アドレスのマッピングのキャッシュ内のホスト名と IP アドレスの検索が含まれます。
 

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

[in] lpServiceType

ネットワーク サービスの種類を指定するグローバル一意識別子 (GUID) へのポインター。 Svcguid.h ヘッダー ファイルには、いくつかの GUID サービスの種類の定義と、それらを操作するためのマクロが含まれています。

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

[in, optional] lpServiceName

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

lpServiceName をNULL に設定することは、dwResolution を RES_SERVICE に設定することと同じです。 関数は 2 番目のモードで動作し、指定した型のサービスをバインドする必要があるローカル アドレスを取得します。 関数は、*lpCsaddrBuffer に格納されているCSADDR_INFO構造体の LocalAddr メンバー内にローカル アドレスを格納します。

dwResolution が RES_SERVICE に設定されている場合、関数は lpServiceName パラメーターを無視します。

dwNameSpace が NS_DNS に設定されている場合、*lpServiceName はホストの名前です。

[in, optional] lpiProtocols

プロトコル識別子の 0 で終わる配列へのポインター。 関数は、名前解決の試行を、これらのプロトコルを提供する名前空間プロバイダーに制限します。 これにより、呼び出し元は検索の範囲を制限できます。

lpiProtocols が NULL に設定されている場合、関数は使用可能なすべてのプロトコルに関する情報を取得します。

[in] dwResolution

サービス名解決プロセスの側面を指定するビット フラグのセット。 次のビット フラグが定義されています。

値 意味
RES_SERVICE
 設定した場合、関数は、指定した型のサービスをバインドする必要があるアドレスを取得します。 これは、 lpServiceName パラメーターを NULL に設定することと同じです。

このフラグが明確な場合は、通常の名前解決が行われます。
RES_FIND_MULTIPLE
 このフラグが設定されている場合、オペレーティング システムはサービスのすべての名前空間の広範な検索を実行します。 すべての適切な名前空間にサービス名の解決を求めます。 このフラグが明確な場合、オペレーティング システムは、サービス アドレスが見つかるとすぐに検索を停止します。
RES_SOFT_SEARCH
 名前空間が複数レベルの検索をサポートしている場合、このフラグは有効です。

このフラグが有効で設定されている場合、オペレーティング システムは名前空間を簡単かつ迅速に検索します。 これは、アプリケーションがサービスの検索しやすいアドレスのみを取得する必要がある場合に便利です。

このフラグが有効で明確な場合、オペレーティング システムは名前空間のより広範な検索を実行します。

[in, optional] lpServiceAsyncInfo

将来の使用のために予約済み。 は NULL に設定する必要があります。

[out] lpCsaddrBuffer

1 つ以上の CSADDR_INFO データ構造を受け取るバッファーへのポインター。 バッファーに書き込まれる構造体の数は、解決試行で見つかった情報の量によって異なります。 複数の構造が書き込まれると想定する必要がありますが、多くの場合は 1 つだけです。

[in, out] lpdwBufferLength

入力時に lpCsaddrBuffer が指すバッファーのサイズをバイト単位で指定する変数へのポインター。

出力時に、この変数には、 CSADDR_INFO 構造体の配列を格納するために必要な合計バイト数が含まれます。 この値が *lpdwBufferLength の入力値以下で、関数が成功した場合、これはバッファーに実際に格納されているバイト数です。 この値が *lpdwBufferLength の入力値より大きい場合、バッファーは小さすぎ、出力値 *lpdwBufferLength は必要最小限のバッファー サイズです。

[in, out] lpAliasBuffer

ネットワーク サービスのエイリアス情報を受信するバッファーへのポインター。

名前空間がエイリアスをサポートしている場合、関数は 、lpAliasBuffer が指すバッファーに、0 で終わる名前文字列の配列を格納します。 リストの末尾に 2 つのゼロ終端記号があります。 配列の名は、サービスのプライマリ名です。 後に続く名前はエイリアスです。 エイリアスをサポートする名前空間の例として、DNS があります。

名前空間がエイリアスをサポートしていない場合、2 つのゼロ終端記号がバッファーに格納されます。

このパラメーターは省略可能であり、 NULL に設定できます。

[in, out] lpdwAliasBufferLength

入力時に lpAliasBuffer が指すバッファーのサイズを要素 (文字) で指定する変数へのポインター。

出力時に、この変数には名前文字列の配列を格納するために必要な要素 (文字) の合計数が含まれます。 この値が *lpdwAliasBufferLength の入力値以下で、関数が成功した場合、これはバッファーに実際に格納されている要素の数です。 この値が *lpdwAliasBufferLength の入力値より大きい場合、バッファーは小さすぎ、出力値 *lpdwAliasBufferLength は必要最小限のバッファー サイズです。

lpAliasBuffer が NULL の場合、lpdwAliasBufferLength は無意味であり、NULL にすることもできます。

戻り値

関数が成功した場合、戻り値は lpCsaddrBuffer によって指CSADDR_INFOバッファーに書き込まれたデータ構造体の数です。

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

エラー コード 意味
ERROR_INSUFFICIENT_BUFFER
 lpCsaddrBuffer が指すバッファーが小さすぎて、関連するすべてのCSADDR_INFO構造体を受信できませんでした。 *lpdwBufferLength で返される値と同じ以上の大きさのバッファーを使用して関数を呼び出します。

注釈

この関数は、 gethostbyname 関数のより強力なバージョンです。 GetAddressByName 関数は、複数の名前サービスで動作します。

メモgethostbyname 関数は、getaddrinfo 関数の導入によって非推奨になりました。 Windows ソケット 2 アプリケーションを作成する開発者には、gethostbyname ではなく getaddrinfo 関数を使用するように求める必要があります。
 

GetAddressByName 関数を使用すると、クライアントはネットワーク サービスの Windows ソケット アドレスを取得できます。 クライアントは、目的のサービスをサービスの種類とサービス名で指定します。

多くの名前サービスでは、サービス名を解決するときにネーム サービス プロバイダーが考慮する既定のプレフィックスまたはサフィックスがサポートされています。 たとえば、DNS 名前空間では、ドメインの名前が "nt.microsoft.com" で、"ftp millikan" が入力として指定されている場合、DNS ソフトウェアは "ミリカン" の解決に失敗しますが、"millikan.nt.microsoft.com" は正常に解決されます。

GetAddressByName 関数は、特定の名前空間内または一連の既定の名前空間内の 2 つの方法でサービス アドレスを検索できることに注意してください。 管理者は、既定の名前空間を使用して、名前で指定されている場合にのみ、特定の名前空間でサービス アドレスを検索することを指定できます。 管理者または名前空間 - セットアップ プログラムは、名前空間検索の順序を制御することもできます。

注意

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

要件

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

こちらもご覧ください

CSADDR_INFO

Winsock 関数

Winsock リファレンス

getaddrinfo

gethostbyname