ホーム › Storage.OperationRecorder › OperationStart

OperationStart

関数

プリフェッチ最適化用に操作記録の開始を通知する。

DLLADVAPI32.dll呼出規約winapi対応OSwindows8.0

シグネチャ

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

BOOL OperationStart(
    OPERATION_START_PARAMETERS* OperationStartParams
);

パラメーター

名前	型	方向	説明
OperationStartParams	OPERATION_START_PARAMETERS*	in	VERSION、OPERATION_ID、FLAGS を指定する _OPERATION_START_PARAMETERS 構造体です。

戻り値の型: BOOL

公式ドキュメント

アプリケーションが操作を開始しようとしていることをシステムに通知します。

戻り値

すべてのパラメーターが有効な場合は TRUE、それ以外の場合は FALSE を返します。拡張エラー情報を取得するには、GetLastError を呼び出します。

解説(Remarks)

_OPERATION_START_PARAMETERS 構造体のバージョンは、Windows SDK で OPERATION_API_VERSION として定義されています。

OperationStart 関数は同期的であるため、戻るまでに数秒かかることがあります。応答性を最良に保つため、UI スレッドでの呼び出しは避けてください。

プロセス内に操作レコーダーのインスタンスは 1 つだけ存在します。操作レコーダー API はプロセス内の複数のスレッドから呼び出せますが、すべての呼び出しはこの単一のインスタンスに対して作用します。

アプリケーション起動のトレースは、プロセスの有効期間の最初の 10 秒間だけ行われます。 OperationStart は、システムによるアプリケーション起動トレースが終了した後に呼び出してください。

OperationStart を呼び出した場合は、必ず OperationEnd の呼び出しを続ける必要があります。そうしないと、操作トレースは約 10 秒後に破棄されます。

特定のシステムで記録できる操作の最大数は構成可能です。この最大数を超えると、最も長く使用されていないプリフェッチファイルが置き換えられます。

Windows 8 では、この機能を使用するために Superfetch サービスが有効になっている必要があります。Windows 8 では、既定でこのサービスが有効になっています。 Windows Server 2012 では、このプリフェッチ機能を必要に応じて有効化および無効化する必要があります。これは CIM ベースの PowerShell コマンドレットを使用して行えます。プリフェッチャー機能は、CIM_PrefetcherService の CIM クラスを使用して公開できます。

例

    BOOL Success;
    DWORD ErrorCode;
    OPERATION_START_PARAMETERS OpStart;
    OPERATION_END_PARAMETERS OpEnd;

    // 同じファイル データに繰り返しアクセスするディスク主体の処理を          
    // これから実行することを Windows に通知します。システムは、以降の操作を 
    // 高速化するために、この処理に関するデータの記録を試みます。    
    
    ZeroMemory(&OpStart, sizeof(OpStart));
    OpStart.Version = OPERATION_API_VERSION;
    OpStart.OperationId = MY_OPERATION_ID_1;

    ZeroMemory(&OpEnd, sizeof(OpEnd));
    OpEnd.Version = OPERATION_API_VERSION;
    OpEnd.OperationId = MY_OPERATION_ID_1;
 
    // このスレッド内のアクティビティのみを記録するようにシステムに指示します。

    OpStart.Flags = OPERATION_START_TRACE_CURRENT_THREAD;
    OpEnd.Flags = 0;

    Success = OperationStart(&OpStart);

    if (!Success) {
        ErrorCode = GetLastError();
        fprintf(stderr, "OperationStart failed: %d\n", ErrorCode);

        // 操作についてシステムに通知できませんでした。それでも問題ありません。
  
                  }

    // ここで、記録対象となるディスク主体の処理を実行します。  
    // これには、多数のファイルを開いて読み取る処理や、     
    // 多数の DLL を読み込んで実行する処理が含まれる場合があります。                                    

    Success = OperationEnd(&OpEnd);

    if (!Success) {
        fprintf(stderr, "OperationEnd failed: %d\n", GetLastError());
                  }

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

各言語での呼び出し定義

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

BOOL OperationStart(
    OPERATION_START_PARAMETERS* OperationStartParams
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", ExactSpelling = true)]
static extern bool OperationStart(
    IntPtr OperationStartParams   // OPERATION_START_PARAMETERS*
);

<DllImport("ADVAPI32.dll", ExactSpelling:=True)>
Public Shared Function OperationStart(
    OperationStartParams As IntPtr   ' OPERATION_START_PARAMETERS*
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' OperationStartParams : OPERATION_START_PARAMETERS*
Declare PtrSafe Function OperationStart Lib "advapi32" ( _
    ByVal OperationStartParams As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

OperationStart = ctypes.windll.advapi32.OperationStart
OperationStart.restype = wintypes.BOOL
OperationStart.argtypes = [
    ctypes.c_void_p,  # OperationStartParams : OPERATION_START_PARAMETERS*
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
OperationStart = Fiddle::Function.new(
  lib['OperationStart'],
  [
    Fiddle::TYPE_VOIDP,  # OperationStartParams : OPERATION_START_PARAMETERS*
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn OperationStart(
        OperationStartParams: *mut OPERATION_START_PARAMETERS  // OPERATION_START_PARAMETERS*
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll")]
public static extern bool OperationStart(IntPtr OperationStartParams);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_OperationStart' -Namespace Win32 -PassThru
# $api::OperationStart(OperationStartParams)

#uselib "ADVAPI32.dll"
#func global OperationStart "OperationStart" sptr
; OperationStart varptr(OperationStartParams)   ; 戻り値は stat
; OperationStartParams : OPERATION_START_PARAMETERS* -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global OperationStart "OperationStart" var
; res = OperationStart(OperationStartParams)
; OperationStartParams : OPERATION_START_PARAMETERS* -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global OperationStart "OperationStart" sptr
; res = OperationStart(varptr(OperationStartParams))
; OperationStartParams : OPERATION_START_PARAMETERS* -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。