WinGetUtil.h (12467B)
1 // Copyright (c) Microsoft Corporation. 2 // Licensed under the MIT License. 3 #pragma once 4 5 extern "C" 6 { 7 // A handle to the index. 8 typedef void* WINGET_SQLITE_INDEX_HANDLE; 9 10 // A handle to the manifest. 11 typedef void* WINGET_MANIFEST_HANDLE; 12 13 // A string taken in by the utility; in UTF16. 14 typedef wchar_t const* const WINGET_STRING; 15 16 // A string returned by the utility; in UTF16. 17 typedef BSTR WINGET_STRING_OUT; 18 19 #define WINGET_UTIL_API HRESULT __stdcall 20 21 #define WINGET_SQLITE_INDEX_VERSION_LATEST ((UINT32)-1) 22 23 enum WinGetValidateManifestOption 24 { 25 Default = 0, 26 SchemaValidationOnly = 0x1, 27 ErrorOnVerifiedPublisherFields = 0x2, 28 InstallerValidations = 0x4, 29 }; 30 31 DEFINE_ENUM_FLAG_OPERATORS(WinGetValidateManifestOption); 32 33 enum WinGetCreateManifestOption 34 { 35 // Just create the manifest without any validation 36 NoValidation = 0, 37 // Only validate against json schema 38 SchemaValidation = 0x1, 39 // Validate against schema and also perform semantic validation 40 SchemaAndSemanticValidation = 0x2, 41 // Use shadow manifest 42 AllowShadowManifest = 0x4, 43 44 /// Below options are additional validation behaviors if needed 45 46 // Return error on manifest fields that require verified publishers, used during semantic validation 47 ReturnErrorOnVerifiedPublisherFields = 0x1000, 48 }; 49 50 DEFINE_ENUM_FLAG_OPERATORS(WinGetCreateManifestOption); 51 52 enum WinGetValidateManifestOptionV2 53 { 54 // No validation, caller will get E_INVALIDARG 55 None = 0, 56 // Dependencies validation against index 57 DependenciesValidation = 0x1, 58 // Arp version validation against index 59 ArpVersionValidation = 0x2, 60 // Installer validation 61 InstallerValidation = 0x4, 62 }; 63 64 DEFINE_ENUM_FLAG_OPERATORS(WinGetValidateManifestOptionV2); 65 66 enum WinGetValidateManifestOperationType 67 { 68 OperationTypeAdd = 0, 69 OperationTypeUpdate = 1, 70 OperationTypeDelete = 2, 71 }; 72 73 enum WinGetValidateManifestResult 74 { 75 Success = 0, 76 77 // Each validation step should have an enum for corresponding failure. 78 DependenciesValidationFailure = 0x1, 79 ArpVersionValidationFailure = 0x2, 80 InstallerValidationFailure = 0x4, 81 82 // Dependencies validation result. 83 SingleManifestPackageHasDependencies = 0x10000, 84 MultiManifestPackageHasDependencies = 0x20000, 85 MissingManifestDependenciesNode = 0x40000, 86 NoSuitableMinVersionDependency = 0x80000, 87 FoundDependencyLoop = 0x100000, 88 89 // Internal error meaning validation does not complete as desired. 90 InternalError = 0x1000, 91 }; 92 93 DEFINE_ENUM_FLAG_OPERATORS(WinGetValidateManifestResult); 94 95 enum WinGetValidateManifestDependenciesOption 96 { 97 DefaultValidation = 0, 98 ForDelete = 0x1, 99 }; 100 101 DEFINE_ENUM_FLAG_OPERATORS(WinGetValidateManifestDependenciesOption); 102 103 // Initializes the logging infrastructure. 104 WINGET_UTIL_API WinGetLoggingInit( 105 WINGET_STRING logPath); 106 107 // Removes the given log file from the logging infrastructure. 108 // If logPath is nullptr, then remove all loggers. 109 WINGET_UTIL_API WinGetLoggingTerm( 110 WINGET_STRING logPath); 111 112 // Creates a new index file at filePath with the given version. 113 WINGET_UTIL_API WinGetSQLiteIndexCreate( 114 WINGET_STRING filePath, 115 UINT32 majorVersion, 116 UINT32 minorVersion, 117 WINGET_SQLITE_INDEX_HANDLE* index); 118 119 // Opens an existing index at filePath. 120 WINGET_UTIL_API WinGetSQLiteIndexOpen( 121 WINGET_STRING filePath, 122 WINGET_SQLITE_INDEX_HANDLE* index); 123 124 // Closes the index. 125 WINGET_UTIL_API WinGetSQLiteIndexClose( 126 WINGET_SQLITE_INDEX_HANDLE index); 127 128 // Migrates the index to the new version specified. 129 WINGET_UTIL_API WinGetSQLiteIndexMigrate( 130 WINGET_SQLITE_INDEX_HANDLE index, 131 UINT32 majorVersion, 132 UINT32 minorVersion); 133 134 enum WinGetSQLiteIndexProperty 135 { 136 WinGetSQLiteIndexProperty_PackageUpdateTrackingBaseTime = 0, 137 WinGetSQLiteIndexProperty_IntermediateFileOutputPath = 1, 138 }; 139 140 // Sets the given property on the index. 141 WINGET_UTIL_API WinGetSQLiteIndexSetProperty( 142 WINGET_SQLITE_INDEX_HANDLE index, 143 WinGetSQLiteIndexProperty property, 144 WINGET_STRING value); 145 146 // Adds the manifest at the repository relative path to the index. 147 // If the function succeeds, the manifest has been added. 148 WINGET_UTIL_API WinGetSQLiteIndexAddManifest( 149 WINGET_SQLITE_INDEX_HANDLE index, 150 WINGET_STRING manifestPath, 151 WINGET_STRING relativePath); 152 153 // Updates the manifest with matching { Id, Version, Channel } in the index. 154 // The return value indicates whether the index was modified by the function. 155 WINGET_UTIL_API WinGetSQLiteIndexUpdateManifest( 156 WINGET_SQLITE_INDEX_HANDLE index, 157 WINGET_STRING manifestPath, 158 WINGET_STRING relativePath, 159 BOOL* indexModified); 160 161 // Adds or Updates the manifest with matching { Id, Version, Channel } in the index. 162 // The return value indicates whether the manifest was added (true) or updated (false). 163 WINGET_UTIL_API WinGetSQLiteIndexAddOrUpdateManifest( 164 WINGET_SQLITE_INDEX_HANDLE index, 165 WINGET_STRING manifestPath, 166 WINGET_STRING relativePath, 167 BOOL* indexModified); 168 169 // Removes the manifest with matching { Id, Version, Channel } from the index. 170 // Path is currently ignored. 171 WINGET_UTIL_API WinGetSQLiteIndexRemoveManifest( 172 WINGET_SQLITE_INDEX_HANDLE index, 173 WINGET_STRING manifestPath, 174 WINGET_STRING relativePath); 175 176 // Removes data that is no longer needed for an index that is to be published. 177 WINGET_UTIL_API WinGetSQLiteIndexPrepareForPackaging( 178 WINGET_SQLITE_INDEX_HANDLE index); 179 180 // Checks the index for consistency, ensuring that at a minimum all referenced rows actually exist. 181 WINGET_UTIL_API WinGetSQLiteIndexCheckConsistency( 182 WINGET_SQLITE_INDEX_HANDLE index, 183 BOOL* succeeded); 184 185 // Validates a given manifest. Returns a bool for validation result and 186 // a string representing validation errors if validation failed. 187 WINGET_UTIL_API WinGetValidateManifest( 188 WINGET_STRING manifestPath, 189 BOOL* succeeded, 190 WINGET_STRING_OUT* message); 191 192 // Validates a given manifest. Returns a bool for validation result and 193 // a string representing validation errors if validation failed. 194 // If mergedManifestPath is provided, this method will write a merged manifest 195 // to the location specified by mergedManifestPath 196 WINGET_UTIL_API WinGetValidateManifestV2( 197 WINGET_STRING inputPath, 198 BOOL* succeeded, 199 WINGET_STRING_OUT* message, 200 WINGET_STRING mergedManifestPath, 201 WinGetValidateManifestOption option); 202 203 // Creates a given manifest with optional validation. Returns a bool for operation result and 204 // a string representing validation errors if validation failed. 205 // If mergedManifestPath is provided, this method will write a merged manifest 206 // to the location specified by mergedManifestPath 207 WINGET_UTIL_API WinGetCreateManifest( 208 WINGET_STRING inputPath, 209 BOOL* succeeded, 210 WINGET_MANIFEST_HANDLE* manifest, 211 WINGET_STRING_OUT* message, 212 WINGET_STRING mergedManifestPath, 213 WinGetCreateManifestOption option); 214 215 // Closes a given manifest. 216 WINGET_UTIL_API WinGetCloseManifest( 217 WINGET_MANIFEST_HANDLE manifest); 218 219 // Validates a given manifest. Returns WinGetValidateManifestResult for validation result and 220 // a string representing validation errors if validation failed. 221 // If result is 0, it is success. Otherwise, caller can check the result with flags to see 222 // which phases failed. 223 WINGET_UTIL_API WinGetValidateManifestV3( 224 WINGET_MANIFEST_HANDLE manifest, 225 WINGET_SQLITE_INDEX_HANDLE index, 226 WinGetValidateManifestResult* result, 227 WINGET_STRING_OUT* message, 228 WinGetValidateManifestOptionV2 option, 229 WinGetValidateManifestOperationType operationType); 230 231 // Validates a given manifest with dependencies. Returns a bool for validation result and 232 // a string representing validation errors if validation failed. 233 // If mergedManifestPath is provided, this method will write a merged manifest 234 // to the location specified by mergedManifestPath 235 WINGET_UTIL_API WinGetValidateManifestDependencies( 236 WINGET_STRING inputPath, 237 BOOL* succeeded, 238 WINGET_STRING_OUT* message, 239 WINGET_SQLITE_INDEX_HANDLE index, 240 WinGetValidateManifestDependenciesOption dependenciesValidationOption); 241 242 // Downloads a file to the given path, returning the SHA 256 hash of the file. 243 WINGET_UTIL_API WinGetDownload( 244 WINGET_STRING url, 245 WINGET_STRING filePath, 246 BYTE* sha256Hash, 247 UINT32 sha256HashLength); 248 249 // Compares two version strings, returning -1 if versionA is less than versionB, 0 if they're equal, or 1 if versionA is greater than versionB 250 WINGET_UTIL_API WinGetCompareVersions( 251 WINGET_STRING versionA, 252 WINGET_STRING versionB, 253 INT* comparisonResult); 254 255 // A handle to the metadata collection object. 256 typedef void* WINGET_INSTALLER_METADATA_COLLECTION_HANDLE; 257 258 // Option flags for WinGetBeginInstallerMetadataCollection. 259 enum WinGetBeginInstallerMetadataCollectionOptions 260 { 261 WinGetBeginInstallerMetadataCollectionOption_None = 0, 262 // The inputJSON is a local file path, not a JSON string. 263 WinGetBeginInstallerMetadataCollectionOption_InputIsFilePath = 0x1, 264 // The inputJSON is a remote URI, not a JSON string. 265 WinGetBeginInstallerMetadataCollectionOption_InputIsURI = 0x2, 266 }; 267 268 DEFINE_ENUM_FLAG_OPERATORS(WinGetBeginInstallerMetadataCollectionOptions); 269 270 // Begins the installer metadata collection process. 271 // By default, inputJSON is expected to be a JSON string. See the WinGetBeginInstallerMetadataCollectionOptions for more options. 272 // logFilePath optionally specifies where to write the log file for the collection operation. 273 // The collectionHandle is owned by the caller and must be passed to WinGetCompleteInstallerMetadataCollection to free it. 274 WINGET_UTIL_API WinGetBeginInstallerMetadataCollection( 275 WINGET_STRING inputJSON, 276 WINGET_STRING logFilePath, 277 WinGetBeginInstallerMetadataCollectionOptions options, 278 WINGET_INSTALLER_METADATA_COLLECTION_HANDLE* collectionHandle); 279 280 // Option flags for WinGetCompleteInstallerMetadataCollection. 281 enum WinGetCompleteInstallerMetadataCollectionOptions 282 { 283 WinGetCompleteInstallerMetadataCollectionOption_None = 0, 284 // Complete will simply free the collection handle without doing any additional work. 285 WinGetCompleteInstallerMetadataCollectionOption_Abandon = 0x1, 286 }; 287 288 DEFINE_ENUM_FLAG_OPERATORS(WinGetCompleteInstallerMetadataCollectionOptions); 289 290 // Completes the installer metadata collection process. 291 // Always frees the collectionHandle; WinGetCompleteInstallerMetadataCollection must be called exactly once for each call to WinGetBeginInstallerMetadataCollection. 292 WINGET_UTIL_API WinGetCompleteInstallerMetadataCollection( 293 WINGET_INSTALLER_METADATA_COLLECTION_HANDLE collectionHandle, 294 WINGET_STRING outputFilePath, 295 WinGetCompleteInstallerMetadataCollectionOptions options); 296 297 // Option flags for WinGetMergeInstallerMetadata. 298 enum WinGetMergeInstallerMetadataOptions 299 { 300 WinGetMergeInstallerMetadataOptions_None = 0, 301 }; 302 303 // Merges the given JSON metadata documents into a single one. 304 WINGET_UTIL_API WinGetMergeInstallerMetadata( 305 WINGET_STRING inputJSON, 306 WINGET_STRING_OUT* outputJSON, 307 UINT32 maximumOutputSizeInBytes, 308 WINGET_STRING logFilePath, 309 WinGetMergeInstallerMetadataOptions options); 310 }