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