UpdateResourceW-Funktion (winbase.h)

Artikel
08/27/2023

Fügt eine Ressource in einer portablen ausführbaren Datei (PE) hinzu, löscht oder ersetzt sie. Es gibt einige Einschränkungen für Ressourcenupdates in Dateien, die Ressourcenkonfigurationsdaten (RC Config) enthalten: sprachneutrale Dateien (LN) und sprachspezifische Ressourcendateien (.mui).

Syntax

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

Parameter

[in] hUpdate

Typ: HANDLE

Ein von der BeginUpdateResource-Funktion zurückgegebenes Modulhandle, das auf die zu aktualisierende Datei verweist.

[in] lpType

Typ: LPCTSTR

Der zu aktualisierende Ressourcentyp. Alternativ kann dieser Parameter anstelle eines Zeigers MAKEINTRESOURCE(ID) sein, wobei ID ein ganzzahliger Wert ist, der einen vordefinierten Ressourcentyp darstellt. Wenn das erste Zeichen der Zeichenfolge ein Pfundzeichen (#) ist, stellen die verbleibenden Zeichen eine Dezimalzahl dar, die den ganzzahligen Bezeichner des Ressourcentyps angibt. Die Zeichenfolge "#258" stellt beispielsweise den Bezeichner 258 dar.

Eine Liste der vordefinierten Ressourcentypen finden Sie unter Ressourcentypen.

[in] lpName

Typ: LPCTSTR

Der Name der zu aktualisierenden Ressource. Alternativ kann dieser Parameter anstelle eines Zeigers MAKEINTRESOURCE(ID) sein, wobei ID eine Ressourcen-ID ist. Verwenden Sie beim Erstellen einer neuen Ressource keine Zeichenfolge, die mit einem "#"-Zeichen für diesen Parameter beginnt.

[in] wLanguage

Typ: WORD

Der Sprachbezeichner der zu aktualisierenden Ressource. Eine Liste der primären Sprachbezeichner und Untersprachebezeichner, aus denen ein Sprachbezeichner besteht, finden Sie im MAKELANGID-Makro .

[in, optional] lpData

Typ: LPVOID

Die Ressourcendaten, die in die durch hUpdate angegebene Datei eingefügt werden sollen. Wenn die Ressource einer der vordefinierten Typen ist, müssen die Daten gültig und ordnungsgemäß ausgerichtet sein. Beachten Sie, dass dies die binären Rohdaten sind, die in der datei gespeichert werden sollen, die von hUpdate angegeben wird, nicht die Daten, die von LoadIcon, LoadString oder anderen ressourcenspezifischen Ladefunktionen bereitgestellt werden. Alle Daten, die Zeichenfolgen oder Text enthalten, müssen im Unicode-Format vorliegen. lpData darf nicht auf ANSI-Daten verweisen.

Wenn lpDataNULL und cbData den Wert 0 aufweist, wird die angegebene Ressource aus der durch hUpdate angegebenen Datei gelöscht.

[in] cb

Art: DWORD

Die Größe der Ressourcendaten in lpData in Byte.

Rückgabewert

Typ: BOOL

Gibt TRUE zurück, wenn dies erfolgreich war, oder andernfalls FALSE . Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Es wird empfohlen, dass die Ressourcendatei nicht geladen wird, bevor diese Funktion aufgerufen wird. Wenn diese Datei jedoch bereits geladen ist, wird kein Fehler zurückgegeben.

Eine Anwendung kann UpdateResource wiederholt verwenden, um Änderungen an den Ressourcendaten vorzunehmen. Jeder Aufruf von UpdateResource trägt zu einer internen Liste von Ergänzungen, Löschungen und Ersetzungen bei, schreibt die Daten jedoch nicht tatsächlich in die durch hUpdate angegebene Datei. Die Anwendung muss die EndUpdateResource-Funktion verwenden, um die akkumulierten Änderungen in die Datei zu schreiben.

Diese Funktion kann Ressourcen in Modulen aktualisieren, die sowohl Code als auch Ressourcen enthalten.

Vor Windows 7: Wenn lpDataNULL und cbData ungleich null ist, wird die angegebene Ressource NICHT gelöscht, und es wird eine Ausnahme ausgelöst.

Ab Windows Vista: Wie bereits erwähnt, gibt es Einschränkungen für Ressourcenupdates in Dateien, die RC-Konfigurationsdaten enthalten: LN-Dateien und MUI-Dateien. Die Einschränkungen sind wie folgt:

Aktion	LN-Datei	MUI-Datei
1. Fügen Sie einen neuen Typ hinzu, der in den LN- oder MUI-Dateien nicht vorhanden ist.	Fügen Sie den Typ in der LN-Datei hinzu, und behandeln Sie sie als sprachneutral (nicht lokalisierbar), und fügen Sie den RC-Konfigurationsdaten einen neuen Typ oder Ein neues Element hinzu.	Die einzigen zulässigen Ergänzungen sind die folgenden Typen: Dateiversion, RC-Konfigurationsdaten, Paralleles Assembly-XML-Manifest.
2. Fügen Sie einem vorhandenen Typ ein neues Ressourcenelement hinzu.	Verwendet die RC-Konfigurationsdaten, um zu überprüfen, ob der Typ in den MUI-Dateien vorhanden ist, die dieser LN-Datei zugeordnet sind. Wenn der Typ in den MUI-Dateien nicht vorhanden ist, fügen Sie das Element hinzu, und behandeln Sie das neue Element als nicht lokalisierbar. Wenn der Typ in den MUI-Dateien vorhanden ist, ist das Hinzufügen nicht zulässig.	Es können nur Elemente der folgenden Typen hinzugefügt werden: Dateiversion, RC-Konfigurationsdaten, Paralleles Assembly-XML-Manifest.
3. Aktualisieren sie ein Ressourcenelement.	Verwendet die RC Config-Daten, um zu überprüfen, ob der Typ in den MUI-Dateien vorhanden ist, die der LN-Datei zugeordnet sind. Wenn der Typ in den MUI-Dateien nicht vorhanden ist, ist dieses Ressourcenelementupdate in der LN-Datei zulässig. Andernfalls ist dieses Update nicht zulässig, wenn der Typ in den MUI-Dateien vorhanden ist, die dieser LN-Datei zugeordnet sind.	Die einzigen zulässigen Updates sind Elemente der folgenden Typen: Dateiversion, RC-Konfigurationsdaten, paralleles Assembly-XML-Manifest.
4. Fügen Sie einen Typ bzw. ein Element für eine neue Sprache hinzu.	Nicht zulässig.	Nicht zulässig.
5. Entfernen Sie einen vorhandenen Typ bzw. ein vorhandenes Element.	Funktioniert ähnlich wie Fall 3. Verwendet die RC Config-Daten, um zu überprüfen, ob der Typ in den MUI-Dateien vorhanden ist, die der LN-Datei zugeordnet sind. Andernfalls ist das Entfernen des Typs/Elements aus der LN-Datei zulässig. Andernfalls ist das Entfernen nicht zulässig, wenn der Typ/das Element in den MUI-Dateien vorhanden ist, die dieser LN-Datei zugeordnet sind.	Die einzigen Typen, die entfernt werden dürfen, sind: Dateiversion, RC-Konfigurationsdaten, Paralleles Assembly-XML-Manifest; außerdem können nur Elemente dieser Typen entfernt werden.
6. Hinzufügen/Löschen/Aktualisieren eines Typs, der nicht in den RC-Konfigurationsdaten enthalten ist (z. B. Version, paralleles Assembly-XML-Manifest oder RC Config-Daten selbst).	Erlaubt.	Erlaubt.
7. Andere Aktualisierungen von nicht lokalisierbaren Daten, z. B. TYPELIB, reginst usw.	Aktualisieren Sie den Typ oder das Element in der LN-Datei, behandeln Sie sie als nicht lokalisierbar, und fügen Sie den RC Config-Daten einen neuen Typ oder ein neues Element hinzu.	Nicht zutreffend.
8. Hinzufügen von RC-Konfigurationsdaten.	Kann ausgeführt werden, aber die Integrität der RC Config-Daten wird nicht überprüft.	Kann ausgeführt werden, aber die Integrität der RC Config-Daten wird nicht überprüft.

Beispiele

Ein Beispiel finden Sie unter Aktualisieren von Ressourcen.

Hinweis

Der winbase.h-Header definiert UpdateResource als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll