ホーム › Networking.WinSock › WPUCompleteOverlappedRequest

WPUCompleteOverlappedRequest

関数

サービスプロバイダーのオーバーラップ要求の完了を通知する。

DLLWS2_32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

INT WPUCompleteOverlappedRequest(
    SOCKET s,
    OVERLAPPED* lpOverlapped,
    DWORD dwError,
    DWORD cbTransferred,
    INT* lpErrno
);

パラメーター

名前	型	方向	説明
s	SOCKET	in	WPUCreateSocketHandle によって作成されたサービスプロバイダーのソケット。
lpOverlapped	OVERLAPPED*	inout	完了を通知するオーバーラップ I/O 操作に関連付けられた WSAOVERLAPPED 構造体へのポインター。
dwError	DWORD	in	完了を通知するオーバーラップ I/O 操作の完了ステータス。
cbTransferred	DWORD	in	クライアントバッファーとの間で転送されたバイト数(転送方向は、完了を通知するオーバーラップ I/O 操作が送信または受信のいずれであるかによって異なります)。
lpErrno	INT*	out	この関数の実行結果として得られるエラーコードへのポインター。

戻り値の型: INT

公式ドキュメント

WPUCompleteOverlappedRequest 関数は、オーバーラップ I/O 操作に対するオーバーラップ I/O 完了通知を実行します。

戻り値

エラーが発生しない場合、 WPUCompleteOverlappedRequest はゼロを返し、クライアントが選択したメカニズムに従ってオーバーラップ I/O 操作の完了を通知します(lpOverlapped が参照する WSAOVERLAPPED 構造体内のイベントをシグナル状態にする、または完了ポートがソケットに関連付けられている場合はその完了ポートに完了ステータスレポートをキューに登録します)。それ以外の場合、 WPUCompleteOverlappedRequest は SOCKET_ERROR を返し、特定のエラーコードが lpErrno で取得できます。

エラーコード	意味
WSAEINVAL	s パラメーターで渡されたソケットが、 WPUCreateSocketHandle によって作成されたソケットではありません。

解説(Remarks)

WPUCompleteOverlappedRequest 関数は、クライアントが指定した完了メカニズムがユーザーモードの非同期プロシージャ呼び出し(APC)以外である場合に、オーバーラップ I/O 操作に対するオーバーラップ I/O 完了通知を実行します。この関数は、 WPUCreateSocketHandle によって作成されたソケットハンドルに対してのみ使用できます。

**注意** この関数は、"WPU" プレフィックスを持つ他の関数とは異なり、アップコールテーブルを介してアクセスされません。代わりに Ws2_32.dll によって直接エクスポートされます。この関数を呼び出す必要があるサービスプロバイダーは、WS2_32.lib をリンクするか、LoadLibrary や GetProcAddress などの適切なオペレーティングシステム関数を使用して関数ポインターを取得する必要があります。

WPUCompleteOverlappedRequest 関数は、公開するソケットハンドルに対してインストール可能ファイルシステム(IFS)機能を直接実装していないサービスプロバイダーによって使用されます。この関数は、指定された完了通知がユーザーモード APC 以外であるすべてのオーバーラップ I/O 要求に対して完了通知を実行します。 WPUCompleteOverlappedRequest は、 WPUCreateSocketHandle によって作成されたソケットハンドルに対してのみサポートされ、サービスプロバイダーが直接作成したソケットに対してはサポートされません。

クライアントが通知方法としてユーザーモード APC を選択した場合、サービスプロバイダーは WPUQueueApc または他の適切なオペレーティングシステム関数を使用して完了通知を実行する必要があります。クライアントがユーザーモード APC を選択しない場合、IFS 機能を直接実装していないサービスプロバイダーは、クライアントがソケットハンドルに完了ポートを関連付けたかどうかを判断できません。したがって、完了通知方法が完了ポートへの完了ステータスレコードのキュー登録であるべきか、それとも WSAOVERLAPPED 構造体内のイベントのシグナル状態への設定であるべきかを判断できません。Windows Socket 2 アーキテクチャは、 WPUCreateSocketHandle によって作成されたソケットに対する完了ポートの関連付けを追跡し、完了ポートベースの通知とイベントベースの通知の間で正しい判断を行うことができます。

