Win32 API 日本語リファレンス
ホーム › System.AddressBook › FtgRegisterIdleRoutine

FtgRegisterIdleRoutine

関数
アイドル時に呼び出されるルーチンを登録する。
DLLMAPI32.dll呼出規約winapi

シグネチャ

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

void* FtgRegisterIdleRoutine(
    PFNIDLE lpfnIdle,
    void* lpvIdleParam,
    SHORT priIdle,
    DWORD csecIdle,
    WORD iroIdle
);

パラメーター

名前型方向説明
lpfnIdlePFNIDLEinアイドル時に呼び出すPFNIDLEコールバック関数へのポインタ。
lpvIdleParamvoid*inoutコールバックへ渡す任意のコンテキストデータへのポインタ。NULL可。
priIdleSHORTinアイドルルーチンの実行優先度を示すSHORT値。値が大きいほど優先される。
csecIdleDWORDin呼び出し間隔をミリ秒単位で示すDWORD値。
iroIdleWORDinルーチンの実行制御フラグを示すWORD値。初回実行や有効状態などを指定する。

戻り値の型: void*

公式ドキュメント

FNIDLE 関数ベースのアイドルルーチンを MAPI システムに追加します。FtgRegisterIdleRoutine がアイドルルーチンを登録できない場合は、NULL を返します。

戻り値

FtgRegisterIdleRoutine 関数は、MAPI システムに追加されたアイドルルーチンを識別する関数タグを返します。メモリの問題などが原因で、クライアントアプリケーションまたはサービスプロバイダーのアイドルルーチンを FtgRegisterIdleRoutine が登録できない場合は、NULL を返します。

解説(Remarks)

MAPI アイドルエンジン、および FNIDLE 関数プロトタイプに基づくアイドルルーチンを扱う関数は次のとおりです。

アイドルルーチン関数 用途
ChangeIdleRoutine
登録済みのアイドルルーチンの特性を変更します。
DeregisterIdleRoutine
登録済みのアイドルルーチンを MAPI システムから削除します。
EnableIdleRoutine
登録済みのアイドルルーチンを MAPI システムから削除せずに、無効化または再度有効化します。
FtgRegisterIdleRoutine
アイドルルーチンを、有効化するかどうかを指定して MAPI システムに追加します。
MAPIDeInitIdle
呼び出し元アプリケーションの MAPI アイドルエンジンをシャットダウンします。
MAPIInitIdle
呼び出し元アプリケーションの MAPI アイドルエンジンを初期化します。

ChangeIdleRoutine、DeregisterIdleRoutine、EnableIdleRoutine は、FtgRegisterIdleRoutine が返す関数タグを入力パラメーターとして受け取ります。

プラットフォーム上のすべてのフォアグラウンドタスクがアイドル状態になると、MAPI アイドルエンジンは、実行可能な状態にあるアイドルルーチンのうち最も優先度の高いものを呼び出します。同じ優先度のアイドルルーチン間では、呼び出し順序は保証されません。

次に、iroIdle パラメーターで FIRONOADJUSTMENT フラグを使用する例を示します。

  1. 5 分の遅延を指定してアイドルルーチンを登録します。

  2. 1 分後にコンピューターを休止状態/スリープにします (タイマーの残り時間は 4 分)。

  3. 10 分後にコンピューターを再開します。

FIRONOADJUSTMENT を指定しない既定の動作では、ルーチンが実行されるまでさらに 4 分待つ必要があります。つまり、コンピューターがスリープしていた時間を考慮してタイマーが調整されます。これに対し、FIRONOADJUSTMENT を渡した場合は、実時間で 5 分を超えて経過しているため、アイドルルーチンはただちに実行されます。

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

各言語での呼び出し定義

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

void* FtgRegisterIdleRoutine(
    PFNIDLE lpfnIdle,
    void* lpvIdleParam,
    SHORT priIdle,
    DWORD csecIdle,
    WORD iroIdle
);
[DllImport("MAPI32.dll", ExactSpelling = true)]
static extern IntPtr FtgRegisterIdleRoutine(
    IntPtr lpfnIdle,   // PFNIDLE
    IntPtr lpvIdleParam,   // void* in/out
    short priIdle,   // SHORT
    uint csecIdle,   // DWORD
    ushort iroIdle   // WORD
);
<DllImport("MAPI32.dll", ExactSpelling:=True)>
Public Shared Function FtgRegisterIdleRoutine(
    lpfnIdle As IntPtr,   ' PFNIDLE
    lpvIdleParam As IntPtr,   ' void* in/out
    priIdle As Short,   ' SHORT
    csecIdle As UInteger,   ' DWORD
    iroIdle As UShort   ' WORD
) As IntPtr
End Function
' lpfnIdle : PFNIDLE
' lpvIdleParam : void* in/out
' priIdle : SHORT
' csecIdle : DWORD
' iroIdle : WORD
Declare PtrSafe Function FtgRegisterIdleRoutine Lib "mapi32" ( _
    ByVal lpfnIdle As LongPtr, _
    ByVal lpvIdleParam As LongPtr, _
    ByVal priIdle As Integer, _
    ByVal csecIdle As Long, _
    ByVal iroIdle As Integer) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

