Функция UpdateResourceA (winbase.h)

Статья
03/08/2023

Добавляет, удаляет или заменяет ресурс в переносимом исполняемом файле (PE). Существуют некоторые ограничения на обновления ресурсов в файлах, содержащих данные конфигурации ресурсов (RC Config): файлы, не зависящие от языка (LN) и файлы ресурсов для конкретного языка (MUI).

Синтаксис

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

Параметры

[in] hUpdate

Тип: HANDLE

Дескриптор модуля, возвращаемый функцией BeginUpdateResource , ссылающийся на обновляемый файл.

[in] lpType

Тип: LPCTSTR

Тип обновляемого ресурса. Кроме того, вместо указателя этот параметр может иметь значение MAKEINTRESOURCE(ID), где ID — это целочисленное значение, представляющее предопределенный тип ресурса. Если первым символом строки является знак фунта (#), остальные символы представляют десятичное число, указывающее целочисленный идентификатор типа ресурса. Например, строка "#258" представляет идентификатор 258.

Список стандартных типов ресурсов см. в разделе Типы ресурсов.

[in] lpName

Тип: LPCTSTR

Имя обновляемого ресурса. Кроме того, вместо указателя этот параметр может иметь значение MAKEINTRESOURCE(ID), где ID — это идентификатор ресурса. При создании ресурса не используйте строку, которая начинается с символа "#" для этого параметра.

[in] wLanguage

Тип: WORD

Идентификатор языка обновляемого ресурса. Список идентификаторов основного языка и подязык, составляющих идентификатор языка, см. в макросе MAKELANGID .

[in, optional] lpData

Тип: LPVOID

Данные ресурса, которые необходимо вставить в файл, указанный параметром hUpdate. Если ресурс является одним из предопределенных типов, данные должны быть допустимыми и соответствующим образом выровнены. Обратите внимание, что это необработанные двоичные данные, которые должны храниться в файле, указанном hUpdate, а не в данных, предоставляемых LoadIcon, LoadString или другими функциями загрузки, зависящими от ресурсов. Все данные, содержащие строки или текст, должны быть в формате Юникода. lpData не должен указывать на данные ANSI.

Если lpData имеет значение NULL , а cbData равно 0, указанный ресурс удаляется из файла, указанного параметром hUpdate.

[in] cb

Тип: DWORD

Размер данных ресурса в lpData в байтах.

Возвращаемое значение

Тип: BOOL

Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Приложение может многократно использовать UpdateResource для внесения изменений в данные ресурса. Каждый вызов UpdateResource вносит вклад в внутренний список дополнений, удалений и замен, но фактически не записывает данные в файл, указанный hUpdate. Приложение должно использовать функцию EndUpdateResource для записи накопленных изменений в файл.

Эта функция может обновлять ресурсы в модулях, содержащих как код, так и ресурсы.

До Windows 7: Если lpData имеет значение NULL , а cbData не равно нулю, указанный ресурс НЕ удаляется и создается исключение.

Начиная с Windows Vista: Как отмечалось выше, существуют ограничения на обновления ресурсов в файлах, содержащих данные конфигурации RC: LN-файлы и MUI-файлы. Ниже приведены ограничения.

Действие	LN-файл	MUI-файл
1. Добавьте новый тип, который не существует в файлах LN или MUI.	Добавьте тип в LN-файл и рассматривайте как не зависящий от языка (не локализуемый) и добавьте новый тип или элемент в данные конфигурации rc.	Единственными допустимыми дополнениями являются следующие типы: версия файла, данные конфигурации rc, xml-манифест параллельной сборки.
2. Добавление нового элемента ресурса к существующему типу.	Использует данные конфигурации rc для проверка, существует ли тип в MUI-файлах, связанных с этим LN-файлом. Если тип не существует в MUI-файлах, добавьте элемент и обработайте новый элемент как не локализуемый. Если тип существует в MUI-файлах, добавление запрещено.	Можно добавлять только элементы следующих типов: версия файла, данные конфигурации rc, xml-манифест параллельной сборки.
3. Обновление элемента ресурса.	Использует данные конфигурации-кандидата для проверка, существует ли тип в MUI-файлах, связанных с LN-файлом. Если тип не существует в MUI-файлах, обновление этого элемента ресурса разрешено в LN-файле. В противном случае, если тип существует в MUI-файлах, связанных с этим LN-файлом, это обновление запрещено.	Единственными допустимыми обновлениями являются элементы следующих типов: версия файла, данные конфигурации RC, xml-манифест параллельной сборки.
4. Добавьте тип или элемент для нового языка.	Не допускается.	Не допускается.
5. Удаление существующего типа или элемента.	Работает аналогично варианту 3. Использует данные конфигурации-кандидата для проверка, существует ли тип в MUI-файлах, связанных с LN-файлом. В противном случае удаление типа или элемента из LN-файла разрешено. В противном случае, если тип или элемент существует в MUI-файлах, связанных с этим LN-файлом, удаление запрещено.	Единственные типы, которые можно удалить: версия файла, данные конфигурации RC, xml-манифест параллельной сборки; кроме того, могут быть удалены только элементы этих типов.
6. Добавление, удаление и обновление типа, не включенного в данные конфигурации-кандидата (например, версия, XML-манифест параллельной сборки или сами данные конфигурации RC).	разрешено.	разрешено.
7. Другое обновление нелокализуемых данных, таких как TYPELIB, reginst и т. д.	Обновите тип или элемент в LN-файле, обработайте его как не локализуемые и добавьте новый тип или элемент в данные конфигурации rc.	Не применяется
8. Добавьте данные конфигурации RC.	Это можно сделать, но целостность данных конфигурации rc не проверяется.	Это можно сделать, но целостность данных конфигурации rc не проверяется.

Примеры

Пример см. в разделе Обновление ресурсов.

Примечание

Заголовок winbase.h определяет UpdateResource как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll