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

Статья
11/20/2024

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

Синтаксис

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

Параметры

[in] hUpdate

Тип: HANDLE

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

[in] lpType

Тип: LPCTSTR

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

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

[in] lpName

Тип: LPCTSTR

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

[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. Обновление элемента ресурса.	Использует данные конфигурации RC для проверки того, существует ли тип в файлах MUI, связанных с LN-файлом. Если тип не существует в mui-файлах, это обновление элемента ресурса разрешено в файле LN. В противном случае, если тип существует в файлах MUI, связанных с этим LN-файлом, это обновление не допускается.	Единственными допустимыми обновлениями являются элементы следующих типов: версия файла, данные конфигурации RC, xml-манифест сборки параллельно.
4. Добавьте тип или элемент для нового языка.	Запрещено.	Запрещено.
5. Удалите существующий тип или элемент.	Работает аналогично варианту 3. Использует данные конфигурации RC для проверки того, существует ли тип в файлах MUI, связанных с LN-файлом. В противном случае разрешено удаление типа или элемента из LN-файла. В противном случае, если тип или элемент существует в файлах MUI, связанных с этим LN-файлом, удаление не допускается.	Единственными типами, разрешенными для удаления, являются: версия файла, данные конфигурации RC, xml-манифест параллельной сборки; Кроме того, могут быть удалены только элементы этих типов.
6. Добавление и удаление или обновление типа, не включенного в данные конфигурации RC (например, версия, xml-манифест сборки параллельной сборки или данные конфигурации RC).	Дозволенный.	Дозволенный.
7. Другое обновление не локализуемых данных, таких как TYPELIB, reginst и т. д.	Обновите тип или элемент в файле LN, обрабатывают как не локализуемые и добавляют новый тип или элемент в данные конфигурации RC.	Неприменимо.
8. Добавление данных конфигурации RC.	Можно сделать, но целостность данных конфигурации RC не проверяется.	Можно сделать, но целостность данных конфигурации RC не проверяется.

Примеры

Пример см. в обновлении ресурсов.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll