CreateThreadpoolIo function (threadpoolapiset.h)

Article
02/22/2024

Creates a new I/O completion object.

Syntax

PTP_IO CreateThreadpoolIo(
  [in]                HANDLE                fl,
  [in]                PTP_WIN32_IO_CALLBACK pfnio,
  [in, out, optional] PVOID                 pv,
  [in, optional]      PTP_CALLBACK_ENVIRON  pcbe
);

Parameters

[in] fl

The file handle to bind to this I/O completion object.

[in] pfnio

The callback function to be called each time an overlapped I/O operation completes on the file. For details, see IoCompletionCallback.

[in, out, optional] pv

Optional application-defined data to pass to the callback function.

[in, optional] pcbe

A pointer to a TP_CALLBACK_ENVIRON structure that defines the environment in which to execute the callback. Use the InitializeThreadpoolEnvironment function to initialize the structure before calling this function.

If this parameter is NULL, the callback executes in the default callback environment. For more information, see InitializeThreadpoolEnvironment.

Return value

If the function succeeds, it returns a pointer to a TP_IO structure that defines the I/O object. Applications do not modify the members of this structure.

If the function fails, it returns NULL. To retrieve extended error information, call GetLastError.

Remarks

To begin receiving overlapped I/O completion callbacks, call the StartThreadpoolIo function.

If the file handle bound to the I/O completion object has the notification mode FILE_SKIP_COMPLETION_PORT_ON_SUCCESS and an asychronous I/O operation returns immediately with success, the I/O completion callback function is not called and threadpool I/O notifications must be canceled. For more information, see CancelThreadpoolIo.

To compile an application that uses this function, define _WIN32_WINNT as 0x0600 or higher.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	threadpoolapiset.h (include Windows.h on Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library	Kernel32.lib
DLL	Kernel32.dll