1 /** @file 2 The file provides Database manager for HII-related data 3 structures. 4 5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 6 SPDX-License-Identifier: BSD-2-Clause-Patent 7 8 @par Revision Reference: 9 This Protocol was introduced in UEFI Specification 2.1. 10 11 **/ 12 13 #ifndef __HII_DATABASE_H__ 14 #define __HII_DATABASE_H__ 15 16 #define EFI_HII_DATABASE_PROTOCOL_GUID \ 17 { 0xef9fc172, 0xa1b2, 0x4693, { 0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42 } } 18 19 typedef struct _EFI_HII_DATABASE_PROTOCOL EFI_HII_DATABASE_PROTOCOL; 20 21 /// 22 /// EFI_HII_DATABASE_NOTIFY_TYPE. 23 /// 24 typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE; 25 26 #define EFI_HII_DATABASE_NOTIFY_NEW_PACK 0x00000001 27 #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK 0x00000002 28 #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK 0x00000004 29 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK 0x00000008 30 31 /** 32 33 Functions which are registered to receive notification of 34 database events have this prototype. The actual event is encoded 35 in NotifyType. The following table describes how PackageType, 36 PackageGuid, Handle, and Package are used for each of the 37 notification types. 38 39 @param PackageType Package type of the notification. 40 41 @param PackageGuid If PackageType is 42 EFI_HII_PACKAGE_TYPE_GUID, then this is 43 the pointer to the GUID from the Guid 44 field of EFI_HII_PACKAGE_GUID_HEADER. 45 Otherwise, it must be NULL. 46 47 @param Package Points to the package referred to by the notification. 48 49 @param Handle The handle of the package 50 list which contains the specified package. 51 52 @param NotifyType The type of change concerning the 53 database. See 54 EFI_HII_DATABASE_NOTIFY_TYPE. 55 56 **/ 57 typedef 58 EFI_STATUS 59 (EFIAPI *EFI_HII_DATABASE_NOTIFY)( 60 IN UINT8 PackageType, 61 IN CONST EFI_GUID *PackageGuid, 62 IN CONST EFI_HII_PACKAGE_HEADER *Package, 63 IN EFI_HII_HANDLE Handle, 64 IN EFI_HII_DATABASE_NOTIFY_TYPE NotifyType 65 ); 66 67 /** 68 69 This function adds the packages in the package list to the 70 database and returns a handle. If there is a 71 EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then 72 this function will create a package of type 73 EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list. For 74 each package in the package list, registered functions with the 75 notification type NEW_PACK and having the same package type will 76 be called. For each call to NewPackageList(), there should be a 77 corresponding call to 78 EFI_HII_DATABASE_PROTOCOL.RemovePackageList(). 79 80 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. 81 82 @param PackageList A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure. 83 84 @param DriverHandle Associate the package list with this EFI handle. 85 If a NULL is specified, this data will not be associate 86 with any drivers and cannot have a callback induced. 87 88 @param Handle A pointer to the EFI_HII_HANDLE instance. 89 90 @retval EFI_SUCCESS The package list associated with the 91 Handle was added to the HII database. 92 93 @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary 94 resources for the new database 95 contents. 96 97 @retval EFI_INVALID_PARAMETER PackageList is NULL, or Handle is NULL. 98 99 **/ 100 typedef 101 EFI_STATUS 102 (EFIAPI *EFI_HII_DATABASE_NEW_PACK)( 103 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 104 IN CONST EFI_HII_PACKAGE_LIST_HEADER *PackageList, 105 IN EFI_HANDLE DriverHandle OPTIONAL, 106 OUT EFI_HII_HANDLE *Handle 107 ); 108 109 /** 110 111 This function removes the package list that is associated with a 112 handle Handle from the HII database. Before removing the 113 package, any registered functions with the notification type 114 REMOVE_PACK and the same package type will be called. For each 115 call to EFI_HII_DATABASE_PROTOCOL.NewPackageList(), there should 116 be a corresponding call to RemovePackageList. 117 118 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. 119 120 @param Handle The handle that was registered to the data 121 that is requested for removal. 122 123 @retval EFI_SUCCESS The data associated with the Handle was 124 removed from the HII database. 125 @retval EFI_NOT_FOUND The specified Handle is not in database. 126 127 **/ 128 typedef 129 EFI_STATUS 130 (EFIAPI *EFI_HII_DATABASE_REMOVE_PACK)( 131 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 132 IN EFI_HII_HANDLE Handle 133 ); 134 135 /** 136 137 This function updates the existing package list (which has the 138 specified Handle) in the HII databases, using the new package 139 list specified by PackageList. The update process has the 140 following steps: Collect all the package types in the package 141 list specified by PackageList. A package type consists of the 142 Type field of EFI_HII_PACKAGE_HEADER and, if the Type is 143 EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in 144 EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within 145 the existing package list in the HII database specified by 146 Handle. If a package's type matches one of the collected types collected 147 in step 1, then perform the following steps: 148 - Call any functions registered with the notification type 149 REMOVE_PACK. 150 - Remove the package from the package list and the HII 151 database. 152 Add all of the packages within the new package list specified 153 by PackageList, using the following steps: 154 - Add the package to the package list and the HII database. 155 - Call any functions registered with the notification type 156 ADD_PACK. 157 158 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. 159 160 @param Handle The handle that was registered to the data 161 that is requested for removal. 162 163 @param PackageList A pointer to an EFI_HII_PACKAGE_LIST 164 package. 165 166 @retval EFI_SUCCESS The HII database was successfully updated. 167 168 @retval EFI_OUT_OF_RESOURCES Unable to allocate enough memory 169 for the updated database. 170 171 @retval EFI_INVALID_PARAMETER PackageList was NULL. 172 @retval EFI_NOT_FOUND The specified Handle is not in database. 173 174 **/ 175 typedef 176 EFI_STATUS 177 (EFIAPI *EFI_HII_DATABASE_UPDATE_PACK)( 178 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 179 IN EFI_HII_HANDLE Handle, 180 IN CONST EFI_HII_PACKAGE_LIST_HEADER *PackageList 181 ); 182 183 /** 184 185 This function returns a list of the package handles of the 186 specified type that are currently active in the database. The 187 pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package 188 handles to be listed. 189 190 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. 191 192 @param PackageType Specifies the package type of the packages 193 to list or EFI_HII_PACKAGE_TYPE_ALL for 194 all packages to be listed. 195 196 @param PackageGuid If PackageType is 197 EFI_HII_PACKAGE_TYPE_GUID, then this is 198 the pointer to the GUID which must match 199 the Guid field of 200 EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it 201 must be NULL. 202 203 @param HandleBufferLength On input, a pointer to the length 204 of the handle buffer. On output, 205 the length of the handle buffer 206 that is required for the handles found. 207 208 @param Handle An array of EFI_HII_HANDLE instances returned. 209 210 @retval EFI_SUCCESS The matching handles are outputted successfully. 211 HandleBufferLength is updated with the actual length. 212 @retval EFI_BUFFER_TOO_SMALL The HandleBufferLength parameter 213 indicates that Handle is too 214 small to support the number of 215 handles. HandleBufferLength is 216 updated with a value that will 217 enable the data to fit. 218 @retval EFI_NOT_FOUND No matching handle could be found in database. 219 @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL. 220 @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not 221 zero and Handle was NULL. 222 @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but 223 PackageGuid is not NULL, PackageType is a EFI_HII_ 224 PACKAGE_TYPE_GUID but PackageGuid is NULL. 225 **/ 226 typedef 227 EFI_STATUS 228 (EFIAPI *EFI_HII_DATABASE_LIST_PACKS)( 229 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 230 IN UINT8 PackageType, 231 IN CONST EFI_GUID *PackageGuid, 232 IN OUT UINTN *HandleBufferLength, 233 OUT EFI_HII_HANDLE *Handle 234 ); 235 236 /** 237 238 This function will export one or all package lists in the 239 database to a buffer. For each package list exported, this 240 function will call functions registered with EXPORT_PACK and 241 then copy the package list to the buffer. The registered 242 functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList() 243 to modify the package list before it is copied to the buffer. If 244 the specified BufferSize is too small, then the status 245 EFI_OUT_OF_RESOURCES will be returned and the actual package 246 size will be returned in BufferSize. 247 248 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. 249 250 251 @param Handle An EFI_HII_HANDLE that corresponds to the 252 desired package list in the HII database to 253 export or NULL to indicate all package lists 254 should be exported. 255 256 @param BufferSize On input, a pointer to the length of the 257 buffer. On output, the length of the 258 buffer that is required for the exported 259 data. 260 261 @param Buffer A pointer to a buffer that will contain the 262 results of the export function. 263 264 265 @retval EFI_SUCCESS Package exported. 266 267 @retval EFI_OUT_OF_RESOURCES BufferSize is too small to hold the package. 268 269 @retval EFI_NOT_FOUND The specified Handle could not be found in the 270 current database. 271 272 @retval EFI_INVALID_PARAMETER BufferSize was NULL. 273 274 @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero 275 and Buffer was NULL. 276 **/ 277 typedef 278 EFI_STATUS 279 (EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS)( 280 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 281 IN EFI_HII_HANDLE Handle, 282 IN OUT UINTN *BufferSize, 283 OUT EFI_HII_PACKAGE_LIST_HEADER *Buffer 284 ); 285 286 /** 287 288 289 This function registers a function which will be called when 290 specified actions related to packages of the specified type 291 occur in the HII database. By registering a function, other 292 HII-related drivers are notified when specific package types 293 are added, removed or updated in the HII database. Each driver 294 or application which registers a notification should use 295 EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before 296 exiting. 297 298 299 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. 300 301 @param PackageType The package type. See 302 EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER. 303 304 @param PackageGuid If PackageType is 305 EFI_HII_PACKAGE_TYPE_GUID, then this is 306 the pointer to the GUID which must match 307 the Guid field of 308 EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it 309 must be NULL. 310 311 @param PackageNotifyFn Points to the function to be called 312 when the event specified by 313 NotificationType occurs. See 314 EFI_HII_DATABASE_NOTIFY. 315 316 @param NotifyType Describes the types of notification which 317 this function will be receiving. See 318 EFI_HII_DATABASE_NOTIFY_TYPE for a 319 list of types. 320 321 @param NotifyHandle Points to the unique handle assigned to 322 the registered notification. Can be used 323 in EFI_HII_DATABASE_PROTOCOL.UnregisterPack 324 to stop notifications. 325 326 327 @retval EFI_SUCCESS Notification registered successfully. 328 329 @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary 330 data structures. 331 332 @retval EFI_INVALID_PARAMETER PackageGuid is not NULL when 333 PackageType is not 334 EFI_HII_PACKAGE_TYPE_GUID. 335 336 **/ 337 typedef 338 EFI_STATUS 339 (EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY)( 340 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 341 IN UINT8 PackageType, 342 IN CONST EFI_GUID *PackageGuid, 343 IN EFI_HII_DATABASE_NOTIFY PackageNotifyFn, 344 IN EFI_HII_DATABASE_NOTIFY_TYPE NotifyType, 345 OUT EFI_HANDLE *NotifyHandle 346 ); 347 348 /** 349 350 Removes the specified HII database package-related notification. 351 352 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL instance. 353 354 @param NotificationHandle The handle of the notification 355 function being unregistered. 356 357 @retval EFI_SUCCESS Successsfully unregistered the notification. 358 359 @retval EFI_NOT_FOUND The incoming notification handle does not exist 360 in the current hii database. 361 362 **/ 363 typedef 364 EFI_STATUS 365 (EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY)( 366 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 367 IN EFI_HANDLE NotificationHandle 368 ); 369 370 /** 371 372 This routine retrieves an array of GUID values for each keyboard 373 layout that was previously registered in the system. 374 375 @param This A pointer to the EFI_HII_PROTOCOL instance. 376 377 @param KeyGuidBufferLength On input, a pointer to the length 378 of the keyboard GUID buffer. On 379 output, the length of the handle 380 buffer that is required for the 381 handles found. 382 383 @param KeyGuidBuffer An array of keyboard layout GUID 384 instances returned. 385 386 @retval EFI_SUCCESS KeyGuidBuffer was updated successfully. 387 388 @retval EFI_BUFFER_TOO_SMALL The KeyGuidBufferLength 389 parameter indicates that 390 KeyGuidBuffer is too small to 391 support the number of GUIDs. 392 KeyGuidBufferLength is updated 393 with a value that will enable 394 the data to fit. 395 @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL. 396 @retval EFI_INVALID_PARAMETER The value referenced by 397 KeyGuidBufferLength is not 398 zero and KeyGuidBuffer is NULL. 399 @retval EFI_NOT_FOUND There was no keyboard layout. 400 401 **/ 402 typedef 403 EFI_STATUS 404 (EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS)( 405 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 406 IN OUT UINT16 *KeyGuidBufferLength, 407 OUT EFI_GUID *KeyGuidBuffer 408 ); 409 410 /** 411 412 This routine retrieves the requested keyboard layout. The layout 413 is a physical description of the keys on a keyboard, and the 414 character(s) that are associated with a particular set of key 415 strokes. 416 417 @param This A pointer to the EFI_HII_PROTOCOL instance. 418 419 @param KeyGuid A pointer to the unique ID associated with a 420 given keyboard layout. If KeyGuid is NULL then 421 the current layout will be retrieved. 422 423 @param KeyboardLayoutLength On input, a pointer to the length of the 424 KeyboardLayout buffer. On output, the length of 425 the data placed into KeyboardLayout. 426 427 @param KeyboardLayout A pointer to a buffer containing the 428 retrieved keyboard layout. 429 430 @retval EFI_SUCCESS The keyboard layout was retrieved 431 successfully. 432 433 @retval EFI_NOT_FOUND The requested keyboard layout was not found. 434 435 **/ 436 typedef 437 EFI_STATUS 438 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT)( 439 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 440 IN CONST EFI_GUID *KeyGuid, 441 IN OUT UINT16 *KeyboardLayoutLength, 442 OUT EFI_HII_KEYBOARD_LAYOUT *KeyboardLayout 443 ); 444 445 /** 446 447 This routine sets the default keyboard layout to the one 448 referenced by KeyGuid. When this routine is called, an event 449 will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID 450 group type. This is so that agents which are sensitive to the 451 current keyboard layout being changed can be notified of this 452 change. 453 454 @param This A pointer to the EFI_HII_PROTOCOL instance. 455 456 @param KeyGuid A pointer to the unique ID associated with a 457 given keyboard layout. 458 459 @retval EFI_SUCCESS The current keyboard layout was successfully set. 460 461 @retval EFI_NOT_FOUND The referenced keyboard layout was not 462 found, so action was taken. 463 464 **/ 465 typedef 466 EFI_STATUS 467 (EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT)( 468 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 469 IN CONST EFI_GUID *KeyGuid 470 ); 471 472 /** 473 474 Return the EFI handle associated with a package list. 475 476 @param This A pointer to the EFI_HII_PROTOCOL instance. 477 478 @param PackageListHandle An EFI_HII_HANDLE that corresponds 479 to the desired package list in the 480 HIIdatabase. 481 482 @param DriverHandle On return, contains the EFI_HANDLE which 483 was registered with the package list in 484 NewPackageList(). 485 486 @retval EFI_SUCCESS The DriverHandle was returned successfully. 487 488 @retval EFI_INVALID_PARAMETER The PackageListHandle was not valid. 489 490 **/ 491 typedef 492 EFI_STATUS 493 (EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE)( 494 IN CONST EFI_HII_DATABASE_PROTOCOL *This, 495 IN EFI_HII_HANDLE PackageListHandle, 496 OUT EFI_HANDLE *DriverHandle 497 ); 498 499 /// 500 /// Database manager for HII-related data structures. 501 /// 502 struct _EFI_HII_DATABASE_PROTOCOL { 503 EFI_HII_DATABASE_NEW_PACK NewPackageList; 504 EFI_HII_DATABASE_REMOVE_PACK RemovePackageList; 505 EFI_HII_DATABASE_UPDATE_PACK UpdatePackageList; 506 EFI_HII_DATABASE_LIST_PACKS ListPackageLists; 507 EFI_HII_DATABASE_EXPORT_PACKS ExportPackageLists; 508 EFI_HII_DATABASE_REGISTER_NOTIFY RegisterPackageNotify; 509 EFI_HII_DATABASE_UNREGISTER_NOTIFY UnregisterPackageNotify; 510 EFI_HII_FIND_KEYBOARD_LAYOUTS FindKeyboardLayouts; 511 EFI_HII_GET_KEYBOARD_LAYOUT GetKeyboardLayout; 512 EFI_HII_SET_KEYBOARD_LAYOUT SetKeyboardLayout; 513 EFI_HII_DATABASE_GET_PACK_HANDLE GetPackageListHandle; 514 }; 515 516 extern EFI_GUID gEfiHiiDatabaseProtocolGuid; 517 518 #endif 519