Funzione UpdateResourceA (winbase.h)

Articolo
03/08/2023

Aggiunge, elimina o sostituisce una risorsa in un file eseguibile portabile (PE). Esistono alcune restrizioni per gli aggiornamenti delle risorse nei file che contengono dati di Configurazione risorse (RC Config): file LN ( Language Neutral ) e file di risorse specifiche della lingua (mui).

Sintassi

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

Parametri

[in] hUpdate

Tipo: HANDLE

Handle del modulo restituito dalla funzione BeginUpdateResource , che fa riferimento al file da aggiornare.

[in] lpType

Tipo: LPCTSTR

Tipo di risorsa da aggiornare. In alternativa, anziché un puntatore, questo parametro può essere MAKEINTRESOURCE(ID), dove ID è un valore integer che rappresenta un tipo di risorsa predefinito. Se il primo carattere della stringa è un segno di cancelletto (#), i caratteri rimanenti rappresentano un numero decimale che specifica l'identificatore integer del tipo di risorsa. Ad esempio, la stringa "#258" rappresenta l'identificatore 258.

Per un elenco dei tipi di risorse predefiniti, vedere Tipi di risorse.

[in] lpName

Tipo: LPCTSTR

Nome della risorsa da aggiornare. In alternativa, anziché un puntatore, questo parametro può essere MAKEINTRESOURCE(ID), dove ID è un ID risorsa. Quando si crea una nuova risorsa non viene usata una stringa che inizia con un carattere '#' per questo parametro.

[in] wLanguage

Tipo: WORD

Identificatore della lingua della risorsa da aggiornare. Per un elenco degli identificatori di lingua primaria e degli identificatori di sottolanguage che costituiscono un identificatore di lingua, vedere la macro MAKELANGID .

[in, optional] lpData

Tipo: LPVOID

Dati delle risorse da inserire nel file indicato da hUpdate. Se la risorsa è uno dei tipi predefiniti, i dati devono essere validi e allineati correttamente. Si noti che si tratta dei dati binari non elaborati da archiviare nel file indicato da hUpdate, non i dati forniti da LoadIcon, LoadString o altre funzioni di caricamento specifiche della risorsa. Tutti i dati contenenti stringhe o testo devono essere in formato Unicode. lpData non deve puntare ai dati ANSI.

Se lpData è NULL e cbData è 0, la risorsa specificata viene eliminata dal file indicato da hUpdate.

[in] cb

Tipo: DWORD

Dimensioni, in byte, dei dati della risorsa in lpData.

Valore restituito

Tipo: BOOL

Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

È consigliabile che il file di risorse non venga caricato prima di chiamare questa funzione. Tuttavia, se il file è già caricato, non verrà restituito un errore.

Un'applicazione può usare ripetutamente UpdateResource per apportare modifiche ai dati delle risorse. Ogni chiamata a UpdateResource contribuisce a un elenco interno di aggiunte, eliminazioni e sostituzioni, ma non scrive effettivamente i dati nel file indicato da hUpdate. L'applicazione deve usare la funzione EndUpdateResource per scrivere le modifiche accumulate nel file.

Questa funzione può aggiornare le risorse all'interno di moduli che contengono sia codice che risorse.

Prima di Windows 7: Se lpData è NULL e cbData è diverso da zero, la risorsa specificata NON viene eliminata e viene generata un'eccezione.

A partire da Windows Vista: Come indicato in precedenza, esistono restrizioni per gli aggiornamenti delle risorse nei file che contengono dati di configurazione RC: file LN e file mui. Le restrizioni sono le seguenti:

Azione	File LN	File mui
1. Aggiungere un nuovo tipo che non esiste nei file LN o mui.	Aggiungere il tipo nel file LN e trattare come indipendente dalla lingua (non localizzabile) e aggiungere un nuovo tipo o elemento nei dati di configurazione RC	Le uniche aggiunte consentite sono i tipi seguenti: versione del file, dati rc di configurazione, manifesto XML dell'assembly side-by-side.
2. Aggiungere un nuovo elemento di risorsa a un tipo esistente.	Usa i dati di configurazione RC per verificare se il tipo esiste nei file mui associati a questo file LN. Se il tipo non esiste nei file con estensione mui, aggiungere l'elemento e trattare il nuovo elemento come non localizzabile. Se il tipo esiste nei file con estensione mui, l'aggiunta non è consentita.	È possibile aggiungere solo gli elementi dei tipi seguenti: Versione file, Dati di configurazione RC, Manifesto XML dell'assembly side-by-side.
3. Aggiornare un elemento della risorsa.	Usa i dati di configurazione RC per verificare se il tipo esiste nei file mui associati al file LN. Se il tipo non esiste nei file mui, questo aggiornamento dell'elemento di risorsa è consentito nel file LN. In caso contrario, se il tipo esiste nei file mui associati a questo file LN, questo aggiornamento non è consentito.	Gli unici aggiornamenti consentiti sono gli elementi dei tipi seguenti: file Version, RC Config data, Side-by-side Assembly XML Manifest.
4. Aggiungere un tipo/elemento per una nuova lingua.	Non consentiti.	Non consentiti.
5. Rimuovere un tipo o un elemento esistente.	Funziona in modo analogo al caso 3. Usa i dati di configurazione RC per verificare se il tipo esiste nei file mui associati al file LN. In caso contrario, è consentita la rimozione del tipo/elemento dal file LN. In caso contrario, se il tipo/elemento esiste nei file mui associati a questo file LN, la rimozione non è consentita.	Gli unici tipi che possono essere rimossi sono: versione del file, dati rc di configurazione, manifesto XML dell'assembly side-by-side; inoltre, solo gli elementi di questi tipi possono essere rimossi.
6. Aggiungere/eliminare/aggiornare un tipo non incluso nei dati di configurazione RC (ad esempio Versione, Manifesto XML assembly affiancato o dati RC Config).	Consentito.	Consentito.
7. Altro aggiornamento di dati non localizzabili, ad esempio TYPELIB, reginst e così via.	Aggiornare il tipo o l'elemento nel file LN, trattare come non localizzabile e aggiungere un nuovo tipo o elemento nei dati rc config.	Non applicabile.
8. Aggiungere dati di configurazione RC.	È possibile eseguire questa operazione, ma l'integrità dei dati di configurazione RC non è selezionata.	È possibile eseguire questa operazione, ma l'integrità dei dati di configurazione RC non è selezionata.

Esempio

Per un esempio, vedere Aggiornamento delle risorse.

Nota

L'intestazione winbase.h definisce UpdateResource come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll