2 The file provides Database manager for HII-related data
5 Copyright (c) 2006 - 2007, Intel Corporation
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
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.
16 #ifndef __HII_DATABASE_H__
17 #define __HII_DATABASE_H__
19 #define EFI_HII_DATABASE_PROTOCOL_GUID \
20 { 0xef9fc172, 0xa1b2, 0x4693, { 0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42 } }
23 typedef struct _EFI_HII_DATABASE_PROTOCOL EFI_HII_DATABASE_PROTOCOL
;
27 // EFI_HII_DATABASE_NOTIFY_TYPE
29 typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE
;
30 #define EFI_HII_DATABASE_NOTIFY_NEW_PACK 0x00000001
31 #define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK 0x00000002
32 #define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK 0x00000004
33 #define EFI_HII_DATABASE_NOTIFY_ADD_PACK 0x00000008
36 Functions which are registered to receive notification of
37 database events have this prototype. The actual event is encoded
38 in NotifyType. The following table describes how PackageType,
39 PackageGuid, Handle, and Package are used for each of the
42 @param PackageType Package type of the notification.
44 @param PackageGuid If PackageType is
45 EFI_HII_PACKAGE_TYPE_GUID, then this is
46 the pointer to the GUID from the Guid
47 field of EFI_HII_PACKAGE_GUID_HEADER.
48 Otherwise, it must be NULL.
50 @param Package Points to the package referred to by the
51 notification Handle The handle of the package
52 list which contains the specified package.
54 @param NotifyType The type of change concerning the
56 EFI_HII_DATABASE_NOTIFY_TYPE.
61 (EFIAPI
*EFI_HII_DATABASE_NOTIFY
) (
63 IN CONST EFI_GUID
*PackageGuid
,
64 IN CONST EFI_HII_PACKAGE_HEADER
*Package
,
65 IN EFI_HII_HANDLE Handle
,
66 IN EFI_HII_DATABASE_NOTIFY_TYPE NotifyType
71 This function adds the packages in the package list to the
72 database and returns a handle. If there is a
73 EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then
74 this function will create a package of type
75 EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list. For
76 each package in the package list, registered functions with the
77 notification type NEW_PACK and having the same package type will
78 be called. For each call to NewPackageList(), there should be a
80 EFI_HII_DATABASE_PROTOCOL.RemovePackageList().
82 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
85 @param PackageList A pointer to an
86 EFI_HII_PACKAGE_LIST_HEADER structure.
88 @param DriverHandle Associate the package list with this EFI
89 handle Handle A pointer to the
90 EFI_HII_HANDLE instance.
92 @retval EFI_SUCCESS The package list associated with the
93 Handle was added to the HII database.
95 @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary
96 resources for the new database
99 @retval EFI_INVALID_PARAMETER PackageList is NULL or Handle
105 (EFIAPI
*EFI_HII_DATABASE_NEW_PACK
) (
106 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
107 IN CONST EFI_HII_PACKAGE_LIST_HEADER
*PackageList
,
108 IN EFI_HANDLE DriverHandle
,
109 OUT EFI_HII_HANDLE
*Handle
115 This function removes the package list that is associated with a
116 handle Handle from the HII database. Before removing the
117 package, any registered functions with the notification type
118 REMOVE_PACK and the same package type will be called. For each
119 call to EFI_HII_DATABASE_PROTOCOL.NewPackageList(), there should
120 be a corresponding call to RemovePackageList.
122 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
125 @param Handle The handle that was registered to the data
126 that is requested for removal.
128 @retval EFI_SUCCESS The data associated with the Handle was
129 removed from the HII database.
131 @retval EFI_INVALID_PARAMETER The Handle was not valid.
136 (EFIAPI
*EFI_HII_DATABASE_REMOVE_PACK
) (
137 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
138 IN EFI_HII_HANDLE Handle
144 This function updates the existing package list (which has the
145 specified Handle) in the HII databases, using the new package
146 list specified by PackageList. The update process has the
147 following steps: Collect all the package types in the package
148 list specified by PackageList. A package type consists of the
149 Type field of EFI_HII_PACKAGE_HEADER and, if the Type is
150 EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in
151 EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within
152 the existing package list in the HII database specified by
153 Handle. If a package??s type matches one of the types collected
154 in step 1, then perform the following steps:
155 - Call any functions registered with the notification type
157 - Remove the package from the package list and the HII
159 Add all of the packages within the new package list specified
160 by PackageList, using the following steps:
161 - Add the package to the package list and the HII database.
162 - Call any functions registered with the notification type
165 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
168 @param Handle The handle that was registered to the data
169 that is requested for removal.
171 @param PackageList A pointer to an EFI_HII_PACKAGE_LIST
174 @retval EFI_SUCCESS The HII database was successfully
177 @retval EFI_OUT_OF_RESOURCES Unable to allocate enough memory
178 for the updated database.
180 @retval EFI_INVALID_PARAMETER The Handle was not valid.
185 (EFIAPI
*EFI_HII_DATABASE_UPDATE_PACK
) (
186 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
187 IN EFI_HII_HANDLE Handle
,
188 IN CONST EFI_HII_PACKAGE_LIST_HEADER
*PackageList
194 This function returns a list of the package handles of the
195 specified type that are currently active in the database. The
196 pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
197 handles to be listed.
199 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
202 @param PackageType Specifies the package type of the packages
203 to list or EFI_HII_PACKAGE_TYPE_ALL for
204 all packages to be listed.
206 @param PackageGuid If PackageType is
207 EFI_HII_PACKAGE_TYPE_GUID, then this is
208 the pointer to the GUID which must match
210 EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
213 @param HandleBufferLength On input, a pointer to the length
214 of the handle buffer. On output,
215 the length of the handle buffer
216 that is required for the handles
219 @param Handle An array of EFI_HII_HANDLE instances returned.
222 @retval EFI_SUCCESS Handle was updated successfully.
224 @retval EFI_BUFFER_TOO_SMALL The HandleBufferLength parameter
225 indicates that Handle is too
226 small to support the number of
227 handles. HandleBufferLength is
228 updated with a value that will
229 enable the data to fit.
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
250 This function will export one or all package lists in the
251 database to a buffer. For each package list exported, this
252 function will call functions registered with EXPORT_PACK and
253 then copy the package list to the buffer. The registered
254 functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()
255 to modify the package list before it is copied to the buffer. If
256 the specified BufferSize is too small, then the status
257 EFI_OUT_OF_RESOURCES will be returned and the actual package
258 size will be returned in BufferSize.
260 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
263 @param Handle An EFI_HII_HANDLE that corresponds to the
264 desired package list in the HII database to
265 export or NULL to indicate all package lists
268 @param BufferSize On input, a pointer to the length of the
269 buffer. On output, the length of the
270 buffer that is required for the exported
273 @param Buffer A pointer to a buffer that will contain the
274 results of the export function.
277 @retval EFI_SUCCESS Package exported.
279 @retval EFI_OUT_OF_RESOURCES BufferSize is too small to hold
285 (EFIAPI
*EFI_HII_DATABASE_EXPORT_PACKS
) (
286 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
287 IN EFI_HII_HANDLE Handle
,
288 IN OUT UINTN
*BufferSize
,
289 OUT EFI_HII_PACKAGE_LIST_HEADER
*Buffer
296 This function registers a function which will be called when
297 specified actions related to packages of the specified type
298 occur in the HII database. By registering a function, other
299 HII-related drivers are notified when specific package types
300 are added, removed or updated in the HII database. Each driver
301 or application which registers a notification should use
302 EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before
306 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
309 @param PackageType The package type. See
310 EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.
312 @param PackageGuid If PackageType is
313 EFI_HII_PACKAGE_TYPE_GUID, then this is
314 the pointer to the GUID which must match
316 EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
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.
324 @param NotifyType Describes the types of notification which
325 this function will be receiving. See
326 EFI_HII_DATABASE_NOTIFY_TYPE for more a
329 @param NotifyHandle Points to the unique handle assigned to
330 the registered notification. Can be used
332 EFI_HII_DATABASE_PROTOCOL.UnregisterPack
333 to stop notifications.
336 @retval EFI_SUCCESS Notification registered successfully.
338 @retval EFI_OUT_OF_RESOURCES Unable to allocate necessary
341 @retval EFI_INVALID_PARAMETER PackageGuid is not NULL when
343 EFI_HII_PACKAGE_TYPE_GUID.
348 (EFIAPI
*EFI_HII_DATABASE_REGISTER_NOTIFY
) (
349 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
350 IN UINT8 PackageType
,
351 IN CONST EFI_GUID
*PackageGuid
,
352 IN EFI_HII_DATABASE_NOTIFY PackageNotifyFn
,
353 IN EFI_HII_DATABASE_NOTIFY_TYPE NotifyType
,
354 OUT EFI_HANDLE
*NotifyHandle
360 Removes the specified HII database package-related notification.
362 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
365 @param NotificationHandle The handle of the notification
366 function being unregistered.
368 @retval EFI_SUCCESS Unregister the notification
371 @retval EFI_INVALID_PARAMETER The Handle is invalid.
376 (EFIAPI
*EFI_HII_DATABASE_UNREGISTER_NOTIFY
) (
377 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
378 IN EFI_HANDLE NotificationHandle
384 This routine retrieves an array of GUID values for each keyboard
385 layout that was previously registered in the system.
387 @param This A pointer to the EFI_HII_PROTOCOL instance.
389 @param KeyGuidBufferLength On input, a pointer to the length
390 of the keyboard GUID buffer. On
391 output, the length of the handle
392 buffer that is required for the
393 handles found. KeyGuidBuffer An
394 array of keyboard layout GUID
397 @retval EFI_SUCCESS KeyGuidBuffer was updated successfully.
399 @retval EFI_BUFFER_TOO_SMALL The KeyGuidBufferLength
400 parameter indicates that
401 KeyGuidBuffer is too small to
402 support the number of GUIDs.
403 KeyGuidBufferLength is updated
404 with a value that will enable
410 (EFIAPI
*EFI_HII_FIND_KEYBOARD_LAYOUTS
) (
411 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
412 IN OUT UINT16
*KeyGuidBufferLength
,
413 OUT EFI_GUID
*KeyGuidBuffer
419 This routine retrieves the requested keyboard layout. The layout
420 is a physical description of the keys on a keyboard and the
421 character(s) that are associated with a particular set of key
424 @param This A pointer to the EFI_HII_PROTOCOL instance.
426 @param KeyGuid A pointer to the unique ID associated with a
427 given keyboard layout. If KeyGuid is NULL then
428 the current layout will be retrieved.
430 @param KeyboardLayout A pointer to a buffer containing the
431 retrieved keyboard layout. below.
433 @retval EFI_SUCCESS The keyboard layout was retrieved
436 @retval EFI_NOT_FOUND The requested keyboard layout was not
442 (EFIAPI
*EFI_HII_GET_KEYBOARD_LAYOUT
) (
443 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
444 IN CONST EFI_GUID
*KeyGuid
,
445 IN OUT UINT16
*KeyboardLayoutLength
,
446 OUT EFI_HII_KEYBOARD_LAYOUT
*KeyboardLayout
451 This routine sets the default keyboard layout to the one
452 referenced by KeyGuid. When this routine is called, an event
453 will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
454 group type. This is so that agents which are sensitive to the
455 current keyboard layout being changed can be notified of this
458 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
461 @param KeyGuid A pointer to the unique ID associated with a
462 given keyboard layout.
465 @retval EFI_SUCCESS The current keyboard layout was
468 @retval EFI_NOT_FOUND The referenced keyboard layout was not
469 found, so action was taken.
474 (EFIAPI
*EFI_HII_SET_KEYBOARD_LAYOUT
) (
475 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
476 IN CONST EFI_GUID
*KeyGuid
481 Return the EFI handle associated with a package list.
483 @param This A pointer to the EFI_HII_DATABASE_PROTOCOL
486 @param PackageListHandle An EFI_HII_HANDLE that corresponds
487 to the desired package list in the
490 @param DriverHandle On return, contains the EFI_HANDLE which
491 was registered with the package list in
494 @retval EFI_SUCCESS The DriverHandle was returned
497 @retval EFI_INVALID_PARAMETER The PackageListHandle was not
503 (EFIAPI
*EFI_HII_DATABASE_GET_PACK_HANDLE
) (
504 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
505 IN EFI_HII_HANDLE PackageListHandle
,
506 OUT EFI_HANDLE
*DriverHandle
511 @param NewPackageList Add a new package list to the HII
514 @param RemovePackageList Remove a package list from the HII
517 @param UpdatePackageList Update a package list in the HII
520 @param ListPackageLists List the handles of the package
521 lists within the HII database.
523 @param ExportPackageLists Export package lists from the HII
526 @param RegisterPackageNotify Register notification when
527 packages of a certain type are
530 @param UnregisterPackageNotify Unregister notification of
533 @param FindKeyboardLayouts Retrieves a list of the keyboard
534 layouts in the system.
536 @param GetKeyboardLayout Allows a program to extract the
537 current keyboard layout. See the
538 GetKeyboardLayout() function
541 @param SetKeyboardLayout Changes the current keyboard layout.
542 See the SetKeyboardLayout() function
546 struct _EFI_HII_DATABASE_PROTOCOL
{
547 EFI_HII_DATABASE_NEW_PACK NewPackageList
;
548 EFI_HII_DATABASE_REMOVE_PACK RemovePackageList
;
549 EFI_HII_DATABASE_UPDATE_PACK UpdatePackageList
;
550 EFI_HII_DATABASE_LIST_PACKS ListPackageLists
;
551 EFI_HII_DATABASE_EXPORT_PACKS ExportPackageLists
;
552 EFI_HII_DATABASE_REGISTER_NOTIFY RegisterPackageNotify
;
553 EFI_HII_DATABASE_UNREGISTER_NOTIFY UnregisterPackageNotify
;
554 EFI_HII_FIND_KEYBOARD_LAYOUTS FindKeyboardLayouts
;
555 EFI_HII_GET_KEYBOARD_LAYOUT GetKeyboardLayout
;
556 EFI_HII_SET_KEYBOARD_LAYOUT SetKeyboardLayout
;
557 EFI_HII_DATABASE_GET_PACK_HANDLE GetPackageListHandle
;
560 extern EFI_GUID gEfiHiiDatabaseProtocolGuid
;