Fonction InitOnceBeginInitialize (synchapi.h)

Article
01/27/2024

Commence une initialisation unique.

Syntaxe

BOOL InitOnceBeginInitialize(
  [in, out]       LPINIT_ONCE lpInitOnce,
  [in]            DWORD       dwFlags,
  [out]           PBOOL       fPending,
  [out, optional] LPVOID      *lpContext
);

Paramètres

[in, out] lpInitOnce

Pointeur vers la structure d’initialisation à usage unique.

[in] dwFlags

Ce paramètre peut avoir la valeur 0, ou un ou plusieurs des indicateurs suivants.

Valeur	Signification
INIT_ONCE_ASYNC 0x00000002UL	Active l’exécution de plusieurs tentatives d’initialisation en parallèle. Si cet indicateur est utilisé, les appels ultérieurs à cette fonction échouent, sauf si cet indicateur est également spécifié.
INIT_ONCE_CHECK_ONLY 0x00000001UL	Cet appel de fonction ne commence pas l’initialisation. La valeur de retour indique si l’initialisation est déjà terminée. Si la fonction retourne TRUE, le paramètre lpContext reçoit les données.

[out] fPending

Si la fonction réussit, ce paramètre indique la status d’initialisation actuelle.

Si ce paramètre a la valeur TRUE et que dwFlags contient INIT_ONCE_CHECK_ONLY, l’initialisation est en attente et les données de contexte ne sont pas valides.

Si ce paramètre a la valeur FALSE, l’initialisation est déjà terminée et l’appelant peut récupérer les données de contexte à partir du paramètre lpContext .

Si ce paramètre a la valeur TRUE et que dwFlags ne contient pas de INIT_ONCE_CHECK_ONLY, l’initialisation a été démarrée et l’appelant peut effectuer les tâches d’initialisation.

[out, optional] lpContext

Paramètre facultatif qui reçoit les données stockées avec la structure d’initialisation à usage unique en cas de réussite. Les bits de INIT_ONCE_CTX_RESERVED_BITS de données de bas ordre sont toujours nuls.

Valeur retournée

Si INIT_ONCE_CHECK_ONLY n’est pas spécifié et que la fonction réussit, la valeur de retour est TRUE.

Si INIT_ONCE_CHECK_ONLY est spécifié et que l’initialisation est terminée, la valeur de retour est TRUE.

Sinon, la valeur de retour est FALSE.

Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Cette fonction peut être utilisée pour une initialisation synchrone ou asynchrone à usage unique. Pour une initialisation asynchrone à usage unique, utilisez l’indicateur INIT_ONCE_ASYNC . Pour spécifier une fonction de rappel à exécuter lors de l’initialisation synchrone à usage unique, consultez la fonction InitOnceExecuteOnce .

Si cette fonction réussit, le thread peut créer un objet de synchronisation et spécifier dans le paramètre lpContext de la fonction InitOnceComplete .

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0600 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Un objet d’initialisation unique ne peut pas être déplacé ou copié. Le processus ne doit pas modifier l’objet d’initialisation et doit plutôt le traiter comme étant logiquement opaque. Utilisez uniquement les fonctions d’initialisation à usage unique pour gérer les objets d’initialisation à usage unique.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Utilisation de l’initialisation One-Time

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	synchapi.h (inclure Windows.h sur Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll