RpcAsyncCancelCall

関数

進行中の非同期RPC呼び出しをキャンセルする。

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

シグネチャ

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

RPC_STATUS RpcAsyncCancelCall(
    RPC_ASYNC_STATE* pAsync,
    BOOL fAbort
);

パラメーター

名前	型	方向	説明
pAsync	RPC_ASYNC_STATE*	inout	非同期呼び出しの情報を格納する RPC_ASYNC_STATE 構造体へのポインターです。
fAbort	BOOL	in	TRUE の場合、呼び出しは直ちにキャンセルされます。FALSE の場合、サーバーが呼び出しを完了するまで待機します。

戻り値の型: RPC_STATUS

公式ドキュメント

クライアントは、非同期呼び出しをキャンセルするために RpcAsyncCancelCall 関数を呼び出します。

戻り値

値	意味
RPC_S_OK	キャンセル要求が処理されました。
RPC_S_INVALID_ASYNC_HANDLE	非同期ハンドルが無効です。

注意有効なエラーコードの一覧については、 RPC Return Values を参照してください。

解説(Remarks)

クライアントが非同期呼び出しのキャンセルを要求する方法には、中止型 (abortive) と 非中止型 (nonabortive) の 2 種類があります。中止型のキャンセル (fAbortCall が TRUE) では、 RpcAsyncCancelCall 関数がサーバー側とクライアント側にキャンセル通知を送信し、サーバーからの応答を待たずに非同期呼び出しが直ちにキャンセルされます。マルチスレッドアプリケーションでは、非同期呼び出しをキャンセルできるのは、その呼び出しを発行したスレッドが呼び出しから成功して戻った後に限られる点に注意してください。これは、呼び出しの発行時に同期的に失敗した後で、別のスレッドによって非同期にキャンセルされることがないようにするために必要です。一般に、非同期呼び出しが同期的に失敗した場合は、非同期にキャンセルすべきではありません。呼び出しの発行とキャンセルが異なるスレッドで行われる可能性がある場合は、クライアントアプリケーションがこの動作を保証する必要があります。

サーバーは RpcServerTestCancel を呼び出して、クライアントからのキャンセル要求を確認します。キャンセル要求が発行された時点での呼び出しの状態や、サーバーがキャンセルを確認する頻度によって、呼び出しは正常に完了する場合もあれば、完了しない場合もあります。クライアントアプリケーションは呼び出しを完了させるために RpcAsyncCompleteCall を呼び出す必要があり、その戻り値によって呼び出しが完了したか、失敗したか、キャンセルされたかが示されます。ただし、RpcAsyncCompleteCall を呼び出す前に、クライアントは元の呼び出しが完了するまで待機する必要があります。

非中止型のキャンセル (fAbortCall が FALSE) では、 RpcAsyncCancelCall 関数はサーバーにキャンセルを通知し、クライアントはサーバーが呼び出しを完了するまで待機します。組み込みのタイムアウト機構はありません。呼び出しにタイムアウトを設けたい場合は、クライアントは独自のタイムアウト機構を用いて、まず非中止型のキャンセルを発行してください。呼び出しがタイムアウトした場合は、クライアントは中止型のキャンセルを発行できます。

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

各言語での呼び出し定義

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

RPC_STATUS RpcAsyncCancelCall(
    RPC_ASYNC_STATE* pAsync,
    BOOL fAbort
);

[DllImport("RPCRT4.dll", ExactSpelling = true)]
static extern int RpcAsyncCancelCall(
    IntPtr pAsync,   // RPC_ASYNC_STATE* in/out
    bool fAbort   // BOOL
);

<DllImport("RPCRT4.dll", ExactSpelling:=True)>
Public Shared Function RpcAsyncCancelCall(
    pAsync As IntPtr,   ' RPC_ASYNC_STATE* in/out
    fAbort As Boolean   ' BOOL
) As Integer
End Function

' pAsync : RPC_ASYNC_STATE* in/out
' fAbort : BOOL
Declare PtrSafe Function RpcAsyncCancelCall Lib "rpcrt4" ( _
    ByVal pAsync As LongPtr, _
    ByVal fAbort As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RpcAsyncCancelCall = ctypes.windll.rpcrt4.RpcAsyncCancelCall
RpcAsyncCancelCall.restype = ctypes.c_int
RpcAsyncCancelCall.argtypes = [
    ctypes.c_void_p,  # pAsync : RPC_ASYNC_STATE* in/out
    wintypes.BOOL,  # fAbort : BOOL
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('RPCRT4.dll')
RpcAsyncCancelCall = Fiddle::Function.new(
  lib['RpcAsyncCancelCall'],
  [
    Fiddle::TYPE_VOIDP,  # pAsync : RPC_ASYNC_STATE* in/out
    Fiddle::TYPE_INT,  # fAbort : BOOL
  ],
  Fiddle::TYPE_INT)

#[link(name = "rpcrt4")]
extern "system" {
    fn RpcAsyncCancelCall(
        pAsync: *mut RPC_ASYNC_STATE,  // RPC_ASYNC_STATE* in/out
        fAbort: i32  // BOOL
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("RPCRT4.dll")]
public static extern int RpcAsyncCancelCall(IntPtr pAsync, bool fAbort);
"@
$api = Add-Type -MemberDefinition $sig -Name 'RPCRT4_RpcAsyncCancelCall' -Namespace Win32 -PassThru
# $api::RpcAsyncCancelCall(pAsync, fAbort)

#uselib "RPCRT4.dll"
#func global RpcAsyncCancelCall "RpcAsyncCancelCall" sptr, sptr
; RpcAsyncCancelCall varptr(pAsync), fAbort   ; 戻り値は stat
; pAsync : RPC_ASYNC_STATE* in/out -> "sptr"
; fAbort : BOOL -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "RPCRT4.dll"
#cfunc global RpcAsyncCancelCall "RpcAsyncCancelCall" var, int
; res = RpcAsyncCancelCall(pAsync, fAbort)
; pAsync : RPC_ASYNC_STATE* in/out -> "var"
; fAbort : BOOL -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "RPCRT4.dll"
#cfunc global RpcAsyncCancelCall "RpcAsyncCancelCall" sptr, int
; res = RpcAsyncCancelCall(varptr(pAsync), fAbort)
; pAsync : RPC_ASYNC_STATE* in/out -> "sptr"
; fAbort : BOOL -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。