Função UpdateResourceA (winbase.h)

Artigo
03/08/2023

Adiciona, exclui ou substitui um recurso em um arquivo PE (executável portátil). Há algumas restrições em atualizações de recursos em arquivos que contêm dados de Configuração de Recursos (Configuração de RC): arquivos LN ( neutros em linguagem ) e arquivos de recurso específicos da linguagem (.mui).

Sintaxe

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

Parâmetros

[in] hUpdate

Tipo: HANDLE

Um identificador de módulo retornado pela função BeginUpdateResource , fazendo referência ao arquivo a ser atualizado.

[in] lpType

Tipo: LPCTSTR

O tipo de recurso a ser atualizado. Como alternativa, em vez de um ponteiro, esse parâmetro pode ser MAKEINTRESOURCE(ID), em que ID é um valor inteiro que representa um tipo de recurso predefinido. Se o primeiro caractere da cadeia de caracteres for um sinal de libra (#), os caracteres restantes representarão um número decimal que especifica o identificador inteiro do tipo de recurso. Por exemplo, a cadeia de caracteres "#258" representa o identificador 258.

Para obter uma lista de tipos de recursos predefinidos, consulte Tipos de recursos.

[in] lpName

Tipo: LPCTSTR

O nome do recurso a ser atualizado. Como alternativa, em vez de um ponteiro, esse parâmetro pode ser MAKEINTRESOURCE(ID), em que ID é uma ID de recurso. Ao criar um novo recurso, não use uma cadeia de caracteres que começa com um caractere '#' para esse parâmetro.

[in] wLanguage

Tipo: WORD

O identificador de idioma do recurso a ser atualizado. Para obter uma lista dos identificadores de idioma primários e identificadores de sublanguagem que compõem um identificador de linguagem, consulte a macro MAKELANGID .

[in, optional] lpData

Tipo: LPVOID

Os dados de recurso a serem inseridos no arquivo indicado por hUpdate. Se o recurso for um dos tipos predefinidos, os dados deverão ser válidos e alinhados corretamente. Observe que esses são os dados binários brutos a serem armazenados no arquivo indicado por hUpdate, não os dados fornecidos por LoadIcon, LoadString ou outras funções de carga específicas do recurso. Todos os dados que contêm cadeias de caracteres ou texto devem estar no formato Unicode. lpData não deve apontar para dados ANSI.

Se lpData for NULL e cbData for 0, o recurso especificado será excluído do arquivo indicado por hUpdate.

[in] cb

Tipo: DWORD

O tamanho, em bytes, dos dados de recurso em lpData.

Valor retornado

Tipo: BOOL

Retornará TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, chame GetLastError.

Comentários

É recomendável que o arquivo de recurso não seja carregado antes que essa função seja chamada. No entanto, se esse arquivo já estiver carregado, ele não fará com que um erro seja retornado.

Um aplicativo pode usar UpdateResource repetidamente para fazer alterações nos dados do recurso. Cada chamada para UpdateResource contribui para uma lista interna de adições, exclusões e substituições, mas não grava os dados no arquivo indicado por hUpdate. O aplicativo deve usar a função EndUpdateResource para gravar as alterações acumuladas no arquivo.

Essa função pode atualizar recursos em módulos que contêm código e recursos.

Antes do Windows 7: Se lpData for NULL e cbData não for zero, o recurso especificado NÃO será excluído e uma exceção será gerada.

Começando com o Windows Vista: Conforme observado acima, há restrições sobre atualizações de recursos em arquivos que contêm dados de configuração de RC: arquivos LN e arquivos .mui. As restrições são as seguintes:

Ação	Arquivo LN	Arquivo .mui
1. Adicione um novo tipo que não existe nos arquivos LN ou .mui.	Adicione o tipo no arquivo LN e trate como neutro em linguagem (não localizável) e adicione um novo tipo ou item nos dados de configuração do RC	As únicas adições permitidas são os seguintes tipos: versão do arquivo, dados de configuração de RC, manifesto XML de assembly lado a lado.
2. Adicione um novo item de recurso a um tipo existente.	Usa os dados de configuração do RC para marcar se o tipo existe nos arquivos .mui associados a esse arquivo LN. Se o tipo não existir nos arquivos .mui, adicione o item e trate o novo item como não localizável. Se o tipo existir nos arquivos .mui, a adição não será permitida.	Somente itens dos seguintes tipos podem ser adicionados: versão do arquivo, dados de configuração de RC, manifesto XML de assembly lado a lado.
3. Atualizar um item de recurso.	Usa os dados de configuração do RC para marcar se o tipo existe nos arquivos .mui associados ao arquivo LN. Se o tipo não existir nos arquivos .mui, essa atualização de item de recurso será permitida no arquivo LN. Caso contrário, se o tipo existir nos arquivos .mui associados a esse arquivo LN, essa atualização não será permitida.	As únicas atualizações permitidas são itens dos seguintes tipos: versão do arquivo, dados de configuração RC, manifesto XML de assembly lado a lado.
4. Adicionar um tipo/item para um novo idioma.	Não permitido.	Não permitido.
5. Remover um tipo/item existente.	Funciona de forma semelhante ao caso 3. Usa os dados de configuração do RC para marcar se o tipo existe nos arquivos .mui associados ao arquivo LN. Caso contrário, a remoção do tipo/item do arquivo LN é permitida. Caso contrário, se o tipo/item existir nos arquivos .mui associados a esse arquivo LN, a remoção não será permitida.	Os únicos tipos que podem ser removidos são: versão do arquivo, dados de configuração RC, manifesto XML de assembly lado a lado; além disso, somente itens desses tipos podem ser removidos.
6. Adicione/exclua/atualize um tipo não incluído nos dados de Configuração do RC (como versão, manifesto XML de assembly lado a lado ou dados de configuração RC propriamente ditos).	Permitido.	Permitido.
7. Outra atualização de dados não localizáveis, como TYPELIB, reginst e assim por diante.	Atualize o tipo ou item no arquivo LN, trate como não localizável e adicione um novo tipo ou item nos dados de Configuração do RC.	Não aplicável.
8. Adicionar dados de configuração de RC.	Pode ser feito, mas a integridade dos dados de configuração do RC não é verificada.	Pode ser feito, mas a integridade dos dados de configuração do RC não é verificada.

Exemplos

Para obter um exemplo, consulte Atualizando recursos.

Observação

O cabeçalho winbase.h define UpdateResource como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll