WSAAsyncGetProtoByName

WSAAsyncGetProtoByName 関数 (winsock.h) は、プロトコル名に対応するプロトコル情報を非同期に取得する。

WSAAsyncGetProtoByName hWnd, wMsg, name, buf, buflen

hWnd : [intptr] 非同期リクエストの完了時にメッセージを受け取るウィンドウのハンドル。
wMsg : [int] 非同期リクエストの完了時に受け取るメッセージ。
name : [str] 解決する、NULL 終端のプロトコル名へのポインタ。
buf : [str] protoent データを受け取るためのデータ領域へのポインタ。データ領域は、Windows Sockets が protoent 構造体とそのメンバが参照するすべてのデータを格納するために使うため、protoent 構造体のサイズより大きくなければならない。MAXGETHOSTSTRUCT バイトのバッファが推奨される。
buflen : [int] buf パラメータ用のデータ領域のサイズ (バイト単位)。

(プラグイン / モジュール : ws2_32.dll)

解説

WSAAsyncGetProtoByName 関数 (winsock.h) は、プロトコル名に対応するプロトコル情報を非同期に取得する。

[戻り値]

戻り値は、非同期操作の開始に成功したかどうかを示す。操作自体の成否を意味するものではない。エラーがない場合、WSAAsyncGetProtoByName
はそのリクエストに対する非同期タスクハンドルを表す、HANDLE 型の 0 以外の値を返す (これは Windows の HTASK
とは異なる)。この値は 2 通りの使い方ができる。WSACancelAsyncRequest
を使って操作をキャンセルするために使うか、wParam
メッセージパラメータを調べて非同期操作と完了メッセージを対応付けるために使える。非同期操作を開始できなかった場合、WSAAsyncGetProtoByName
はゼロを返し、WSAGetLastError
を呼び出すことで特定のエラー番号を取得できる。アプリケーションウィンドウがメッセージを受け取ったとき、次のエラーコードが設定されうる。前述の通り、これらは
WSAGETASYNCERROR マクロを使って返信メッセージの lParam から取り出せる。
（以下省略）

[備考]
WSAAsyncGetProtoByName 関数は getprotobyname
の非同期版である。指定したプロトコル名に対応するプロトコル名と番号を Windows Sockets
データベースから取得するために使用される。Windows Sockets
は操作を開始して直ちに呼び出し元に戻り、アプリケーションが操作を識別するのに使える不透明な非同期タスクハンドルを返す。操作が完了すると、結果
(あれば)
が呼び出し元から提供されたバッファにコピーされ、アプリケーションのウィンドウにメッセージが送信される。非同期操作が完了すると、hWnd
パラメータで指定されたアプリケーションウィンドウが wMsg パラメータで指定されたメッセージを受け取る。wParam
パラメータには元の関数呼び出しが返した非同期タスクハンドルが格納される。lParam の上位 16
ビットにはエラーコードが格納される。エラーコードは Winsock2.h
で定義された任意のエラーになりうる。エラーコードがゼロなら非同期操作が正常完了したことを示す。正常完了時には、元の関数呼び出しに指定したバッファに
protoent 構造体が格納される。エラーコードが WSAENOBUFS の場合、元の呼び出しで buflen
に指定したバッファサイズがすべての結果情報を格納するには小さすぎたことを意味する。この場合、lParam の下位 16
ビットに必要なバッファサイズが格納される。WSAENOBUFS エラーを避けるため、アプリケーションは少なくとも
MAXGETHOSTSTRUCT バイトのバッファを用意するべきである。エラーコードとバッファ長は、Winsock2.h で定義されている
WSAGETASYNCERROR および WSAGETASYNCBUFLEN マクロを使って lParam から取り出すべきである。
（以下省略）

情報