home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 June / Chip_2001-06_cd1.bin / zkuste / vbasic / Data / Utility / MSISDK15.msi / PatchApi.h < prev    next >
C/C++ Source or Header  |  2000-07-28  |  16KB  |  460 lines
  1. //
  2. //  patchapi.h
  3. //
  4. //  Interface for creating and applying patches to files.
  5. //
  6. //  Copyright (C) Microsoft, 1997-2000.
  7. //
  8.  
  9. #ifndef _PATCHAPI_H_
  10. #define _PATCHAPI_H_
  11.  
  12. #ifdef __cplusplus
  13. extern "C" {
  14. #endif
  15.  
  16. //
  17. //  The following constants can be combined and used as the OptionFlags
  18. //  parameter in the patch creation apis.
  19. //
  20.  
  21.  
  22. #define PATCH_OPTION_USE_LZX_A          0x00000001  // normal
  23. #define PATCH_OPTION_USE_LZX_B          0x00000002  // better on some x86 binaries
  24. #define PATCH_OPTION_USE_LZX_BEST       0x00000003  // auto choose best of LZX_A or LZX_B
  25. #define PATCH_OPTION_USE_BEST           0x00000000  // same as USE_LZX_BEST
  26.  
  27. #define PATCH_OPTION_USE_LZX_LARGE      0x00000004  // better support for files >4MB, patches may not apply with mspatcha.dll < 1.96
  28.  
  29. #define PATCH_OPTION_NO_BINDFIX         0x00010000  // PE bound imports
  30. #define PATCH_OPTION_NO_LOCKFIX         0x00020000  // PE smashed locks
  31. #define PATCH_OPTION_NO_REBASE          0x00040000  // PE rebased image
  32. #define PATCH_OPTION_FAIL_IF_SAME_FILE  0x00080000  // don't create if same
  33. #define PATCH_OPTION_FAIL_IF_BIGGER     0x00100000  // fail if patch is larger than simply compressing new file (slower)
  34. #define PATCH_OPTION_NO_CHECKSUM        0x00200000  // PE checksum zero
  35. #define PATCH_OPTION_NO_RESTIMEFIX      0x00400000  // PE resource timestamps
  36. #define PATCH_OPTION_NO_TIMESTAMP       0x00800000  // don't store new file timestamp in patch
  37. #define PATCH_OPTION_SIGNATURE_MD5      0x01000000  // use MD5 instead of CRC32
  38. #define PATCH_OPTION_RESERVED1          0x80000000  // (used internally)
  39.  
  40. #define PATCH_OPTION_VALID_FLAGS        0x80FF0007
  41.  
  42. #define PATCH_SYMBOL_NO_IMAGEHLP        0x00000001  // don't use imagehlp.dll
  43. #define PATCH_SYMBOL_NO_FAILURES        0x00000002  // don't fail patch due to imagehlp failures
  44. #define PATCH_SYMBOL_UNDECORATED_TOO    0x00000004  // after matching decorated symbols, try to match remaining by undecorated names
  45. #define PATCH_SYMBOL_RESERVED1          0x80000000  // (used internally)
  46.  
  47.  
  48. //
  49. //  The following constants can be combined and used as the ApplyOptionFlags
  50. //  parameter in the patch apply and test apis.
  51. //
  52.  
  53. #define APPLY_OPTION_FAIL_IF_EXACT      0x00000001  // don't copy new file
  54. #define APPLY_OPTION_FAIL_IF_CLOSE      0x00000002  // differ by rebase, bind
  55. #define APPLY_OPTION_TEST_ONLY          0x00000004  // don't create new file
  56. #define APPLY_OPTION_VALID_FLAGS        0x00000007
  57.  
  58. //
  59. //  In addition to standard Win32 error codes, the following error codes may
  60. //  be returned via GetLastError() when one of the patch APIs fails.
  61. //
  62.  
  63. #define ERROR_PATCH_ENCODE_FAILURE          0xC00E3101  // create
  64. #define ERROR_PATCH_INVALID_OPTIONS         0xC00E3102  // create
  65. #define ERROR_PATCH_SAME_FILE               0xC00E3103  // create
  66. #define ERROR_PATCH_RETAIN_RANGES_DIFFER    0xC00E3104  // create
  67. #define ERROR_PATCH_BIGGER_THAN_COMPRESSED  0xC00E3105  // create
  68. #define ERROR_PATCH_IMAGEHLP_FAILURE        0xC00E3106  // create
  69.  
  70. #define ERROR_PATCH_DECODE_FAILURE          0xC00E4101  // apply
  71. #define ERROR_PATCH_CORRUPT                 0xC00E4102  // apply
  72. #define ERROR_PATCH_NEWER_FORMAT            0xC00E4103  // apply
  73. #define ERROR_PATCH_WRONG_FILE              0xC00E4104  // apply
  74. #define ERROR_PATCH_NOT_NECESSARY           0xC00E4105  // apply
  75. #define ERROR_PATCH_NOT_AVAILABLE           0xC00E4106  // apply
  76.  
  77. typedef BOOL (CALLBACK PATCH_PROGRESS_CALLBACK)(
  78.     PVOID CallbackContext,
  79.     ULONG CurrentPosition,
  80.     ULONG MaximumPosition
  81.     );
  82.  
  83. typedef PATCH_PROGRESS_CALLBACK *PPATCH_PROGRESS_CALLBACK;
  84.  
  85. typedef BOOL (CALLBACK PATCH_SYMLOAD_CALLBACK)(
  86.     IN ULONG  WhichFile,          // 0 for new file, 1 for first old file, etc
  87.     IN LPCSTR SymbolFileName,
  88.     IN ULONG  SymType,            // see SYM_TYPE in imagehlp.h
  89.     IN ULONG  SymbolFileCheckSum,
  90.     IN ULONG  SymbolFileTimeDate,
  91.     IN ULONG  ImageFileCheckSum,
  92.     IN ULONG  ImageFileTimeDate,
  93.     IN PVOID  CallbackContext
  94.     );
  95.  
  96. typedef PATCH_SYMLOAD_CALLBACK *PPATCH_SYMLOAD_CALLBACK;
  97.  
  98. typedef struct _PATCH_IGNORE_RANGE {
  99.     ULONG OffsetInOldFile;
  100.     ULONG LengthInBytes;
  101.     } PATCH_IGNORE_RANGE, *PPATCH_IGNORE_RANGE;
  102.  
  103. typedef struct _PATCH_RETAIN_RANGE {
  104.     ULONG OffsetInOldFile;
  105.     ULONG LengthInBytes;
  106.     ULONG OffsetInNewFile;
  107.     } PATCH_RETAIN_RANGE, *PPATCH_RETAIN_RANGE;
  108.  
  109. typedef struct _PATCH_OLD_FILE_INFO_A {
  110.     ULONG               SizeOfThisStruct;
  111.     LPCSTR              OldFileName;
  112.     ULONG               IgnoreRangeCount;               // maximum 255
  113.     PPATCH_IGNORE_RANGE IgnoreRangeArray;
  114.     ULONG               RetainRangeCount;               // maximum 255
  115.     PPATCH_RETAIN_RANGE RetainRangeArray;
  116.     } PATCH_OLD_FILE_INFO_A, *PPATCH_OLD_FILE_INFO_A;
  117.  
  118. typedef struct _PATCH_OLD_FILE_INFO_W {
  119.     ULONG               SizeOfThisStruct;
  120.     LPCWSTR             OldFileName;
  121.     ULONG               IgnoreRangeCount;               // maximum 255
  122.     PPATCH_IGNORE_RANGE IgnoreRangeArray;
  123.     ULONG               RetainRangeCount;               // maximum 255
  124.     PPATCH_RETAIN_RANGE RetainRangeArray;
  125.     } PATCH_OLD_FILE_INFO_W, *PPATCH_OLD_FILE_INFO_W;
  126.  
  127. typedef struct _PATCH_OLD_FILE_INFO_H {
  128.     ULONG               SizeOfThisStruct;
  129.     HANDLE              OldFileHandle;
  130.     ULONG               IgnoreRangeCount;               // maximum 255
  131.     PPATCH_IGNORE_RANGE IgnoreRangeArray;
  132.     ULONG               RetainRangeCount;               // maximum 255
  133.     PPATCH_RETAIN_RANGE RetainRangeArray;
  134.     } PATCH_OLD_FILE_INFO_H, *PPATCH_OLD_FILE_INFO_H;
  135.  
  136. typedef struct _PATCH_OLD_FILE_INFO {
  137.     ULONG               SizeOfThisStruct;
  138.     union {
  139.         LPCSTR          OldFileNameA;
  140.         LPCWSTR         OldFileNameW;
  141.         HANDLE          OldFileHandle;
  142.         };
  143.     ULONG               IgnoreRangeCount;               // maximum 255
  144.     PPATCH_IGNORE_RANGE IgnoreRangeArray;
  145.     ULONG               RetainRangeCount;               // maximum 255
  146.     PPATCH_RETAIN_RANGE RetainRangeArray;
  147.     } PATCH_OLD_FILE_INFO, *PPATCH_OLD_FILE_INFO;
  148.  
  149. typedef struct _PATCH_OPTION_DATA {
  150.     ULONG                   SizeOfThisStruct;
  151.     ULONG                   SymbolOptionFlags;      // PATCH_SYMBOL_xxx flags
  152.     LPCSTR                  NewFileSymbolPath;      // always ANSI, never Unicode
  153.     LPCSTR                 *OldFileSymbolPathArray; // array[ OldFileCount ]
  154.     ULONG                   ExtendedOptionFlags;
  155.     PPATCH_SYMLOAD_CALLBACK SymLoadCallback;
  156.     PVOID                   SymLoadContext;
  157.     } PATCH_OPTION_DATA, *PPATCH_OPTION_DATA;
  158.  
  159. //
  160. //  Note that PATCH_OPTION_DATA contains LPCSTR paths, and no LPCWSTR (Unicode)
  161. //  path argument is available, even when used with one of the Unicode APIs
  162. //  such as CreatePatchFileW.  This is because the underlying system services
  163. //  for symbol file handling (IMAGEHLP.DLL) only support ANSI file/path names.
  164. //
  165.  
  166. //
  167. //  A note about PATCH_RETAIN_RANGE specifiers with multiple old files:
  168. //
  169. //  Each old version file must have the same RetainRangeCount, and the same
  170. //  retain range LengthInBytes and OffsetInNewFile values in the same order.
  171. //  Only the OffsetInOldFile values can differ between old files for retain
  172. //  ranges.
  173. //
  174.  
  175. #ifdef IMPORTING_PATCHAPI_DLL
  176. #define PATCHAPI WINAPI __declspec( dllimport )
  177. #else
  178. #define PATCHAPI WINAPI
  179. #endif
  180.  
  181.  
  182. //
  183. //  The following prototypes are interface for creating patches from files.
  184. //
  185.  
  186. BOOL
  187. PATCHAPI
  188. CreatePatchFileA(
  189.     IN  LPCSTR OldFileName,
  190.     IN  LPCSTR NewFileName,
  191.     OUT LPCSTR PatchFileName,
  192.     IN  ULONG  OptionFlags,
  193.     IN  PPATCH_OPTION_DATA OptionData       // optional
  194.     );
  195.  
  196. BOOL
  197. PATCHAPI
  198. CreatePatchFileW(
  199.     IN  LPCWSTR OldFileName,
  200.     IN  LPCWSTR NewFileName,
  201.     OUT LPCWSTR PatchFileName,
  202.     IN  ULONG   OptionFlags,
  203.     IN  PPATCH_OPTION_DATA OptionData       // optional
  204.     );
  205.  
  206. BOOL
  207. PATCHAPI
  208. CreatePatchFileByHandles(
  209.     IN  HANDLE OldFileHandle,
  210.     IN  HANDLE NewFileHandle,
  211.     OUT HANDLE PatchFileHandle,
  212.     IN  ULONG  OptionFlags,
  213.     IN  PPATCH_OPTION_DATA OptionData       // optional
  214.     );
  215.  
  216. BOOL
  217. PATCHAPI
  218. CreatePatchFileExA(
  219.     IN  ULONG                    OldFileCount,          // maximum 255
  220.     IN  PPATCH_OLD_FILE_INFO_A   OldFileInfoArray,
  221.     IN  LPCSTR                   NewFileName,
  222.     OUT LPCSTR                   PatchFileName,
  223.     IN  ULONG                    OptionFlags,
  224.     IN  PPATCH_OPTION_DATA       OptionData,            // optional
  225.     IN  PPATCH_PROGRESS_CALLBACK ProgressCallback,
  226.     IN  PVOID                    CallbackContext
  227.     );
  228.  
  229. BOOL
  230. PATCHAPI
  231. CreatePatchFileExW(
  232.     IN  ULONG                    OldFileCount,          // maximum 255
  233.     IN  PPATCH_OLD_FILE_INFO_W   OldFileInfoArray,
  234.     IN  LPCWSTR                  NewFileName,
  235.     OUT LPCWSTR                  PatchFileName,
  236.     IN  ULONG                    OptionFlags,
  237.     IN  PPATCH_OPTION_DATA       OptionData,            // optional
  238.     IN  PPATCH_PROGRESS_CALLBACK ProgressCallback,
  239.     IN  PVOID                    CallbackContext
  240.     );
  241.  
  242. BOOL
  243. PATCHAPI
  244. CreatePatchFileByHandlesEx(
  245.     IN  ULONG                    OldFileCount,          // maximum 255
  246.     IN  PPATCH_OLD_FILE_INFO_H   OldFileInfoArray,
  247.     IN  HANDLE                   NewFileHandle,
  248.     OUT HANDLE                   PatchFileHandle,
  249.     IN  ULONG                    OptionFlags,
  250.     IN  PPATCH_OPTION_DATA       OptionData,            // optional
  251.     IN  PPATCH_PROGRESS_CALLBACK ProgressCallback,
  252.     IN  PVOID                    CallbackContext
  253.     );
  254.  
  255. BOOL
  256. PATCHAPI
  257. ExtractPatchHeaderToFileA(
  258.     IN  LPCSTR PatchFileName,
  259.     OUT LPCSTR PatchHeaderFileName
  260.     );
  261.  
  262. BOOL
  263. PATCHAPI
  264. ExtractPatchHeaderToFileW(
  265.     IN  LPCWSTR PatchFileName,
  266.     OUT LPCWSTR PatchHeaderFileName
  267.     );
  268.  
  269. BOOL
  270. PATCHAPI
  271. ExtractPatchHeaderToFileByHandles(
  272.     IN  HANDLE PatchFileHandle,
  273.     OUT HANDLE PatchHeaderFileHandle
  274.     );
  275.  
  276. //
  277. //  The following prototypes are interface for creating new file from old file
  278. //  and patch file.  Note that it is possible for the TestApply API to succeed
  279. //  but the actual Apply to fail since the TestApply only verifies that the
  280. //  old file has the correct CRC without actually applying the patch.  The
  281. //  TestApply API only requires the patch header portion of the patch file,
  282. //  but its CRC must be fixed up.
  283. //
  284.  
  285. BOOL
  286. PATCHAPI
  287. TestApplyPatchToFileA(
  288.     IN LPCSTR PatchFileName,
  289.     IN LPCSTR OldFileName,
  290.     IN ULONG  ApplyOptionFlags
  291.     );
  292.  
  293. BOOL
  294. PATCHAPI
  295. TestApplyPatchToFileW(
  296.     IN LPCWSTR PatchFileName,
  297.     IN LPCWSTR OldFileName,
  298.     IN ULONG   ApplyOptionFlags
  299.     );
  300.  
  301. BOOL
  302. PATCHAPI
  303. TestApplyPatchToFileByHandles(
  304.     IN HANDLE PatchFileHandle,      // requires GENERIC_READ access
  305.     IN HANDLE OldFileHandle,        // requires GENERIC_READ access
  306.     IN ULONG  ApplyOptionFlags
  307.     );
  308.  
  309. BOOL
  310. PATCHAPI
  311. ApplyPatchToFileA(
  312.     IN  LPCSTR PatchFileName,
  313.     IN  LPCSTR OldFileName,
  314.     OUT LPCSTR NewFileName,
  315.     IN  ULONG  ApplyOptionFlags
  316.     );
  317.  
  318. BOOL
  319. PATCHAPI
  320. ApplyPatchToFileW(
  321.     IN  LPCWSTR PatchFileName,
  322.     IN  LPCWSTR OldFileName,
  323.     OUT LPCWSTR NewFileName,
  324.     IN  ULONG   ApplyOptionFlags
  325.     );
  326.  
  327. BOOL
  328. PATCHAPI
  329. ApplyPatchToFileByHandles(
  330.     IN  HANDLE PatchFileHandle,     // requires GENERIC_READ access
  331.     IN  HANDLE OldFileHandle,       // requires GENERIC_READ access
  332.     OUT HANDLE NewFileHandle,       // requires GENERIC_READ | GENERIC_WRITE
  333.     IN  ULONG  ApplyOptionFlags
  334.     );
  335.  
  336. BOOL
  337. PATCHAPI
  338. ApplyPatchToFileExA(
  339.     IN  LPCSTR                   PatchFileName,
  340.     IN  LPCSTR                   OldFileName,
  341.     OUT LPCSTR                   NewFileName,
  342.     IN  ULONG                    ApplyOptionFlags,
  343.     IN  PPATCH_PROGRESS_CALLBACK ProgressCallback,
  344.     IN  PVOID                    CallbackContext
  345.     );
  346.  
  347. BOOL
  348. PATCHAPI
  349. ApplyPatchToFileExW(
  350.     IN  LPCWSTR                  PatchFileName,
  351.     IN  LPCWSTR                  OldFileName,
  352.     OUT LPCWSTR                  NewFileName,
  353.     IN  ULONG                    ApplyOptionFlags,
  354.     IN  PPATCH_PROGRESS_CALLBACK ProgressCallback,
  355.     IN  PVOID                    CallbackContext
  356.     );
  357.  
  358. BOOL
  359. PATCHAPI
  360. ApplyPatchToFileByHandlesEx(
  361.     IN  HANDLE                   PatchFileHandle,
  362.     IN  HANDLE                   OldFileHandle,
  363.     OUT HANDLE                   NewFileHandle,
  364.     IN  ULONG                    ApplyOptionFlags,
  365.     IN  PPATCH_PROGRESS_CALLBACK ProgressCallback,
  366.     IN  PVOID                    CallbackContext
  367.     );
  368.  
  369. //
  370. //  The following prototypes provide a unique patch "signature" for a given
  371. //  file.  Consider the case where you have a new foo.dll and the machines
  372. //  to be updated with the new foo.dll may have one of three different old
  373. //  foo.dll files.  Rather than creating a single large patch file that can
  374. //  update any of the three older foo.dll files, three separate smaller patch
  375. //  files can be created and "named" according to the patch signature of the
  376. //  old file.  Then the patch applyer application can determine at runtime
  377. //  which of the three foo.dll patch files is necessary given the specific
  378. //  foo.dll to be updated.  If patch files are being downloaded over a slow
  379. //  network connection (Internet over a modem), this signature scheme provides
  380. //  a mechanism for choosing the correct single patch file to download at
  381. //  application time thus decreasing total bytes necessary to download.
  382. //
  383.  
  384. BOOL
  385. PATCHAPI
  386. GetFilePatchSignatureA(
  387.     IN  LPCSTR FileName,
  388.     IN  ULONG  OptionFlags,
  389.     IN  PVOID  OptionData,
  390.     IN  ULONG  IgnoreRangeCount,
  391.     IN  PPATCH_IGNORE_RANGE IgnoreRangeArray,
  392.     IN  ULONG  RetainRangeCount,
  393.     IN  PPATCH_RETAIN_RANGE RetainRangeArray,
  394.     IN  ULONG  SignatureBufferSize,
  395.     OUT PVOID  SignatureBuffer
  396.     );
  397.  
  398. BOOL
  399. PATCHAPI
  400. GetFilePatchSignatureW(
  401.     IN  LPCWSTR FileName,
  402.     IN  ULONG   OptionFlags,
  403.     IN  PVOID   OptionData,
  404.     IN  ULONG   IgnoreRangeCount,
  405.     IN  PPATCH_IGNORE_RANGE IgnoreRangeArray,
  406.     IN  ULONG   RetainRangeCount,
  407.     IN  PPATCH_RETAIN_RANGE RetainRangeArray,
  408.     IN  ULONG   SignatureBufferSizeInBytes,
  409.     OUT PVOID   SignatureBuffer
  410.     );
  411.  
  412. BOOL
  413. PATCHAPI
  414. GetFilePatchSignatureByHandle(
  415.     IN  HANDLE  FileHandle,
  416.     IN  ULONG   OptionFlags,
  417.     IN  PVOID   OptionData,
  418.     IN  ULONG   IgnoreRangeCount,
  419.     IN  PPATCH_IGNORE_RANGE IgnoreRangeArray,
  420.     IN  ULONG   RetainRangeCount,
  421.     IN  PPATCH_RETAIN_RANGE RetainRangeArray,
  422.     IN  ULONG   SignatureBufferSize,
  423.     OUT PVOID   SignatureBuffer
  424.     );
  425.  
  426.  
  427. //
  428. //  Depending on whether UNICODE is defined, map the generic API names to the
  429. //  appropriate Unicode or Ansi APIs.
  430. //
  431.  
  432. #ifdef UNICODE
  433.  
  434.     #define CreatePatchFile          CreatePatchFileW
  435.     #define CreatePatchFileEx        CreatePatchFileExW
  436.     #define TestApplyPatchToFile     TestApplyPatchToFileW
  437.     #define ApplyPatchToFile         ApplyPatchToFileW
  438.     #define ApplyPatchToFileEx       ApplyPatchToFileExW
  439.     #define ExtractPatchHeaderToFile ExtractPatchHeaderToFileW
  440.     #define GetFilePatchSignature    GetFilePatchSignatureW
  441.  
  442. #else
  443.  
  444.     #define CreatePatchFile          CreatePatchFileA
  445.     #define CreatePatchFileEx        CreatePatchFileExA
  446.     #define TestApplyPatchToFile     TestApplyPatchToFileA
  447.     #define ApplyPatchToFile         ApplyPatchToFileA
  448.     #define ApplyPatchToFileEx       ApplyPatchToFileExA
  449.     #define ExtractPatchHeaderToFile ExtractPatchHeaderToFileA
  450.     #define GetFilePatchSignature    GetFilePatchSignatureA
  451.  
  452. #endif // UNICODE
  453.  
  454. #ifdef __cplusplus
  455. }
  456. #endif
  457.  
  458. #endif // _PATCHAPI_H_
  459.  
  460.