SHCreateThreadWithHandle 関数 (shlwapi.h)

  • [アーティクル]

新しいスレッドを作成し、そのハンドルを取得します。

構文

BOOL SHCreateThreadWithHandle(
  [in]            LPTHREAD_START_ROUTINE pfnThreadProc,
  [in, optional]  void                   *pData,
  [in]            SHCT_FLAGS             flags,
  [in, optional]  LPTHREAD_START_ROUTINE pfnCallback,
  [out, optional] HANDLE                 *pHandle
);

パラメーター

[in] pfnThreadProc

種類: LPTHREAD_START_ROUTINE

LPTHREAD_START_ROUTINE型のアプリケーション定義関数へのポインター。 新しいスレッドが正常に作成された場合、このアプリケーション定義関数はそのスレッドのコンテキストで呼び出されます。 SHCreateThreadWithHandle は、 pfnThreadProc が指す関数が完了するまで待機せず、呼び出し元に戻ります。 pfnThreadProc によって指定された関数の戻り値は、スレッドの終了コードです。

[in, optional] pData

型: void*

初期化データを含むオプションのアプリケーション定義データ構造へのポインター。 pfnThreadProc が指す関数と、必要に応じて pfnCallback によって指される関数に渡されます。

[in] flags

種類: SHCT_FLAGS

関数の動作を制御するフラグ。1 つ以上の CTF 定数。

[in, optional] pfnCallback

種類: LPTHREAD_START_ROUTINE

LPTHREAD_START_ROUTINE型の省略可能なアプリケーション定義関数へのポインター。 この関数は、 pfnThreadProc によって指される関数が呼び出される前に、作成されたスレッドのコンテキストで呼び出されます。 また、引数として pData を受け取ります。 SHCreateThreadWithHandle は 、pfnCallback が指す関数が完了するまで待機してから、呼び出し元に戻ります。 pfnCallback によって指定された関数の戻り値は無視されます。

[out, optional] pHandle

種類: HANDLE*

作成されたスレッドの HANDLE へのポインター。 不要になったら、 CloseHandle 関数を呼び出してこのハンドルを閉じる必要があります。 この値は NULL にすることができます。

戻り値

種類: BOOL

スレッド が正常に作成された場合は TRUE。それ以外の場合は FALSE

解説

Windows 7 より前のバージョンでは、この関数にはヘッダー ファイルまたはライブラリ ファイルが関連付けられませんでした。 以前のオペレーティング システムでこの関数を使用するには、DLL 名 (Shlwapi.dll) で LoadLibrary を呼び出してモジュール ハンドルを取得します。 次に、そのモジュール ハンドルと 615 の関数序数で GetProcAddress を呼び出して、この関数のアドレスを取得します。

pfnThreadProc および pfnCallback が指す関数は、次の形式にする必要があります。

DWORD WINAPI ThreadProc(LPVOID pData)
{
    ...
}

関数名は任意です。 pData パラメーターは、初期化情報を含むアプリケーション定義のデータ構造を指します。

例

次のコード例では、序数で SHCreateThreadWithHandle を呼び出すための関数ポインター プロトタイプ typedef を提供し、そのような呼び出しを実行する方法を示します。

// Define SHCREATETHREADWITHHANDLE as a function pointer to SHCreateThreadWithHandle.
typedef BOOL (STDMETHODCALLTYPE *SHCREATETHREADWITHHANDLE)(LPTHREAD_START_ROUTINE, 
                                                           void *, 
                                                           DWORD, 
                                                           LPTHREAD_START_ROUTINE, 
                                                           HANDLE *);

// CallSHCreateThreadWithHandle is an example function that:
// 1. Accepts parameters for the SHCreateThreadWithHandle function.
// 2. Loads Shlwapi.dll, which implements SHCreateThreadWithHandle.
// 3. Obtains the address of SHCreateThreadWithHandle in the loaded library.
// 4. Calls SHCreateThreadWithHandle through a SHCREATETHREADWITHHANDLE function pointer.

BOOL CallSHCreateThreadWithHandle(LPTHREAD_START_ROUTINE pfnThreadProc, 
                                  void *pData,
                                  DWORD dwFlags, 
                                  LPTHREAD_START_ROUTINE pfnCallback, 
                                  HANDLE *pHandle)
{
    // Build a string that contains the local path to Shlwapi.dll.
    WCHAR szPath[MAX_PATH];
    GetSystemDirectory(szPath, ARRAYSIZE(szPath));  
    PathAppend(szPath, L"shlwapi.dll");

    // Attempt to load Shlwapi.dll.
    HMODULE hModule = LoadLibrary(szPath);

    HRESULT hr = hModule ? S_OK : HRESULT_FROM_WIN32(GetLastError());
    if (SUCCEEDED(hr)) 
    {
        // Shlwapi.dll is loaded. 
        // Before Windows 7, SHCreateThreadWithHandle must be accessed through 
        // its ordinal. The following commented lines are used for this.
        
        // Get the address of SHCreateThreadWithHandle through its ordinal value of 615.
        // SHCREATETHREADWITHHANDLE pfn =
        //     (SHCREATETHREADWITHHANDLE)GetProcAddress(hModule, MAKEINTRESOURCEA(615));
        //
        // hr = pfn ? S_OK : HRESULT_FROM_WIN32(GetLastError());
        //
        // if (SUCCEEDED(hr))
        // {
        //     // Call SHCreateThreadWithHandle through SHCREATETHREADWITHHANDLE.
        //     hr = pfn(pfnThreadProc, pData, dwFlags, pfnCallback, pHandle) 
        //               ? S_OK : HRESULT_FROM_WIN32(GetLastError());
        // }
        // FreeLibrary(hModule);
        
        hr = SHCreateThreadWithHandle(pfnThreadProc, pData, dwFlags, pfnCallback, pHandle) 
                       ? S_OK : HRESULT_FROM_WIN32(GetLastError());
    }
    return SUCCEEDED(hr);
}

要件

   
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー shlwapi.h
Library Shlwapi.lib
[DLL] Shlwapi.dll (バージョン 6.0 以降)

関連項目

GetLastError

GetProcAddress

GetSystemDirectory

HRESULT_FROM_WIN32

LoadLibrary