IInitiateWinSATAssessment

アセスメントを開始します。

アドホックアセスメントを開始します。

このメソッドは次のいずれかの値を返すことがあります。

次の表に、このメソッドが返す HRESULT 値の一部を示します。

通常、アドホックアセスメントはコンピューターの 1 つのサブコンポーネントを評価するために実行しますが、正式なアセスメントはコンピューターのすべてのサブコンポーネントを評価します。正式なアセスメントを実行するには、IInitiateWinSATAssessment::InitiateFormalAssessment メソッドを呼び出してください。

アドホックアセスメントは WinSAT データストアに保存されません。データストアに保存されるのは正式なアセスメントのみです(結果のクエリに IQueryRecentWinSATAssessment インターフェイスを使用することはできません)。アドホックアセスメントの結果を取得するには、–xml FileName 引数を指定します。これにより結果が XML ファイルに保存され、後で解析できます。

WinSAT の実行には管理者権限が必要です。ユーザーが管理者権限を持っていない場合、WinSAT は資格情報の入力を求めるダイアログボックスを表示します。

例

次の例は、アドホックアセスメントを実行し、その進行状況の通知を受け取る方法を示しています。

#include <windows.h>
#include <stdio.h>
#include <conio.h>  // For kbhit()
#include <winsatcominterfacei.h>

#pragma comment(lib, "ole32.lib")

BOOL IsKeyEvent(HANDLE hStdIn);


// Class that implements IWinSATInitiateEvents. Implement this class to
// get progress information and completion notification.
class CWinSATCallbacks : public IWinSATInitiateEvents
{
    LONG m_lRefCount;

public:

    // Constructor, Destructor
    CWinSATCallbacks() {m_lRefCount = 1;};
    ~CWinSATCallbacks() {};

    // IUnknown methods
    HRESULT __stdcall QueryInterface(REFIID riid, LPVOID *ppvObj);
    ULONG __stdcall AddRef();
    ULONG __stdcall Release();

    // IWinSATInitiateEvents methods
    HRESULT __stdcall WinSATComplete(HRESULT hr, LPCWSTR description);
    HRESULT __stdcall WinSATUpdate(UINT currentTick, UINT tickTotal, LPCWSTR currentState);
};


HRESULT CWinSATCallbacks::QueryInterface(REFIID riid, LPVOID* ppvObj) 
{
    if (riid == __uuidof(IUnknown) || riid == __uuidof(IWinSATInitiateEvents)) 
    {
        *ppvObj = this;
    }
    else
    {
        *ppvObj = NULL;
        return E_NOINTERFACE;
    }

    AddRef();
    return NOERROR;
}

ULONG CWinSATCallbacks::AddRef() 
{
    return InterlockedIncrement(&m_lRefCount);
}

ULONG CWinSATCallbacks::Release() 
{
    ULONG  ulCount = InterlockedDecrement(&m_lRefCount);

    if(0 == ulCount) 
    {
        delete this;
    }

    return ulCount;
}

// Is called when WinSAT completes the assessment or an error occurs.
HRESULT CWinSATCallbacks::WinSATComplete(HRESULT hr, LPCWSTR description)
{
    if (SUCCEEDED(hr))
    {
        wprintf(L"\n*** %s", description);
    }
    else
    {
        wprintf(L"\n*** The assessment failed with 0x%x (%s)\n", hr, description);
    }

    return S_OK;
}

// There is no progress information for ad hoc assessment. The method provides the 
// name of the component being assessed.
HRESULT CWinSATCallbacks::WinSATUpdate(UINT currentTick, UINT tickTotal, LPCWSTR currentState)
{
    return S_OK;
}