FtgRegisterIdleRoutine = ctypes.windll.mapi32.FtgRegisterIdleRoutine
FtgRegisterIdleRoutine.restype = ctypes.c_void_p
FtgRegisterIdleRoutine.argtypes = [
    ctypes.c_void_p,  # lpfnIdle : PFNIDLE
    ctypes.POINTER(None),  # lpvIdleParam : void* in/out
    ctypes.c_short,  # priIdle : SHORT
    wintypes.DWORD,  # csecIdle : DWORD
    ctypes.c_ushort,  # iroIdle : WORD
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MAPI32.dll')
FtgRegisterIdleRoutine = Fiddle::Function.new(
  lib['FtgRegisterIdleRoutine'],
  [
    Fiddle::TYPE_VOIDP,  # lpfnIdle : PFNIDLE
    Fiddle::TYPE_VOIDP,  # lpvIdleParam : void* in/out
    Fiddle::TYPE_SHORT,  # priIdle : SHORT
    -Fiddle::TYPE_INT,  # csecIdle : DWORD
    -Fiddle::TYPE_SHORT,  # iroIdle : WORD
  ],
  Fiddle::TYPE_VOIDP)
#[link(name = "mapi32")]
extern "system" {
    fn FtgRegisterIdleRoutine(
        lpfnIdle: *const core::ffi::c_void,  // PFNIDLE
        lpvIdleParam: *mut (),  // void* in/out
        priIdle: i16,  // SHORT
        csecIdle: u32,  // DWORD
        iroIdle: u16  // WORD
    ) -> *mut ();
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("MAPI32.dll")]
public static extern IntPtr FtgRegisterIdleRoutine(IntPtr lpfnIdle, IntPtr lpvIdleParam, short priIdle, uint csecIdle, ushort iroIdle);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MAPI32_FtgRegisterIdleRoutine' -Namespace Win32 -PassThru
# $api::FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
#uselib "MAPI32.dll"
#func global FtgRegisterIdleRoutine "FtgRegisterIdleRoutine" sptr, sptr, sptr, sptr, sptr
; FtgRegisterIdleRoutine lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle   ; 戻り値は stat
; lpfnIdle : PFNIDLE -> "sptr"
; lpvIdleParam : void* in/out -> "sptr"
; priIdle : SHORT -> "sptr"
; csecIdle : DWORD -> "sptr"
; iroIdle : WORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "MAPI32.dll"
#cfunc global FtgRegisterIdleRoutine "FtgRegisterIdleRoutine" sptr, sptr, int, int, int
; res = FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
; lpfnIdle : PFNIDLE -> "sptr"
; lpvIdleParam : void* in/out -> "sptr"
; priIdle : SHORT -> "int"
; csecIdle : DWORD -> "int"
; iroIdle : WORD -> "int"
; void* FtgRegisterIdleRoutine(PFNIDLE lpfnIdle, void* lpvIdleParam, SHORT priIdle, DWORD csecIdle, WORD iroIdle)
#uselib "MAPI32.dll"
#cfunc global FtgRegisterIdleRoutine "FtgRegisterIdleRoutine" intptr, intptr, int, int, int
; res = FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
; lpfnIdle : PFNIDLE -> "intptr"
; lpvIdleParam : void* in/out -> "intptr"
; priIdle : SHORT -> "int"
; csecIdle : DWORD -> "int"
; iroIdle : WORD -> "int"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	mapi32 = windows.NewLazySystemDLL("MAPI32.dll")
	procFtgRegisterIdleRoutine = mapi32.NewProc("FtgRegisterIdleRoutine")
)

