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