WPUCompleteOverlappedRequest が完了通知をキューに登録するとき、 WSAOVERLAPPED 構造体の InternalHigh メンバーに転送されたバイト数を設定します。次に、Internal メンバーに特別な値 WSS_OPERATION_IN_PROGRESS 以外の OS 依存の値を設定します。処理が非同期に行われる場合があるため、WPUCompleteOverlappedRequest が戻ってからこれらの値が現れるまでにわずかな遅延が生じることがあります。ただし、InternalHigh の値(バイト数)は Internal が設定される時点までに設定されることが保証されています。

WPUCompleteOverlappedRequest は、ソケットハンドルが完了ポートに関連付けられているかどうかにかかわらず、記載されたとおりに(クライアントが要求した完了通知を)動作します。

WSPGetOverlappedResult との連携

WPUCompleteOverlappedRequest の動作は、サービスプロバイダーが WSPGetOverlappedResult を実装する方法にいくつかの制約を課します。なぜなら、 WSAOVERLAPPED 構造体のうちサービスプロバイダーが排他的に制御するのは Offset メンバーと OffsetHigh メンバーのみであるにもかかわらず、 WSPGetOverlappedResult は構造体から 3 つの値(バイト数、フラグ、エラー)を取得する必要があるためです。サービスプロバイダーは、 WPUCompleteOverlappedRequest の動作と適切に連携する限り、任意の方法でこれを実現できます。ただし、一般的な実装は次のとおりです。

オーバーラップ処理の開始時に、サービスプロバイダーは Internal に WSS_OPERATION_IN_PROGRESS を設定します。
I/O 操作が完了すると、プロバイダーは OffsetHigh に操作の結果として得られた Windows Socket 2 エラーコードを設定し、Offset に I/O 操作の結果として得られたフラグを設定し、転送バイト数をパラメーターの 1 つとして渡して WPUCompleteOverlappedRequest を呼び出します。 WPUCompleteOverlappedRequest は最終的に InternalHigh に転送バイト数を設定し、次に Internal に WSS_OPERATION_IN_PROGRESS 以外の値を設定します。
WSPGetOverlappedResult が呼び出されると、サービスプロバイダーは Internal を確認します。それが WSS_OPERATION_IN_PROGRESS である場合、プロバイダーは WSPGetOverlappedResult の FWAIT フラグの設定に基づいて、hEvent メンバー内のイベントハンドルで待機するか、エラーを返します。処理中でない場合、または待機の完了後、プロバイダーは InternalHigh、OffsetHigh、Offset の値をそれぞれ転送数、操作結果のエラーコード、フラグとして返します。

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

各言語での呼び出し定義

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

INT WPUCompleteOverlappedRequest(
    SOCKET s,
    OVERLAPPED* lpOverlapped,
    DWORD dwError,
    DWORD cbTransferred,
    INT* lpErrno
);

[DllImport("WS2_32.dll", ExactSpelling = true)]
static extern int WPUCompleteOverlappedRequest(
    UIntPtr s,   // SOCKET
    IntPtr lpOverlapped,   // OVERLAPPED* in/out
    uint dwError,   // DWORD
    uint cbTransferred,   // DWORD
    out int lpErrno   // INT* out
);

<DllImport("WS2_32.dll", ExactSpelling:=True)>
Public Shared Function WPUCompleteOverlappedRequest(
    s As UIntPtr,   ' SOCKET
    lpOverlapped As IntPtr,   ' OVERLAPPED* in/out
    dwError As UInteger,   ' DWORD
    cbTransferred As UInteger,   ' DWORD
    <Out> ByRef lpErrno As Integer   ' INT* out
) As Integer
End Function