// lpfnIdle (PFNIDLE), lpvIdleParam (void* in/out), priIdle (SHORT), csecIdle (DWORD), iroIdle (WORD)
r1, _, err := procFtgRegisterIdleRoutine.Call(
	uintptr(lpfnIdle),
	uintptr(lpvIdleParam),
	uintptr(priIdle),
	uintptr(csecIdle),
	uintptr(iroIdle),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // void*
function FtgRegisterIdleRoutine(
  lpfnIdle: Pointer;   // PFNIDLE
  lpvIdleParam: Pointer;   // void* in/out
  priIdle: Smallint;   // SHORT
  csecIdle: DWORD;   // DWORD
  iroIdle: Word   // WORD
): Pointer; stdcall;
  external 'MAPI32.dll' name 'FtgRegisterIdleRoutine';
result := DllCall("MAPI32\FtgRegisterIdleRoutine"
    , "Ptr", lpfnIdle   ; PFNIDLE
    , "Ptr", lpvIdleParam   ; void* in/out
    , "Short", priIdle   ; SHORT
    , "UInt", csecIdle   ; DWORD
    , "UShort", iroIdle   ; WORD
    , "Ptr")   ; return: void*
●FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle) = DLL("MAPI32.dll", "void* FtgRegisterIdleRoutine(void*, void*, int, dword, int)")
# 呼び出し: FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
# lpfnIdle : PFNIDLE -> "void*"
# lpvIdleParam : void* in/out -> "void*"
# priIdle : SHORT -> "int"
# csecIdle : DWORD -> "dword"
# iroIdle : WORD -> "int"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "mapi32" fn FtgRegisterIdleRoutine(
    lpfnIdle: ?*anyopaque, // PFNIDLE
    lpvIdleParam: ?*anyopaque, // void* in/out
    priIdle: i16, // SHORT
    csecIdle: u32, // DWORD
    iroIdle: u16 // WORD
) callconv(std.os.windows.WINAPI) ?*anyopaque;
proc FtgRegisterIdleRoutine(
    lpfnIdle: pointer,  # PFNIDLE
    lpvIdleParam: pointer,  # void* in/out
    priIdle: int16,  # SHORT
    csecIdle: uint32,  # DWORD
    iroIdle: uint16  # WORD
): pointer {.importc: "FtgRegisterIdleRoutine", stdcall, dynlib: "MAPI32.dll".}
pragma(lib, "mapi32");
extern(Windows)
void* FtgRegisterIdleRoutine(
    void* lpfnIdle,   // PFNIDLE
    void* lpvIdleParam,   // void* in/out
    short priIdle,   // SHORT
    uint csecIdle,   // DWORD
    ushort iroIdle   // WORD
);
ccall((:FtgRegisterIdleRoutine, "MAPI32.dll"), stdcall, Ptr{Cvoid},
      (Ptr{Cvoid}, Ptr{Cvoid}, Int16, UInt32, UInt16),
      lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
# lpfnIdle : PFNIDLE -> Ptr{Cvoid}
# lpvIdleParam : void* in/out -> Ptr{Cvoid}
# priIdle : SHORT -> Int16
# csecIdle : DWORD -> UInt32
# iroIdle : WORD -> UInt16
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
void* FtgRegisterIdleRoutine(
    void* lpfnIdle,
    void* lpvIdleParam,
    int16_t priIdle,
    uint32_t csecIdle,
    uint16_t iroIdle);
]]
local mapi32 = ffi.load("mapi32")
-- mapi32.FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
-- lpfnIdle : PFNIDLE
-- lpvIdleParam : void* in/out
-- priIdle : SHORT
-- csecIdle : DWORD
-- iroIdle : WORD
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('MAPI32.dll');
const FtgRegisterIdleRoutine = lib.func('__stdcall', 'FtgRegisterIdleRoutine', 'void *', ['void *', 'void *', 'int16_t', 'uint32_t', 'uint16_t']);
// FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
// lpfnIdle : PFNIDLE -> 'void *'
// lpvIdleParam : void* in/out -> 'void *'
// priIdle : SHORT -> 'int16_t'
// csecIdle : DWORD -> 'uint32_t'
// iroIdle : WORD -> 'uint16_t'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
// コールバック(関数ポインタ)は koffi.proto/koffi.register で型を定義して渡す(素の void* では JS 関数を渡せない)。
const lib = Deno.dlopen("MAPI32.dll", {
  FtgRegisterIdleRoutine: { parameters: ["pointer", "pointer", "i16", "u32", "u16"], result: "pointer" },
});
// lib.symbols.FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle)
// lpfnIdle : PFNIDLE -> "pointer"
// lpvIdleParam : void* in/out -> "pointer"
// priIdle : SHORT -> "i16"
// csecIdle : DWORD -> "u32"
// iroIdle : WORD -> "u16"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
void* FtgRegisterIdleRoutine(
    void* lpfnIdle,
    void* lpvIdleParam,
    int16_t priIdle,
    uint32_t csecIdle,
    uint16_t iroIdle);
C, "MAPI32.dll");
// $ffi->FtgRegisterIdleRoutine(lpfnIdle, lpvIdleParam, priIdle, csecIdle, iroIdle);
// lpfnIdle : PFNIDLE
// lpvIdleParam : void* in/out
// priIdle : SHORT
// csecIdle : DWORD
// iroIdle : WORD
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Mapi32 extends StdCallLibrary {
    Mapi32 INSTANCE = Native.load("mapi32", Mapi32.class);
    Pointer FtgRegisterIdleRoutine(
        Callback lpfnIdle,   // PFNIDLE
        Pointer lpvIdleParam,   // void* in/out
        short priIdle,   // SHORT
        int csecIdle,   // DWORD
        short iroIdle   // WORD
    );
}
@[Link("mapi32")]
lib LibMAPI32
  fun FtgRegisterIdleRoutine = FtgRegisterIdleRoutine(
    lpfnIdle : Void*,   # PFNIDLE
    lpvIdleParam : Void*,   # void* in/out
    priIdle : Int16,   # SHORT
    csecIdle : UInt32,   # DWORD
    iroIdle : UInt16   # WORD
  ) : Void*
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef FtgRegisterIdleRoutineNative = Pointer<Void> Function(Pointer<Void>, Pointer<Void>, Int16, Uint32, Uint16);
typedef FtgRegisterIdleRoutineDart = Pointer<Void> Function(Pointer<Void>, Pointer<Void>, int, int, int);
final FtgRegisterIdleRoutine = DynamicLibrary.open('MAPI32.dll')
    .lookupFunction<FtgRegisterIdleRoutineNative, FtgRegisterIdleRoutineDart>('FtgRegisterIdleRoutine');
// lpfnIdle : PFNIDLE -> Pointer<Void>
// lpvIdleParam : void* in/out -> Pointer<Void>
// priIdle : SHORT -> Int16
// csecIdle : DWORD -> Uint32
// iroIdle : WORD -> Uint16
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function FtgRegisterIdleRoutine(
  lpfnIdle: Pointer;   // PFNIDLE
  lpvIdleParam: Pointer;   // void* in/out
  priIdle: Smallint;   // SHORT
  csecIdle: DWORD;   // DWORD
  iroIdle: Word   // WORD
): Pointer; stdcall;
  external 'MAPI32.dll' name 'FtgRegisterIdleRoutine';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "FtgRegisterIdleRoutine"
  c_FtgRegisterIdleRoutine :: Ptr () -> Ptr () -> Int16 -> Word32 -> Word16 -> IO (Ptr ())
-- lpfnIdle : PFNIDLE -> Ptr ()
-- lpvIdleParam : void* in/out -> Ptr ()
-- priIdle : SHORT -> Int16
-- csecIdle : DWORD -> Word32
-- iroIdle : WORD -> Word16
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let ftgregisteridleroutine =
  foreign "FtgRegisterIdleRoutine"
    ((ptr void) @-> (ptr void) @-> int16_t @-> uint32_t @-> uint16_t @-> returning (ptr void))
(* lpfnIdle : PFNIDLE -> (ptr void) *)
(* lpvIdleParam : void* in/out -> (ptr void) *)
(* priIdle : SHORT -> int16_t *)
(* csecIdle : DWORD -> uint32_t *)
(* iroIdle : WORD -> uint16_t *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library mapi32 (t "MAPI32.dll"))
(cffi:use-foreign-library mapi32)

(cffi:defcfun ("FtgRegisterIdleRoutine" ftg-register-idle-routine :convention :stdcall) :pointer
  (lpfn-idle :pointer)   ; PFNIDLE
  (lpv-idle-param :pointer)   ; void* in/out
  (pri-idle :int16)   ; SHORT
  (csec-idle :uint32)   ; DWORD
  (iro-idle :uint16))   ; WORD
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $FtgRegisterIdleRoutine = Win32::API::More->new('MAPI32',
    'LPVOID FtgRegisterIdleRoutine(LPVOID lpfnIdle, LPVOID lpvIdleParam, short priIdle, DWORD csecIdle, WORD iroIdle)');
# my $ret = $FtgRegisterIdleRoutine->Call($lpfnIdle, $lpvIdleParam, $priIdle, $csecIdle, $iroIdle);
# lpfnIdle : PFNIDLE -> LPVOID
# lpvIdleParam : void* in/out -> LPVOID
# priIdle : SHORT -> short
# csecIdle : DWORD -> DWORD
# iroIdle : WORD -> WORD
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# コールバック(関数ポインタ)は Perl sub を直接渡せません。Win32::API::Callback を使用してください。

関連項目

使用する型