UpdateResourceA-Funktion (winbase.h)

Artikel
03/08/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 UpdateResourceA(
  [in]           HANDLE hUpdate,
  [in]           LPCSTR lpType,
  [in]           LPCSTR lpName,
  [in]           WORD   wLanguage,
  [in, optional] LPVOID lpData,
  [in]           DWORD  cb
);

Parameter

[in] hUpdate

Typ: HANDLE

Ein Modulhandle, das von der BeginUpdateResource-Funktion zurückgegeben wird und 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 restlichen 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 dem 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 Makro MAKELANGID .

[in, optional] lpData

Typ: LPVOID

Die Ressourcendaten, die in die von hUpdate angegebene Datei eingefügt werden sollen. Wenn es sich bei der Ressource um einen der vordefinierten Typen handelt, müssen die Daten gültig und ordnungsgemäß ausgerichtet sein. Beachten Sie, dass dies die rohen Binärdaten 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 0 ist, wird die angegebene Ressource aus der von hUpdate angegebenen Datei gelöscht.

[in] cb

Art: DWORD

Die Größe der Ressourcendaten bei lpData in Bytes.

Rückgabewert

Typ: BOOL

Gibt TRUE zurück, wenn der Vorgang 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 von 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 nonzero ist, wird die angegebene Ressource NICHT gelöscht, und eine Ausnahme wird ausgelöst.

Ab Windows Vista: Wie oben erwähnt, gibt es Einschränkungen für Ressourcenupdates in Dateien, die RC Config-Daten 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 Config-Daten einen neuen Typ oder Element hinzu.	Die einzigen zulässigen Ergänzungen sind die folgenden Typen: Dateiversion, RC-Konfigurationsdaten, Paralleles XML-Manifest der Assembly.
2. Fügen Sie einem vorhandenen Typ ein neues Ressourcenelement hinzu.	Verwendet die RC Config-Daten, 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 XML-Manifest der Assembly.
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 XML-Manifest der Assembly.
4. Fügen Sie einen Typ/Element für eine neue Sprache hinzu.	Nicht zulässig.	Nicht zulässig.
5. Entfernen Sie einen vorhandenen Typ/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 Config-Daten enthalten ist (z. B. Version, Paralleles Assembly-XML-Manifest oder RC Config-Daten selbst).	Erlaubt.	Erlaubt.
7. Andere Aktualisierungen nicht lokalisierbarer 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 element hinzu.	Nicht zutreffend.
8. Fügen Sie RC Config-Daten hinzu.	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 nicht codierungsneutralem Code 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 (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll