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
オペレーティング システムがネットワーク アドレス情報を照会する必要がある名前空間 (既定の名前空間のセット)。
名前空間を指定するには、次のいずれかの定数を使用します。
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
サービス名解決プロセスの側面を指定するビット フラグのセット。 次のビット フラグが定義されています。
[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 を呼び出します。
エラー コード | 意味 |
---|---|
|
lpCsaddrBuffer が指すバッファーが小さすぎて、関連するすべてのCSADDR_INFO構造体を受信できませんでした。 *lpdwBufferLength で返される値と同じ以上の大きさのバッファーを使用して関数を呼び出します。 |
注釈
この関数は、 gethostbyname 関数のより強力なバージョンです。 GetAddressByName 関数は、複数の名前サービスで動作します。
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 |