void main(void)
{
    HRESULT hr = S_OK;
    IInitiateWinSATAssessment* pAssessment = NULL;
    CWinSATCallbacks* pCallbacks = NULL;  // Class that implements IWinSATInitiateEvents
    LPWSTR pCommand = L"mem -buffersize 32MB -xml .\\MemoryAssessment.xml";
    HANDLE hConsole = INVALID_HANDLE_VALUE;
    DWORD dwWait = 0;

    CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

    // Get an instance of the assessment interface.
    hr = CoCreateInstance(__uuidof(CInitiateWinSAT),
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          __uuidof(IInitiateWinSATAssessment),
                          (void**)&pAssessment);

    if (FAILED(hr))
    {
        wprintf(L"Failed to create an instance of IInitiateWinSATAssessment. Failed with 0x%x.\n", hr);
        goto cleanup;
    }

    wprintf(L"Running formal assessment... hit any key when complete.\n");

    // Get a handle for console input, so you can break out of the loop.
    hConsole = GetStdHandle(STD_INPUT_HANDLE);
    if (INVALID_HANDLE_VALUE == hConsole)
    {
        wprintf(L"GetStdHandle failed with %lu.\n", GetLastError());
        goto cleanup;
    }

    pCallbacks = new CWinSATCallbacks();
    if (NULL == pCallbacks)
    {
        wprintf(L"Failed to create an instance of the CWinSATCallbacks class.\n");
        goto cleanup;
    }

    // Run the formal assessment.
    hr = pAssessment->InitiateAssessment(pCommand, pCallbacks, NULL);
    if (FAILED(hr))
    {
        // This is a failure to start WinSAT. If WinSAT fails while running, 
        // your implementation of the IWinSATInitiateEvents::WinSATComplete 
        // method will receive the failure code.
        wprintf(L"InitiateFormalAssessment failed with 0x%x.\n", hr);
        goto cleanup;
    }

    // Loop until the user presses a key or there is an error.
    while (true)
    {
        dwWait = WaitForSingleObject(hConsole, INFINITE);

        if (WAIT_OBJECT_0 == dwWait)  // Console input
        {
            if (IsKeyEvent(hConsole))
                break;
        }
        else if (WAIT_FAILED == dwWait)
        {
            wprintf(L"WaitForSingleObject failed with %lu\n", GetLastError());
            break;
        }
    }

cleanup:

    if (pAssessment)
        pAssessment->Release();

    if (pCallbacks)
        pCallbacks->Release();

    if (hConsole)
        CloseHandle(hConsole);

    CoUninitialize();
}

// Determines whether the console input was a key event.
BOOL IsKeyEvent(HANDLE hStdIn)
{
    INPUT_RECORD Record[128];
    DWORD dwRecordsRead = 0;
    BOOL fKeyPress = FALSE;

    if (ReadConsoleInput(hStdIn, Record, 128, &dwRecordsRead))
    {
        for (DWORD i = 0; i < dwRecordsRead; i++)
        {
            if (KEY_EVENT == Record[i].EventType)
            {
                fKeyPress = TRUE;
                break;
            }
        }
    }

    return fKeyPress;
}

正式なアセスメントを開始します。

このメソッドは次のいずれかの値を返すことがあります。

次の表に、このメソッドが返す HRESULT 値の一部を示します。

通常、正式なアセスメントはコンピューターのすべてのサブコンポーネントを評価するために実行しますが、アドホックアセスメントはコンピューターの 1 つのサブコンポーネントを評価します。アドホックアセスメントを実行するには、IInitiateWinSATAssessment::InitiateAssessment メソッドを呼び出してください。

正式なアセスメントの結果を取得するには、IQueryRecentWinSATAssessment インターフェイスを使用します。

Windows アプリケーションからこの関数を呼び出す場合は、IWinSATInitiateEvents インターフェイスを実装して、進行状況を表示したりアセスメント完了時に通知を受け取ったりできるようにします。Windows コンソールアプリケーションの場合は、WinSAT が進行状況をコンソールウィンドウに書き込むため、進行状況を表示する必要はありません。

WinSAT の実行には管理者権限が必要である点に注意してください。ユーザーが管理者権限を持っていない場合、WinSAT は資格情報の入力を求めるダイアログボックスを表示します。

例

次の例は、正式なアセスメントを実行し、その進行状況の通知を受け取る方法を示しています。

#include <windows.h>
#include <stdio.h>
#include <conio.h>  // For kbhit()
#include <winsatcominterfacei.h>

#pragma comment(lib, "ole32.lib")

// Class that implements IWinSATInitiateEvents. Implement this class to
// get progress information and completion notification.
class CWinSATCallbacks : public IWinSATInitiateEvents
{
    LONG m_lRefCount;

public:

    // Constructor, Destructor
    CWinSATCallbacks() {m_lRefCount = 1;};
    ~CWinSATCallbacks() {};

