PINIT_ONCE_FN callback function (synchapi.h)

Article
02/22/2024

An application-defined callback function. Specify a pointer to this function when calling the InitOnceExecuteOnce function. The PINIT_ONCE_FN type defines a pointer to this callback function. InitOnceCallback is a placeholder for the application-defined function name.

Syntax

PINIT_ONCE_FN PinitOnceFn;

BOOL PinitOnceFn(
  [in, out]           PINIT_ONCE InitOnce,
  [in, out, optional] PVOID Parameter,
  [out, optional]     PVOID *Context
)
{...}

Parameters

[in, out] InitOnce

A pointer to the one-time initialization structure.

[in, out, optional] Parameter

An optional parameter that was passed to the callback function.

[out, optional] Context

The data to be stored with the one-time initialization structure. If Context references a value, the low-order INIT_ONCE_CTX_RESERVED_BITS of the value must be zero. If Context points to a data structure, the data structure must be DWORD-aligned. Context must not be a code pointer on Arm32, because Arm32 code pointers always have the least significant bit set, see the Arm32 ABI for details.

Return value

If the function returns TRUE, the block is marked as initialized.

If the function returns FALSE, the block is not marked as initialized and the call to InitOnceExecuteOnce fails. To communicate additional error information, call SetLastError before returning FALSE.

Remarks

This function can create a synchronization object and return it in the lpContext parameter.

To compile an application that uses this function, define _WIN32_WINNT as 0x0600 or later. For more information, see Using the Windows Headers.

Examples

For an example that uses this function, see Using One-Time Initialization.

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	synchapi.h (include Windows.h)