WSAAsyncGetHostByName 関数 (winsock2.h)

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

WSAAsyncGetHostByName 関数は、ホスト名に対応するホスト情報を非同期的に取得します。

メモWSAAsyncGetHostByName 関数は、複数の名前の並列解決を提供するようには設計されていません。したがって、複数の要求を発行するアプリケーションでは、同時に実行されることを想定しないでください。または、アプリケーションで別のスレッドを開始し、 getaddrinfo 関数を使用して IP バージョンに依存しない方法で名前を解決することもできます。 Windows Sockets 2 アプリケーションを作成する開発者は、 getaddrinfo 関数を使用して、IPv6 互換性へのスムーズな移行を可能にするよう促されます。

構文

HANDLE WSAAPI WSAAsyncGetHostByName(
  HWND       hWnd,
  u_int      wMsg,
  const char *name,
  char       *buf,
  int        buflen
);

パラメーター

hWnd

TBD

wMsg

TBD

name

TBD

buf

TBD

buflen

TBD

戻り値

戻り値は、非同期操作が正常に開始されたかどうかを指定します。これは、操作自体の成功または失敗を意味するものではありません。

エラーが発生しない場合、 WSAAsyncGetHostByName は、要求の非同期タスクハンドル (Windows HTASK と混同しないように) である HANDLE 型の 0 以外の値を返します。この値は、2 つの方法で使用できます。 WSACancelAsyncRequest を使用して操作を取り消すために使用することも、wParam メッセージパラメーターを調べることで非同期操作と完了メッセージを照合するために使用することもできます。

非同期操作を開始できなかった場合、 WSAAsyncGetHostByName は 0 の値を返し、 WSAGetLastError を呼び出すことで特定のエラー番号を取得できます。

次のエラーコードは、アプリケーションウィンドウがメッセージを受信したときに設定できます。前述のように、WSAGETASYNCERROR マクロを使用して、応答メッセージ内の lParam から抽出できます。

エラーコード	意味
WSAENETDOWN	ネットワークサブシステムが失敗しました。
WSAENOBUFS	バッファー領域が不足しています。
WSAEFAULT	name パラメーターまたは buf パラメーターが、プロセス・アドレス・スペースの有効な部分にありません。
WSAHOST_NOT_FOUND	権限のある応答ホストが見つかりません。
WSATRY_AGAIN	認証されていないホストが見つからない、または SERVERFAIL。
WSANO_RECOVERY	回復不可能なエラー: FORMERR、REFUSED、NOTIMP。
WSANO_DATA	有効な名前。要求された型のデータレコードはありません。

関数呼び出し時に次のエラーが発生する可能性があり、非同期操作を開始できなかったことを示します。

エラーコード	意味
WSANOTINITIALISED	この関数を使用する前に、 WSAStartup 呼び出しが正常に行われる必要があります。
WSAENETDOWN	ネットワークサブシステムが失敗しました。
WSAEINPROGRESS	ブロックしている Windows Sockets 1.1 呼び出しが進行中であるか、サービスプロバイダーがコールバック関数を処理しています。
WSAEWOULDBLOCK	現時点では、Windows ソケット実装内のリソースまたはその他の制約のため、非同期操作をスケジュールできません。

注釈

WSAAsyncGetHostByName 関数は、gethostbyname の非同期バージョンであり、ホスト名に対応するホスト名とアドレス情報を取得するために使用されます。 Windows ソケットは操作を開始し、すぐに呼び出し元に戻り、アプリケーションが操作を識別するために使用できる不透明な非同期タスクハンドルを返します。操作が完了すると、結果 (存在する場合) が呼び出し元によって提供されるバッファーにコピーされ、メッセージがアプリケーションのウィンドウに送信されます。

非同期操作が完了すると、 hWnd パラメーターによって示されるアプリケーションウィンドウは 、wMsg パラメーターでメッセージを受信します。 wParam パラメーターには、元の関数呼び出しによって返される非同期タスクハンドルが含まれています。 lParam の上位 16 ビットには、エラーコードが含まれています。エラーコードには、Winsock2.h で定義されている任意のエラーを指定できます。エラーコード 0 は、非同期操作が正常に完了したことを示します。

正常に完了すると、元の関数呼び出しに指定されたバッファーにホスト型構造体が含まれます。この構造体の要素にアクセスするには、元のバッファーアドレスを ホスト型 構造体ポインターにキャストし、必要に応じてアクセスする必要があります。

エラーコードが WSAENOBUFS の場合、元の呼び出しで buflen によって指定されたバッファーのサイズが小さすぎて、結果のすべての情報が格納されませんでした。この場合、 lParam の下位 16 ビットには、必要なすべての情報を提供するために必要なバッファーのサイズが含まれます。部分的なデータが不十分であるとアプリケーションが判断した場合、 WSAAsyncGetHostByName 関数呼び出しを、必要なすべての情報を受け取るのに十分な大きさのバッファーを使用して再発行できます (つまり、 lParam の下位 16 ビット以下)。

この関数に指定されたバッファーは、同じホスト型構造体のメンバーによって参照されるデータ領域の内容と共にホスト型構造体を構築するために、Windows ソケットによって使用されます。 WSAENOBUFS エラーを回避するには、アプリケーションで少なくとも MAXGETHOSTSTRUCT バイトのバッファーを指定する必要があります (Winsock2.h で定義されています)。

エラーコードとバッファー長は、Winsock2.h で次のように定義されているマクロ WSAGETASYNCERROR と WSAGETASYNCBUFLEN を使用して lParam から抽出する必要があります。

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

これらのマクロを使用すると、アプリケーションのソースコードの移植性が最大化されます。

WSAAsyncGetHostByName は、 gethostname の正常な呼び出しによって返される文字列を解決することが保証されます。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winsock2.h (Winsock2.h、Winsock.h を含む)
Library	Ws2_32.lib
[DLL]	Ws2_32.dll