    // IUnknown methods
    HRESULT __stdcall QueryInterface(REFIID riid, LPVOID *ppvObj);
    ULONG __stdcall AddRef();
    ULONG __stdcall Release();

    // IWinSATInitiateEvents methods
    HRESULT __stdcall WinSATComplete(HRESULT hr, LPCWSTR description);
    HRESULT __stdcall WinSATUpdate(UINT currentTick, UINT tickTotal, LPCWSTR currentState);
};


HRESULT CWinSATCallbacks::QueryInterface(REFIID riid, LPVOID* ppvObj) 
{
    if (riid == __uuidof(IUnknown) || riid == __uuidof(IWinSATInitiateEvents)) 
    {
        *ppvObj = this;
    }
    else
    {
        *ppvObj = NULL;
        return E_NOINTERFACE;
    }

    AddRef();
    return NOERROR;
}

ULONG CWinSATCallbacks::AddRef() 
{
    return InterlockedIncrement(&m_lRefCount);
}

ULONG CWinSATCallbacks::Release() 
{
    ULONG  ulCount = InterlockedDecrement(&m_lRefCount);

    if(0 == ulCount) 
    {
        delete this;
    }

    return ulCount;
}

// Is called when WinSAT completes the assessment or an error occurs.
HRESULT CWinSATCallbacks::WinSATComplete(HRESULT hr, LPCWSTR description)
{
    if (SUCCEEDED(hr))
    {
        wprintf(L"\n*** %s", description);
    }
    else
    {
        wprintf(L"\n*** The assessment failed with 0x%x (%s)\n", hr, description);
    }

    return S_OK;
}

// Is called when the assessment makes progress. Indicates the percentage of the assessment
// that is complete and the current component being assessed.
HRESULT CWinSATCallbacks::WinSATUpdate(UINT currentTick, UINT tickTotal, LPCWSTR currentState)
{
    // Typically, you would provide the tick values to a ProgressBar control.

    if (tickTotal > 0)
    {
        wprintf(L"\n*** Percent complete: %u%%\n", 100*currentTick/tickTotal);
        wprintf(L"*** Currently assessing: %s\n\n", currentState);
    }

    return S_OK;
}

void main(void)
{
    HRESULT hr = S_OK;
    IInitiateWinSATAssessment* pAssessment = NULL;
    CWinSATCallbacks* pCallbacks = NULL;  // Class that implements IWinSATInitiateEvents

    CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

    // Get an instance of the assessment interface.
    hr = CoCreateInstance(__uuidof(CInitiateWinSAT),
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          __uuidof(IInitiateWinSATAssessment),
                          (void**)&pAssessment);

    if (FAILED(hr))
    {
        wprintf(L"Failed to create an instance of IInitiateWinSATAssessment. Failed with 0x%x.\n", hr);
        goto cleanup;
    }

    wprintf(L"Running formal assessment... hit any key when complete.\n");

    pCallbacks = new CWinSATCallbacks();
    if (NULL == pCallbacks)
    {
        wprintf(L"Failed to create an instance of the CWinSATCallbacks class.\n");
        goto cleanup;
    }

    // Run the formal assessment.
    hr = pAssessment->InitiateFormalAssessment(pCallbacks, NULL);
    if (FAILED(hr))
    {
        // This is a failure to start WinSAT. If WinSAT fails while running, 
        // your implementation of the IWinSATInitiateEvents::WinSATComplete 
        // method will receive the failure code.
        wprintf(L"InitiateFormalAssessment failed with 0x%x.\n", hr);
        goto cleanup;
    }

    while (!_kbhit())
        Sleep(10);

cleanup:

    if (pAssessment)
        pAssessment->Release();

    if (pCallbacks)
        pCallbacks->Release();

    CoUninitialize();
}

現在実行中のアセスメントをキャンセルします。

成功した場合は S_OK を返します。それ以外の場合は、次のエラーコード、または HRESULT として返される Win32 エラーコードを返します。

このメソッドは WinSAT にアセスメントのキャンセル要求を送信します。キャンセル要求が成功したかどうかを判断するには、IWinSATInitiateEvents::WinSATComplete メソッドを実装し、hresult パラメーターの値が WINSAT_ERROR_WINSAT_CANCELED かどうかを確認してください。