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 是資源識別碼。建立新資源時，不會使用以此參數 '#' 字元開頭的字串。

[in] wLanguage

類型： WORD

要更新之資源的語言識別項。如需組成語言識別項的主要語言識別項和子語言識別項清單，請參閱 MAKELANGID 宏。

[in, optional] lpData

類型： LPVOID

要插入 hUpdate所指示之檔案的資源資料。如果資源是其中一個預先定義的類型，資料必須有效且正確對齊。請注意，這是要儲存在 hUpdate所指示之檔案中的原始二進位資料，而不是 LoadIcon、 LoadString或其他資源特定載入函式所提供的資料。包含字串或文字的所有資料都必須是 Unicode 格式。 lpData 不得指向 ANSI 資料。

如果 lpData 為 Null 且 cbData 為 0，則會從 hUpdate所指示的檔案中刪除指定的資源。

[in] cb

類型： DWORD

資源資料的大小，以位元組為單位，位於 lpData。

傳回值

類型： BOOL

如果成功或 FALSE，則傳回 TRUE 。否則傳回 TRUE 。若要取得擴充的錯誤資訊，請呼叫 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 組態資料來檢查類型是否存在於與此 LN 檔案相關聯的 .mui 檔案中。如果類型不存在於 .mui 檔案中，請新增專案，並將新專案視為無法當地語系化。如果類型存在於 .mui 檔案中，則不允許新增。	只能新增下列類型的專案：檔案版本、RC 設定資料、並存元件 XML 資訊清單。
3.更新資源專案。	使用 RC 組態資料來檢查類型是否存在於與 LN 檔案相關聯的 .mui 檔案中。如果 .mui 檔案中不存在此類型，則 LN 檔案中允許此資源專案更新。否則，如果類型存在於與此 LN 檔案相關聯的 .mui 檔案中，則不允許此更新。	唯一允許的更新是下列類型的專案：檔案版本、RC 設定資料、並存元件 XML 資訊清單。
4.為新語言新增類型/專案。	不允許。	不允許。
5.移除現有的類型/專案。	運作方式與案例 3 類似。使用 RC 組態資料來檢查類型是否存在於與 LN 檔案相關聯的 .mui 檔案中。如果沒有，則允許從 LN 檔案中移除類型/專案。否則，如果類型/專案存在於與此 LN 檔案相關聯的 .mui 檔案中，則不允許移除。	唯一允許移除的類型包括：檔案版本、RC 設定資料、並存元件 XML 資訊清單;此外，只能移除這些類型的專案。
6.新增/刪除/更新 RC 設定資料中不包含的類型， (例如版本、並存元件 XML 資訊清單或 RC 設定資料本身) 。	已允許。	已允許。
7.其他無法當地語系化的資料更新，例如 TYPELIB、reginst 等等。	更新 LN 檔案中的類型或專案、視為不可當地語系化，並在 RC 組態資料中新增類型或專案。	不適用。
8.新增 RC 設定資料。	可以完成，但不會檢查 RC 設定資料的完整性。	可以完成，但不會檢查 RC 設定資料的完整性。

範例

如需範例，請參閱更新資源。

注意

winbase.h 標頭會將 UpdateResource 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求


最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll