Función SHCreateThreadWithHandle (shlwapi.h)

Artículo
08/26/2023

Crea un subproceso y recupera su identificador.

Sintaxis

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
);

Parámetros

[in] pfnThreadProc

Tipo: LPTHREAD_START_ROUTINE

Puntero a una función definida por la aplicación de tipo LPTHREAD_START_ROUTINE. Si se creó correctamente un nuevo subproceso, se llama a esta función definida por la aplicación en el contexto de ese subproceso. SHCreateThreadWithHandle no espera a que se complete la función a la que apunta pfnThreadProc antes de volver a su llamador. El valor devuelto de la función especificada por pfnThreadProc es el código de salida del subproceso.

[in, optional] pData

Tipo: void*

Puntero a una estructura de datos opcional definida por la aplicación que contiene datos de inicialización. Se pasa a la función a la que apunta pfnThreadProc y, opcionalmente, la función a la que apunta pfnCallback.

[in] flags

Tipo: SHCT_FLAGS

Marcas que controlan el comportamiento de la función; una o varias de las constantes CTF .

[in, optional] pfnCallback

Tipo: LPTHREAD_START_ROUTINE

Puntero a una función opcional definida por la aplicación de tipo LPTHREAD_START_ROUTINE. Se llama a esta función en el contexto del subproceso creado antes de llamar a la función a la que apunta pfnThreadProc . También recibirá pData como argumento. SHCreateThreadWithHandle espera a que se complete la función a la que apunta pfnCallback antes de volver a su llamador. Se omite el valor devuelto de la función especificada por pfnCallback .

[out, optional] pHandle

Tipo: HANDLE*

Puntero al identificador del subproceso creado. Cuando ya no es necesario, este identificador debe cerrarse mediante una llamada a la función CloseHandle . Este valor puede ser NULL.

Valor devuelto

Tipo: BOOL

TRUE si el subproceso se crea correctamente; en caso contrario, FALSE

Comentarios

Antes de Windows 7, esta función no tenía un archivo de encabezado o biblioteca asociado. Para usar esta función en esos sistemas operativos anteriores, llame a LoadLibrary con el nombre dll (Shlwapi.dll) para obtener un identificador de módulo. A continuación, llame a GetProcAddress con ese identificador de módulo y un ordinal de función de 615 para obtener la dirección de esta función.

La función a la que apunta pfnThreadProc y pfnCallback debe tener la siguiente forma.

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

El nombre de la función es arbitrario. El parámetro pData apunta a una estructura de datos definida por la aplicación con información de inicialización.

Ejemplos

En el ejemplo de código siguiente se proporciona una definición de tipo de prototipo de puntero de función para llamar a SHCreateThreadWithHandle por ordinal y se muestra cómo realizar dicha llamada.

// 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);
}

Requisitos


Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shlwapi.h
Library	Shlwapi.lib
Archivo DLL	Shlwapi.dll (versión 6.0 o posterior)