WSAAsyncGetHostByAddr 関数 (winsock2.h)

  • [アーティクル]

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

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

構文

HANDLE WSAAPI WSAAsyncGetHostByAddr(
  HWND       hWnd,
  u_int      wMsg,
  const char *addr,
  int        len,
  int        type,
  char       *buf,
  int        buflen
);

パラメーター

hWnd

TBD

wMsg

TBD

addr

TBD

len

TBD

type

TBD

buf

TBD

buflen

TBD

戻り値

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

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

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

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

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

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

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

解説

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

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

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

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

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

要件

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

関連項目

WSACancelAsyncRequest

Winsock 関数

Winsock リファレンス

getaddrinfo

gethostbyaddr

getnameinfo

hostent