' s : SOCKET
' lpOverlapped : OVERLAPPED* in/out
' dwError : DWORD
' cbTransferred : DWORD
' lpErrno : INT* out
Declare PtrSafe Function WPUCompleteOverlappedRequest Lib "ws2_32" ( _
    ByVal s As LongPtr, _
    ByVal lpOverlapped As LongPtr, _
    ByVal dwError As Long, _
    ByVal cbTransferred As Long, _
    ByRef lpErrno As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WPUCompleteOverlappedRequest = ctypes.windll.ws2_32.WPUCompleteOverlappedRequest
WPUCompleteOverlappedRequest.restype = ctypes.c_int
WPUCompleteOverlappedRequest.argtypes = [
    ctypes.c_size_t,  # s : SOCKET
    ctypes.c_void_p,  # lpOverlapped : OVERLAPPED* in/out
    wintypes.DWORD,  # dwError : DWORD
    wintypes.DWORD,  # cbTransferred : DWORD
    ctypes.POINTER(ctypes.c_int),  # lpErrno : INT* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WS2_32.dll')
WPUCompleteOverlappedRequest = Fiddle::Function.new(
  lib['WPUCompleteOverlappedRequest'],
  [
    Fiddle::TYPE_UINTPTR_T,  # s : SOCKET
    Fiddle::TYPE_VOIDP,  # lpOverlapped : OVERLAPPED* in/out
    -Fiddle::TYPE_INT,  # dwError : DWORD
    -Fiddle::TYPE_INT,  # cbTransferred : DWORD
    Fiddle::TYPE_VOIDP,  # lpErrno : INT* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ws2_32")]
extern "system" {
    fn WPUCompleteOverlappedRequest(
        s: usize,  // SOCKET
        lpOverlapped: *mut OVERLAPPED,  // OVERLAPPED* in/out
        dwError: u32,  // DWORD
        cbTransferred: u32,  // DWORD
        lpErrno: *mut i32  // INT* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WS2_32.dll")]
public static extern int WPUCompleteOverlappedRequest(UIntPtr s, IntPtr lpOverlapped, uint dwError, uint cbTransferred, out int lpErrno);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WS2_32_WPUCompleteOverlappedRequest' -Namespace Win32 -PassThru
# $api::WPUCompleteOverlappedRequest(s, lpOverlapped, dwError, cbTransferred, lpErrno)

#uselib "WS2_32.dll"
#func global WPUCompleteOverlappedRequest "WPUCompleteOverlappedRequest" sptr, sptr, sptr, sptr, sptr
; WPUCompleteOverlappedRequest s, varptr(lpOverlapped), dwError, cbTransferred, varptr(lpErrno)   ; 戻り値は stat
; s : SOCKET -> "sptr"
; lpOverlapped : OVERLAPPED* in/out -> "sptr"
; dwError : DWORD -> "sptr"
; cbTransferred : DWORD -> "sptr"
; lpErrno : INT* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WS2_32.dll"
#cfunc global WPUCompleteOverlappedRequest "WPUCompleteOverlappedRequest" sptr, var, int, int, var
; res = WPUCompleteOverlappedRequest(s, lpOverlapped, dwError, cbTransferred, lpErrno)
; s : SOCKET -> "sptr"
; lpOverlapped : OVERLAPPED* in/out -> "var"
; dwError : DWORD -> "int"
; cbTransferred : DWORD -> "int"
; lpErrno : INT* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WS2_32.dll"
#cfunc global WPUCompleteOverlappedRequest "WPUCompleteOverlappedRequest" sptr, sptr, int, int, sptr
; res = WPUCompleteOverlappedRequest(s, varptr(lpOverlapped), dwError, cbTransferred, varptr(lpErrno))
; s : SOCKET -> "sptr"
; lpOverlapped : OVERLAPPED* in/out -> "sptr"
; dwError : DWORD -> "int"
; cbTransferred : DWORD -> "int"
; lpErrno : INT* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。