ホーム › Networking.WinSock › WSAAsyncGetProtoByNumber

WSAAsyncGetProtoByNumber

関数

プロトコル番号のプロトコル情報を非同期で取得する。

DLLWS2_32.dll呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// WS2_32.dll
#include <windows.h>

HANDLE WSAAsyncGetProtoByNumber(
    HWND hWnd,
    DWORD wMsg,
    INT number,
    LPSTR buf,
    INT buflen
);

パラメーター

名前	型	方向	説明
hWnd	HWND	in	非同期要求が完了したときにメッセージを受け取るウィンドウのハンドルです。
wMsg	DWORD	in	非同期要求が完了したときに受け取るメッセージです。
number	INT	in	解決するプロトコル番号です。ホストバイトオーダーで指定します。
buf	LPSTR	out	protoent データを受け取るデータ領域へのポインターです。Windows Sockets はこのデータ領域に protoent 構造体と、その protoent 構造体のメンバーから参照されるすべてのデータを格納するため、データ領域は protoent 構造体のサイズより大きくする必要があります。MAXGETHOSTSTRUCT バイトのバッファーを使用することを推奨します。
buflen	INT	in	buf パラメーターのデータ領域のサイズ (バイト単位) です。

戻り値の型: HANDLE

公式ドキュメント

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

戻り値

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

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

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

アプリケーションのウィンドウがメッセージを受け取ったときには、次のエラーコードが設定される場合があります。前述のとおり、これらは応答メッセージの lParam から WSAGETASYNCERROR マクロを使用して取り出すことができます。

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

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

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

解説(Remarks)

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

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

正常に完了すると、元の関数呼び出しで指定したバッファーには protoent 構造体が格納されます。この構造体のメンバーにアクセスするには、元のバッファーアドレスを protoent 構造体ポインターにキャストし、適宜アクセスします。

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

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

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

#include <windows.h>

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

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// WS2_32.dll
#include <windows.h>

HANDLE WSAAsyncGetProtoByNumber(
    HWND hWnd,
    DWORD wMsg,
    INT number,
    LPSTR buf,
    INT buflen
);

[DllImport("WS2_32.dll", SetLastError = true, ExactSpelling = true)]
static extern IntPtr WSAAsyncGetProtoByNumber(
    IntPtr hWnd,   // HWND
    uint wMsg,   // DWORD
    int number,   // INT
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder buf,   // LPSTR out
    int buflen   // INT
);

<DllImport("WS2_32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function WSAAsyncGetProtoByNumber(
    hWnd As IntPtr,   ' HWND
    wMsg As UInteger,   ' DWORD
    number As Integer,   ' INT
    <MarshalAs(UnmanagedType.LPStr)> buf As System.Text.StringBuilder,   ' LPSTR out
    buflen As Integer   ' INT
) As IntPtr
End Function

' hWnd : HWND
' wMsg : DWORD
' number : INT
' buf : LPSTR out
' buflen : INT
Declare PtrSafe Function WSAAsyncGetProtoByNumber Lib "ws2_32" ( _
    ByVal hWnd As LongPtr, _
    ByVal wMsg As Long, _
    ByVal number As Long, _
    ByVal buf As String, _
    ByVal buflen As Long) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WSAAsyncGetProtoByNumber = ctypes.windll.ws2_32.WSAAsyncGetProtoByNumber
WSAAsyncGetProtoByNumber.restype = ctypes.c_void_p
WSAAsyncGetProtoByNumber.argtypes = [
    wintypes.HANDLE,  # hWnd : HWND
    wintypes.DWORD,  # wMsg : DWORD
    ctypes.c_int,  # number : INT
    wintypes.LPSTR,  # buf : LPSTR out
    ctypes.c_int,  # buflen : INT
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WS2_32.dll')
WSAAsyncGetProtoByNumber = Fiddle::Function.new(
  lib['WSAAsyncGetProtoByNumber'],
  [
    Fiddle::TYPE_VOIDP,  # hWnd : HWND
    -Fiddle::TYPE_INT,  # wMsg : DWORD
    Fiddle::TYPE_INT,  # number : INT
    Fiddle::TYPE_VOIDP,  # buf : LPSTR out
    Fiddle::TYPE_INT,  # buflen : INT
  ],
  Fiddle::TYPE_VOIDP)

#[link(name = "ws2_32")]
extern "system" {
    fn WSAAsyncGetProtoByNumber(
        hWnd: *mut core::ffi::c_void,  // HWND
        wMsg: u32,  // DWORD
        number: i32,  // INT
        buf: *mut u8,  // LPSTR out
        buflen: i32  // INT
    ) -> *mut core::ffi::c_void;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WS2_32.dll", SetLastError = true)]
public static extern IntPtr WSAAsyncGetProtoByNumber(IntPtr hWnd, uint wMsg, int number, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder buf, int buflen);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_WSAAsyncGetProtoByNumber' -Namespace Win32 -PassThru
# $api::WSAAsyncGetProtoByNumber(hWnd, wMsg, number, buf, buflen)

#uselib "WS2_32.dll"
#func global WSAAsyncGetProtoByNumber "WSAAsyncGetProtoByNumber" sptr, sptr, sptr, sptr, sptr
; WSAAsyncGetProtoByNumber hWnd, wMsg, number, varptr(buf), buflen   ; 戻り値は stat
; hWnd : HWND -> "sptr"
; wMsg : DWORD -> "sptr"
; number : INT -> "sptr"
; buf : LPSTR out -> "sptr"
; buflen : INT -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WS2_32.dll"
#cfunc global WSAAsyncGetProtoByNumber "WSAAsyncGetProtoByNumber" sptr, int, int, var, int
; res = WSAAsyncGetProtoByNumber(hWnd, wMsg, number, buf, buflen)
; hWnd : HWND -> "sptr"
; wMsg : DWORD -> "int"
; number : INT -> "int"
; buf : LPSTR out -> "var"
; buflen : INT -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WS2_32.dll"
#cfunc global WSAAsyncGetProtoByNumber "WSAAsyncGetProtoByNumber" sptr, int, int, sptr, int
; res = WSAAsyncGetProtoByNumber(hWnd, wMsg, number, varptr(buf), buflen)
; hWnd : HWND -> "sptr"
; wMsg : DWORD -> "int"
; number : INT -> "int"
; buf : LPSTR out -> "sptr"
; buflen : INT -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。