WSAAsyncGetProtoByName 関数 (winsock.h)

  • [アーティクル]

WSAAsyncGetProtoByName 関数は、プロトコル名に対応するプロトコル情報を非同期的に取得します。

構文

HANDLE WSAAsyncGetProtoByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [out] char       *buf,
  [out] int        buflen
);

パラメーター

[in] hWnd

非同期要求が完了したときにメッセージを受信するウィンドウのハンドル。

[in] wMsg

非同期要求が完了したときに受信するメッセージ。

[in] name

解決する null で終わるプロトコル名へのポインター。

[out] buf

原産データを受信するデータ領域へのポインター。 データ領域は、データ領域が Windows ソケットによって使用され、原産構造のメンバーによって参照されるすべてのデータが格納されるため、データ領域は原産構造のサイズよりも大きくする必要があります。 MAXGETHOSTSTRUCT バイトのバッファーをお勧めします。

[out] buflen

buf パラメーターのデータ領域のサイズ (バイト単位)。

戻り値

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

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

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

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

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

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

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

注釈

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

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

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

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

こちらもご覧ください

WSACancelAsyncRequest

Winsock 関数

Winsock リファレンス

getprotobyname