UpdateResourceW, fonction (winbase.h)

Article
11/20/2024

Ajoute, supprime ou remplace une ressource dans un fichier exécutable portable (PE). Certaines restrictions s’appliquent aux mises à jour des ressources dans les fichiers qui contiennent des données de configuration de ressource (CONFIGURATION RC) : fichiers (LN) et les fichiers de ressources spécifiques au langage (.mui).

Syntaxe

BOOL UpdateResourceW(
  [in]           HANDLE  hUpdate,
  [in]           LPCWSTR lpType,
  [in]           LPCWSTR lpName,
  [in]           WORD    wLanguage,
  [in, optional] LPVOID  lpData,
  [in]           DWORD   cb
);

Paramètres

[in] hUpdate

Type : HANDLE

Handle de module retourné par la fonction BeginUpdateResource, référençant le fichier à mettre à jour.

[in] lpType

Type : LPCTSTR

Type de ressource à mettre à jour. Sinon, au lieu d’un pointeur, ce paramètre peut être MAKEINTRESOURCE(ID), où ID est une valeur entière représentant un type de ressource prédéfini. Si le premier caractère de la chaîne est un signe de livre (#), les caractères restants représentent un nombre décimal qui spécifie l’identificateur entier du type de ressource. Par exemple, la chaîne « #258 » représente l’identificateur 258.

Pour obtenir la liste des types de ressources prédéfinis, consultez types de ressources.

[in] lpName

Type : LPCTSTR

Nom de la ressource à mettre à jour. Sinon, plutôt qu’un pointeur, ce paramètre peut être MAKEINTRESOURCE(ID), où l’ID est un ID de ressource. Lors de la création d’une ressource, n’utilisez pas de chaîne commençant par un caractère « # » pour ce paramètre.

[in] wLanguage

Type : WORD

Identificateur de langue de la ressource à mettre à jour. Pour obtenir la liste des identificateurs de langue primaires et des identificateurs de sous-langage qui composent un identificateur de langue, consultez la macro MAKELANGID.

[in, optional] lpData

Type : LPVOID

Données de ressource à insérer dans le fichier indiqué par hUpdate . Si la ressource est l’un des types prédéfinis, les données doivent être valides et correctement alignées. Notez qu’il s’agit des données binaires brutes à stocker dans le fichier indiqué par hUpdate , et non les données fournies par LoadIcon, LoadStringou d’autres fonctions de chargement spécifiques aux ressources. Toutes les données contenant des chaînes ou du texte doivent être au format Unicode. lpData ne doit pas pointer vers des données ANSI.

Si lpData est NULL et cbData est 0, la ressource spécifiée est supprimée du fichier indiqué par hUpdate .

[in] cb

Type : DWORD

Taille, en octets, des données de ressource à lpData.

Valeur de retour

Type : BOOL

Retourne TRUE si elle réussit ou FALSE sinon. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Il est recommandé que le fichier de ressources ne soit pas chargé avant l’appel de cette fonction. Toutefois, si ce fichier est déjà chargé, il n’entraîne pas de retour d’erreur.

Une application peut utiliser UpdateResource à plusieurs reprises pour apporter des modifications aux données de ressource. Chaque appel à UpdateResource contribue à une liste interne d’ajouts, de suppressions et de remplacements, mais n’écrit pas réellement les données dans le fichier indiqué par hUpdate. L’application doit utiliser la fonction EndUpdateResource pour écrire les modifications accumulées dans le fichier.

Cette fonction peut mettre à jour des ressources au sein des modules qui contiennent du code et des ressources.

Avant Windows 7 : Si lpData est NULL et cbData n’est pas zéro, la ressource spécifiée n’est pas supprimée et une exception est levée.

À partir de Windows Vista : Comme indiqué ci-dessus, il existe des restrictions sur les mises à jour des ressources dans les fichiers qui contiennent des données RC Config : fichiers LN et fichiers .mui. Les restrictions sont les suivantes :

Action	Fichier LN	Fichier .mui
1. Ajoutez un nouveau type qui n’existe pas dans les fichiers LN ou .mui.	Ajoutez un type dans le fichier LN et traitez comme neutre en langage (non localisable) et ajoutez un nouveau type ou un élément dans les données rc Config	Les seuls ajouts autorisés sont les types suivants : version de fichier, données de configuration RC, manifeste XML d’assembly côte à côte.
2. Ajoutez un nouvel élément de ressource à un type existant.	Utilise les données RC Config pour vérifier si le type existe dans les fichiers .mui associés à ce fichier LN. Si le type n’existe pas dans les fichiers .mui, ajoutez l’élément et traitez le nouvel élément comme non localisable. Si le type existe dans les fichiers .mui, l’ajout n’est pas autorisé.	Seuls les éléments des types suivants peuvent être ajoutés : version de fichier, données de configuration RC, manifeste XML d’assembly côte à côte.
3. Mettez à jour un élément de ressource.	Utilise les données RC Config pour vérifier si le type existe dans les fichiers .mui associés au fichier LN. Si le type n’existe pas dans les fichiers .mui, cette mise à jour d’élément de ressource est autorisée dans le fichier LN. Sinon, si le type existe dans les fichiers .mui associés à ce fichier LN, cette mise à jour n’est pas autorisée.	Les seules mises à jour autorisées sont des éléments des types suivants : version de fichier, données de configuration RC, manifeste XML d’assembly côte à côte.
4. Ajoutez un type/élément pour une nouvelle langue.	Non autorisé.	Non autorisé.
5. Supprimez un type/élément existant.	Fonctionne de la même façon que le cas 3. Utilise les données RC Config pour vérifier si le type existe dans les fichiers .mui associés au fichier LN. Si ce n’est pas le cas, la suppression du type/élément du fichier LN est autorisée. Sinon, si le type/élément existe dans les fichiers .mui associés à ce fichier LN, la suppression n’est pas autorisée.	Les seuls types autorisés à être supprimés sont : version de fichier, données de configuration RC, manifeste XML d’assembly côte à côte ; de plus, seuls les éléments de ces types peuvent être supprimés.
6. Ajoutez/supprimez/mettez à jour un type non inclus dans les données RC Config (par exemple, version, manifeste XML d’assembly côte à côte ou données RC Config elle-même).	Autorisé.	Autorisé.
7. Autre mise à jour des données non localisables, telles que TYPELIB, reginst, etc.	Mettez à jour le type ou l’élément dans le fichier LN, traitez comme non localisable et ajoutez un nouveau type ou un élément dans les données RC Config.	Sans objet.
8. Ajouter des données de configuration RC.	Vous pouvez effectuer cette opération, mais l’intégrité des données RC Config n’est pas vérifiée.	Vous pouvez effectuer cette opération, mais l’intégrité des données RC Config n’est pas vérifiée.

Exemples

Pour obtenir un exemple, consultez Mise à jour des ressources.

Note

L’en-tête winbase.h définit UpdateResource comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll