windows-server-2003/admin/services/sched/idletask/idl/idlrpc.idl

/*++

Copyright (c) 1990  Microsoft Corporation

Module Name:

    idlrpc.idl

Abstract:

    Contains the RPC interface specification for the idle task / idle detection APIs.
    Also contains the RPC specific data structures for these API.

Author:

    Cenk Ergan (cenke)  07-August-2000

Environment:

    User Mode - Win32 - MIDL

Revision History:

--*/

//
// Interface Attributes
//

[
    uuid(0a74ef1c-41a4-4e06-83ae-dc74fb1cdd53),
    version(1.0)
]

//
// Interface Keyword
//

interface idletask

//
// Interface Body
//

{
import "wtypes.idl";

//
// IT_IDLE_TASK_ID declaration.
//

#define MIDL_PASS
#include <idletask.h>

//
// The prefered protocol sequence for connecting the server and the
// client is LPC because of its low overhead. We'd like to bind to
// dynamic endpoint, because a well known endpoint may require another
// listener thread on the server side. Note that depending on the
// other RPC servers in the process we end up in, other bindings may
// also be used.
//

const WCHAR * IT_RPC_PROTSEQ          = L"ncalrpc";

//
// This is the custom binding handle type. Specifying this allows us
// to bind to the server when the interface functions are called via
// the IT_RPC_bind and _unbind functions that are part of the client.
// It is not used for any other purpose, although it has to be a
// parameter to the interface functions.
//

typedef [handle] WCHAR * ITRPC_HANDLE;

//
// This is a custom context handle. This allows the server to get
// notified when a client dies.
//

typedef [context_handle] VOID *IT_HANDLE;

//
// Status of an idle task.
//

// FUTURE-2002/03/26-ScottMa -- The following enumeration is not exposed
//   outside the server.  Consider moving it to ..\server\idletsks.h instead
//   of leaving it here in the generated RPC headers.

typedef enum _IT_IDLE_TASK_STATUS {
    ItIdleTaskInitializing,
    ItIdleTaskQueued,
    ItIdleTaskRunning,
    ItIdleTaskMaxStatus
} IT_IDLE_TASK_STATUS, *PIT_IDLE_TASK_STATUS;

//
// This structure describes the idle task the client wants to register.
//

typedef struct _IT_IDLE_TASK_PROPERTIES {

    //
    // Size of the structure.
    //

    ULONG Size;
    
    //
    // Idle task identifier and which process it is in. These two
    // uniquely identify the idle task.
    //

    IT_IDLE_TASK_ID IdleTaskId;
    DWORD ProcessId;

    //
    // Local handle for the event to be notified when the task should
    // start running.
    //
    
    ULONG_PTR StartEventHandle;
    
    //
    // Local handle for the event to be notified when the task should
    // stop running.
    //
    
    ULONG_PTR StopEventHandle;

} IT_IDLE_TASK_PROPERTIES, *PIT_IDLE_TASK_PROPERTIES;

//
// This structure contains parameters that control the behaviour of
// idle detection.
//

typedef struct _IT_IDLE_DETECTION_PARAMETERS {

    //
    // This is how long in ms we will wait until each time we check
    // for system idleness.
    //

    ULONG IdleDetectionPeriod;

    //
    // After we detect that system was idle over a long period, we
    // will verify the system is still idle by checking idleness over
    // a smaller period. This way we won't miss recent activity that
    // seemed insignificant over a long IdleDetectionPeriod.
    //

    ULONG IdleVerificationPeriod;
    ULONG NumVerifications;

    //
    // We will be polling for user input when running idle tasks every
    // this many ms. We want to catch user input and notify the idle task
    // to stop running as soon as possible. Even though the system is
    // idle, we don't want to create too much overhead which may mislead
    // ourself.
    //

    ULONG IdleInputCheckPeriod;

    //
    // We check to see if the idle task we asked to run is really running
    // (i.e. it is using the disk and CPU) every this many ms. This is our
    // mechanism for cleaning up after unregistered/orphaned tasks. This
    // should be greater than IdleInputCheckPeriod.
    //

    // FUTURE-2002/03/26-ScottMa -- This field is never used as an R-value.

    ULONG IdleTaskRunningCheckPeriod;

    //
    // If the CPU is not idle more than this percent over a time interval,
    // the system is not considered idle.
    //

    ULONG MinCpuIdlePercentage;

    //
    // If a disk is not idle more than this percent over a time interval,
    // the system is not considered idle.
    //
    
    ULONG MinDiskIdlePercentage;

    //
    // This is the maximum number of registered idle tasks at one time.
    //

    ULONG MaxNumRegisteredTasks;

} IT_IDLE_DETECTION_PARAMETERS, *PIT_IDLE_DETECTION_PARAMETERS;

//
// Idle task server registration/unregistration API. These are not
// called from the user directly. They are called by the client side
// implementation of the RegisterIdleTask/UnregisterIdleTask API.
//

// ISSUE-2002/03/26-ScottMa -- The context handle in the following two RPCs
//   should not be passed by ref.  The UnregisterIdleTask function must
//   set the context handle to NULL prior to returning, and [ref] pointers
//   cannot be NULL.  Modify the pointer specifier on IT_HANDLE to be of
//   type [unique].

DWORD
ItSrvRegisterIdleTask (
    [in,string,unique] ITRPC_HANDLE Reserved,
    [out,ref] IT_HANDLE *ItHandle,
    [in,ref] PIT_IDLE_TASK_PROPERTIES IdleTaskProperties
    );

void
ItSrvUnregisterIdleTask (
    [in,string,unique] ITRPC_HANDLE Reserved,
    [in,out,ref] IT_HANDLE *ItHandle
    );

//
// This function is called to process all registered tasks without
// waiting for system to become idle.
//

DWORD
ItSrvProcessIdleTasks (
    [in,string,unique] ITRPC_HANDLE Reserved
    );

//
// This function is implemented only in the debug builds so test
// applications can set stress parameters. It returns
// ERROR_NOT_IMPLEMENTED on free builds.
//

DWORD
ItSrvSetDetectionParameters (
    [in,string,unique] ITRPC_HANDLE Reserved,
    [in,ref] PIT_IDLE_DETECTION_PARAMETERS Parameters
    );

}