UpdateResourceA, fonction (winbase.h)

Article
08/27/2023

Ajoute, supprime ou remplace une ressource dans un fichier exécutable portable (PE). Il existe certaines restrictions sur les mises à jour de ressources dans les fichiers qui contiennent des données de configuration de ressource (configuration RC) : fichiers non linguistiques (LN) et fichiers de ressources spécifiques à la langue (.mui).

Syntaxe

BOOL UpdateResourceA(
  [in]           HANDLE hUpdate,
  [in]           LPCSTR lpType,
  [in]           LPCSTR 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, plutôt qu’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 dièse (#), 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ù ID est un ID de ressource. Lors de la création d’une ressource, n’utilisez pas une chaîne qui commence 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 principale 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 des données fournies par LoadIcon, LoadString ou d’autres fonctions de charge 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 a la valeur NULL et que cbData a la valeur 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 sur lpData.

Valeur retournée

Type : BOOL

Retourne TRUE en cas de réussite ou FALSE dans le cas contraire. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Il est recommandé de ne pas charger le fichier de ressources avant l’appel de cette fonction. Toutefois, si ce fichier est déjà chargé, aucune erreur n’est retournée.

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 dans des modules qui contiennent à la fois du code et des ressources.

Avant Windows 7 : Si lpData a la valeur NULL et que cbData est différent de zéro, la ressource spécifiée n’est PAS supprimée et une exception est levée.

À compter 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 de configuration RC : 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 étant indépendant de la langue (non localisable) et ajoutez un nouveau type ou un nouvel élément dans les données de configuration RC	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 de configuration RC pour case activée 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. Mettre à jour un élément de ressource.	Utilise les données de configuration RC pour case activée 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 de l’é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. Ajouter 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 de configuration RC pour case activée 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 ; en outre, seuls les éléments de ces types peuvent être supprimés.
6. Ajouter/supprimer/mettre à jour un type non inclus dans les données de configuration RC (par exemple, Version, Manifeste XML d’assembly côte à côte ou données de configuration RC proprement dite).	Autorisé.	Autorisé.
7. Autres mises à 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 nouvel élément dans les données de configuration RC.	Non applicable.
8. Ajouter des données de configuration RC.	Peut être effectué, mais l’intégrité des données de configuration RC n’est pas vérifiée.	Peut être effectué, mais l’intégrité des données de configuration RC n’est pas vérifiée.

Exemples

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

Notes

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. La combinaison 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.

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll