MdeModulePkg/Universal/Disk/UdfDxe/Udf.h

   1 /** @file
   2   UDF/ECMA-167 file system driver.
   3
   4   Copyright (C) 2014-2017 Paulo Alcantara <pcacjr@zytor.com>
   5   Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8 **/
   9
  10 #ifndef _UDF_H_
  11 #define _UDF_H_
  12
  13 #include <Uefi.h>
  14 #include <Base.h>
  15
  16 #include <Protocol/BlockIo.h>
  17 #include <Protocol/ComponentName.h>
  18 #include <Protocol/DevicePath.h>
  19 #include <Protocol/DriverBinding.h>
  20 #include <Protocol/DiskIo.h>
  21 #include <Protocol/SimpleFileSystem.h>
  22
  23 #include <Guid/FileInfo.h>
  24 #include <Guid/FileSystemInfo.h>
  25 #include <Guid/FileSystemVolumeLabelInfo.h>
  26
  27 #include <Library/DebugLib.h>
  28 #include <Library/UefiDriverEntryPoint.h>
  29 #include <Library/BaseLib.h>
  30 #include <Library/UefiLib.h>
  31 #include <Library/BaseMemoryLib.h>
  32 #include <Library/MemoryAllocationLib.h>
  33 #include <Library/UefiBootServicesTableLib.h>
  34 #include <Library/DevicePathLib.h>
  35
  36 #include <IndustryStandard/ElTorito.h>
  37 #include <IndustryStandard/Udf.h>
  38
  39 //
  40 // C5BD4D42-1A76-4996-8956-73CDA326CD0A
  41 //
  42 #define EFI_UDF_DEVICE_PATH_GUID                        \
  43   { 0xC5BD4D42, 0x1A76, 0x4996,                         \
  44     { 0x89, 0x56, 0x73, 0xCD, 0xA3, 0x26, 0xCD, 0x0A }  \
  45   }
  46
  47 #define FE_ICB_FILE_TYPE(_Ptr)                                      \
  48   (UDF_FILE_ENTRY_TYPE)(                                            \
  49     ((UDF_DESCRIPTOR_TAG *)(_Ptr))->TagIdentifier == UdfFileEntry ? \
  50     ((UDF_FILE_ENTRY *)(_Ptr))->IcbTag.FileType :                   \
  51     ((UDF_EXTENDED_FILE_ENTRY *)(_Ptr))->IcbTag.FileType)
  52
  53 typedef enum {
  54   UdfFileEntryDirectory = 4,
  55   UdfFileEntryStandardFile = 5,
  56   UdfFileEntrySymlink = 12,
  57 } UDF_FILE_ENTRY_TYPE;
  58
  59 #define HIDDEN_FILE     (1 << 0)
  60 #define DIRECTORY_FILE  (1 << 1)
  61 #define DELETED_FILE    (1 << 2)
  62 #define PARENT_FILE     (1 << 3)
  63
  64 #define IS_FID_HIDDEN_FILE(_Fid) \
  65   (BOOLEAN)((_Fid)->FileCharacteristics & HIDDEN_FILE)
  66 #define IS_FID_DIRECTORY_FILE(_Fid) \
  67   (BOOLEAN)((_Fid)->FileCharacteristics & DIRECTORY_FILE)
  68 #define IS_FID_DELETED_FILE(_Fid) \
  69   (BOOLEAN)((_Fid)->FileCharacteristics & DELETED_FILE)
  70 #define IS_FID_PARENT_FILE(_Fid) \
  71   (BOOLEAN)((_Fid)->FileCharacteristics & PARENT_FILE)
  72 #define IS_FID_NORMAL_FILE(_Fid) \
  73   (BOOLEAN)(!IS_FID_DIRECTORY_FILE (_Fid) && \
  74             !IS_FID_PARENT_FILE (_Fid))
  75
  76 typedef enum {
  77   ShortAdsSequence,
  78   LongAdsSequence,
  79   ExtendedAdsSequence,
  80   InlineData
  81 } UDF_FE_RECORDING_FLAGS;
  82
  83 #define GET_FE_RECORDING_FLAGS(_Fe) \
  84   ((UDF_FE_RECORDING_FLAGS)((UDF_ICB_TAG *)( \
  85                   (UINT8 *)(_Fe) + \
  86                   sizeof (UDF_DESCRIPTOR_TAG)))->Flags & 0x07)
  87
  88 typedef enum {
  89   ExtentRecordedAndAllocated,
  90   ExtentNotRecordedButAllocated,
  91   ExtentNotRecordedNotAllocated,
  92   ExtentIsNextExtent,
  93 } UDF_EXTENT_FLAGS;
  94
  95 #define AD_LENGTH(_RecFlags) \
  96   ((_RecFlags) == ShortAdsSequence ? \
  97    ((UINT64)(sizeof (UDF_SHORT_ALLOCATION_DESCRIPTOR))) : \
  98    ((UINT64)(sizeof (UDF_LONG_ALLOCATION_DESCRIPTOR))))
  99
 100 #define GET_EXTENT_FLAGS(_RecFlags, _Ad) \
 101   ((_RecFlags) == ShortAdsSequence ? \
 102    ((UDF_EXTENT_FLAGS)((((UDF_SHORT_ALLOCATION_DESCRIPTOR *)(_Ad))->ExtentLength >> \
 103             30) & 0x3)) : \
 104    ((UDF_EXTENT_FLAGS)((((UDF_LONG_ALLOCATION_DESCRIPTOR *)(_Ad))->ExtentLength >> \
 105             30) & 0x3)))
 106
 107 #define GET_EXTENT_LENGTH(_RecFlags, _Ad) \
 108   ((_RecFlags) == ShortAdsSequence ? \
 109    ((UINT32)((((UDF_SHORT_ALLOCATION_DESCRIPTOR *)(_Ad))->ExtentLength & \
 110           ~0xC0000000UL))) : \
 111    ((UINT32)((((UDF_LONG_ALLOCATION_DESCRIPTOR *)(_Ad))->ExtentLength & \
 112           ~0xC0000000UL))))
 113
 114 #define UDF_FILENAME_LENGTH  128
 115 #define UDF_PATH_LENGTH      512
 116
 117 #define GET_FID_FROM_ADS(_Data, _Offs) \
 118   ((UDF_FILE_IDENTIFIER_DESCRIPTOR *)((UINT8 *)(_Data) + (_Offs)))
 119
 120 #define IS_VALID_COMPRESSION_ID(_CompId) \
 121   ((BOOLEAN)((_CompId) == 8 || (_CompId) == 16))
 122
 123 #define UDF_STANDARD_IDENTIFIER_LENGTH   5
 124
 125 #pragma pack(1)
 126
 127 typedef struct {
 128   UINT8 StandardIdentifier[UDF_STANDARD_IDENTIFIER_LENGTH];
 129 } UDF_STANDARD_IDENTIFIER;
 130
 131 #pragma pack()
 132
 133 typedef enum {
 134   ReadFileGetFileSize,
 135   ReadFileAllocateAndRead,
 136   ReadFileSeekAndRead,
 137 } UDF_READ_FILE_FLAGS;
 138
 139 typedef struct {
 140   VOID                 *FileData;
 141   UDF_READ_FILE_FLAGS  Flags;
 142   UINT64               FileDataSize;
 143   UINT64               FilePosition;
 144   UINT64               FileSize;
 145   UINT64               ReadLength;
 146 } UDF_READ_FILE_INFO;
 147
 148 #pragma pack(1)
 149
 150 typedef struct {
 151   UINT16          TypeAndTimezone;
 152   INT16           Year;
 153   UINT8           Month;
 154   UINT8           Day;
 155   UINT8           Hour;
 156   UINT8           Minute;
 157   UINT8           Second;
 158   UINT8           Centiseconds;
 159   UINT8           HundredsOfMicroseconds;
 160   UINT8           Microseconds;
 161 } UDF_TIMESTAMP;
 162
 163 typedef struct {
 164   UDF_DESCRIPTOR_TAG                 DescriptorTag;
 165   UINT32                             PrevAllocationExtentDescriptor;
 166   UINT32                             LengthOfAllocationDescriptors;
 167 } UDF_ALLOCATION_EXTENT_DESCRIPTOR;
 168
 169 typedef struct {
 170   UINT8                   StructureType;
 171   UINT8                   StandardIdentifier[UDF_STANDARD_IDENTIFIER_LENGTH];
 172   UINT8                   StructureVersion;
 173   UINT8                   Reserved;
 174   UINT8                   StructureData[2040];
 175 } UDF_VOLUME_DESCRIPTOR;
 176
 177 typedef struct {
 178   UDF_DESCRIPTOR_TAG             DescriptorTag;
 179   UDF_TIMESTAMP                  RecordingDateTime;
 180   UINT32                         IntegrityType;
 181   UDF_EXTENT_AD                  NextIntegrityExtent;
 182   UINT8                          LogicalVolumeContentsUse[32];
 183   UINT32                         NumberOfPartitions;
 184   UINT32                         LengthOfImplementationUse;
 185   UINT8                          Data[0];
 186 } UDF_LOGICAL_VOLUME_INTEGRITY;
 187
 188 typedef struct {
 189   UDF_DESCRIPTOR_TAG         DescriptorTag;
 190   UINT32                     VolumeDescriptorSequenceNumber;
 191   UINT16                     PartitionFlags;
 192   UINT16                     PartitionNumber;
 193   UDF_ENTITY_ID              PartitionContents;
 194   UINT8                      PartitionContentsUse[128];
 195   UINT32                     AccessType;
 196   UINT32                     PartitionStartingLocation;
 197   UINT32                     PartitionLength;
 198   UDF_ENTITY_ID              ImplementationIdentifier;
 199   UINT8                      ImplementationUse[128];
 200   UINT8                      Reserved[156];
 201 } UDF_PARTITION_DESCRIPTOR;
 202
 203 typedef struct {
 204   UDF_DESCRIPTOR_TAG              DescriptorTag;
 205   UDF_TIMESTAMP                   RecordingDateAndTime;
 206   UINT16                          InterchangeLevel;
 207   UINT16                          MaximumInterchangeLevel;
 208   UINT32                          CharacterSetList;
 209   UINT32                          MaximumCharacterSetList;
 210   UINT32                          FileSetNumber;
 211   UINT32                          FileSetDescriptorNumber;
 212   UDF_CHAR_SPEC                   LogicalVolumeIdentifierCharacterSet;
 213   UINT8                           LogicalVolumeIdentifier[128];
 214   UDF_CHAR_SPEC                   FileSetCharacterSet;
 215   UINT8                           FileSetIdentifier[32];
 216   UINT8                           CopyrightFileIdentifier[32];
 217   UINT8                           AbstractFileIdentifier[32];
 218   UDF_LONG_ALLOCATION_DESCRIPTOR  RootDirectoryIcb;
 219   UDF_ENTITY_ID                   DomainIdentifier;
 220   UDF_LONG_ALLOCATION_DESCRIPTOR  NextExtent;
 221   UDF_LONG_ALLOCATION_DESCRIPTOR  SystemStreamDirectoryIcb;
 222   UINT8                           Reserved[32];
 223 } UDF_FILE_SET_DESCRIPTOR;
 224
 225 typedef struct {
 226   UINT32                            ExtentLength;
 227   UINT32                            ExtentPosition;
 228 } UDF_SHORT_ALLOCATION_DESCRIPTOR;
 229
 230 typedef struct {
 231   UDF_DESCRIPTOR_TAG               DescriptorTag;
 232   UINT16                           FileVersionNumber;
 233   UINT8                            FileCharacteristics;
 234   UINT8                            LengthOfFileIdentifier;
 235   UDF_LONG_ALLOCATION_DESCRIPTOR   Icb;
 236   UINT16                           LengthOfImplementationUse;
 237   UINT8                            Data[0];
 238 } UDF_FILE_IDENTIFIER_DESCRIPTOR;
 239
 240 typedef struct {
 241   UINT32        PriorRecordNumberOfDirectEntries;
 242   UINT16        StrategyType;
 243   UINT16        StrategyParameter;
 244   UINT16        MaximumNumberOfEntries;
 245   UINT8         Reserved;
 246   UINT8         FileType;
 247   UDF_LB_ADDR   ParentIcbLocation;
 248   UINT16        Flags;
 249 } UDF_ICB_TAG;
 250
 251 typedef struct {
 252   UDF_DESCRIPTOR_TAG              DescriptorTag;
 253   UDF_ICB_TAG                     IcbTag;
 254   UINT32                          Uid;
 255   UINT32                          Gid;
 256   UINT32                          Permissions;
 257   UINT16                          FileLinkCount;
 258   UINT8                           RecordFormat;
 259   UINT8                           RecordDisplayAttributes;
 260   UINT32                          RecordLength;
 261   UINT64                          InformationLength;
 262   UINT64                          LogicalBlocksRecorded;
 263   UDF_TIMESTAMP                   AccessTime;
 264   UDF_TIMESTAMP                   ModificationTime;
 265   UDF_TIMESTAMP                   AttributeTime;
 266   UINT32                          CheckPoint;
 267   UDF_LONG_ALLOCATION_DESCRIPTOR  ExtendedAttributeIcb;
 268   UDF_ENTITY_ID                   ImplementationIdentifier;
 269   UINT64                          UniqueId;
 270   UINT32                          LengthOfExtendedAttributes;
 271   UINT32                          LengthOfAllocationDescriptors;
 272   UINT8                           Data[0]; // L_EA + L_AD
 273 } UDF_FILE_ENTRY;
 274
 275 typedef struct {
 276   UDF_DESCRIPTOR_TAG              DescriptorTag;
 277   UDF_ICB_TAG                     IcbTag;
 278   UINT32                          Uid;
 279   UINT32                          Gid;
 280   UINT32                          Permissions;
 281   UINT16                          FileLinkCount;
 282   UINT8                           RecordFormat;
 283   UINT8                           RecordDisplayAttributes;
 284   UINT32                          RecordLength;
 285   UINT64                          InformationLength;
 286   UINT64                          ObjectSize;
 287   UINT64                          LogicalBlocksRecorded;
 288   UDF_TIMESTAMP                   AccessTime;
 289   UDF_TIMESTAMP                   ModificationTime;
 290   UDF_TIMESTAMP                   CreationTime;
 291   UDF_TIMESTAMP                   AttributeTime;
 292   UINT32                          CheckPoint;
 293   UINT32                          Reserved;
 294   UDF_LONG_ALLOCATION_DESCRIPTOR  ExtendedAttributeIcb;
 295   UDF_LONG_ALLOCATION_DESCRIPTOR  StreamDirectoryIcb;
 296   UDF_ENTITY_ID                   ImplementationIdentifier;
 297   UINT64                          UniqueId;
 298   UINT32                          LengthOfExtendedAttributes;
 299   UINT32                          LengthOfAllocationDescriptors;
 300   UINT8                           Data[0]; // L_EA + L_AD
 301 } UDF_EXTENDED_FILE_ENTRY;
 302
 303 typedef struct {
 304   UINT8                ComponentType;
 305   UINT8                LengthOfComponentIdentifier;
 306   UINT16               ComponentFileVersionNumber;
 307   UINT8                ComponentIdentifier[0];
 308 } UDF_PATH_COMPONENT;
 309
 310 #pragma pack()
 311
 312 //
 313 // UDF filesystem driver's private data
 314 //
 315 typedef struct {
 316   UINT64                         MainVdsStartLocation;
 317   UDF_LOGICAL_VOLUME_DESCRIPTOR  LogicalVolDesc;
 318   UDF_PARTITION_DESCRIPTOR       PartitionDesc;
 319   UDF_FILE_SET_DESCRIPTOR        FileSetDesc;
 320   UINTN                          FileEntrySize;
 321 } UDF_VOLUME_INFO;
 322
 323 typedef struct {
 324   VOID                            *FileEntry;
 325   UDF_FILE_IDENTIFIER_DESCRIPTOR  *FileIdentifierDesc;
 326 } UDF_FILE_INFO;
 327
 328 typedef struct {
 329   VOID                      *DirectoryData;
 330   UINT64                    DirectoryLength;
 331   UINT64                    FidOffset;
 332 } UDF_READ_DIRECTORY_INFO;
 333
 334 #define PRIVATE_UDF_FILE_DATA_SIGNATURE SIGNATURE_32 ('U', 'd', 'f', 'f')
 335
 336 #define PRIVATE_UDF_FILE_DATA_FROM_THIS(a) \
 337   CR ( \
 338       a, \
 339       PRIVATE_UDF_FILE_DATA, \
 340       FileIo, \
 341       PRIVATE_UDF_FILE_DATA_SIGNATURE \
 342       )
 343
 344 typedef struct {
 345   UINTN                            Signature;
 346   BOOLEAN                          IsRootDirectory;
 347   UDF_FILE_INFO                    *Root;
 348   UDF_FILE_INFO                    File;
 349   UDF_READ_DIRECTORY_INFO          ReadDirInfo;
 350   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL  *SimpleFs;
 351   EFI_FILE_PROTOCOL                FileIo;
 352   CHAR16                           AbsoluteFileName[UDF_PATH_LENGTH];
 353   CHAR16                           FileName[UDF_FILENAME_LENGTH];
 354   UINT64                           FileSize;
 355   UINT64                           FilePosition;
 356 } PRIVATE_UDF_FILE_DATA;
 357
 358 #define PRIVATE_UDF_SIMPLE_FS_DATA_SIGNATURE SIGNATURE_32 ('U', 'd', 'f', 's')
 359
 360 #define PRIVATE_UDF_SIMPLE_FS_DATA_FROM_THIS(a) \
 361   CR ( \
 362       a, \
 363       PRIVATE_UDF_SIMPLE_FS_DATA, \
 364       SimpleFs, \
 365       PRIVATE_UDF_SIMPLE_FS_DATA_SIGNATURE \
 366       )
 367
 368 typedef struct {
 369   UINTN                            Signature;
 370   EFI_BLOCK_IO_PROTOCOL            *BlockIo;
 371   EFI_DISK_IO_PROTOCOL             *DiskIo;
 372   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL  SimpleFs;
 373   UDF_VOLUME_INFO                  Volume;
 374   UDF_FILE_INFO                    Root;
 375   UINTN                            OpenFiles;
 376   EFI_HANDLE                       Handle;
 377 } PRIVATE_UDF_SIMPLE_FS_DATA;
 378
 379 //
 380 // Global Variables
 381 //
 382 extern EFI_DRIVER_BINDING_PROTOCOL   gUdfDriverBinding;
 383 extern EFI_COMPONENT_NAME_PROTOCOL   gUdfComponentName;
 384 extern EFI_COMPONENT_NAME2_PROTOCOL  gUdfComponentName2;
 385
 386 //
 387 // Function Prototypes
 388 //
 389
 390 /**
 391   Open the root directory on a volume.
 392
 393   @param  This Protocol instance pointer.
 394   @param  Root Returns an Open file handle for the root directory
 395
 396   @retval EFI_SUCCESS          The device was opened.
 397   @retval EFI_UNSUPPORTED      This volume does not support the file system.
 398   @retval EFI_NO_MEDIA         The device has no media.
 399   @retval EFI_DEVICE_ERROR     The device reported an error.
 400   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 401   @retval EFI_ACCESS_DENIED    The service denied access to the file.
 402   @retval EFI_OUT_OF_RESOURCES The volume was not opened due to lack of resources.
 403
 404 **/
 405 EFI_STATUS
 406 EFIAPI
 407 UdfOpenVolume (
 408   IN   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL  *This,
 409   OUT  EFI_FILE_PROTOCOL                **Root
 410   );
 411
 412 /**
 413   Opens a new file relative to the source file's location.
 414
 415   @param  This       The protocol instance pointer.
 416   @param  NewHandle  Returns File Handle for FileName.
 417   @param  FileName   Null terminated string. "\", ".", and ".." are supported.
 418   @param  OpenMode   Open mode for file.
 419   @param  Attributes Only used for EFI_FILE_MODE_CREATE.
 420
 421   @retval EFI_SUCCESS          The device was opened.
 422   @retval EFI_NOT_FOUND        The specified file could not be found on the device.
 423   @retval EFI_NO_MEDIA         The device has no media.
 424   @retval EFI_MEDIA_CHANGED    The media has changed.
 425   @retval EFI_DEVICE_ERROR     The device reported an error.
 426   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 427   @retval EFI_ACCESS_DENIED    The service denied access to the file.
 428   @retval EFI_OUT_OF_RESOURCES The volume was not opened due to lack of resources.
 429   @retval EFI_VOLUME_FULL      The volume is full.
 430
 431 **/
 432 EFI_STATUS
 433 EFIAPI
 434 UdfOpen (
 435   IN   EFI_FILE_PROTOCOL  *This,
 436   OUT  EFI_FILE_PROTOCOL  **NewHandle,
 437   IN   CHAR16             *FileName,
 438   IN   UINT64             OpenMode,
 439   IN   UINT64             Attributes
 440   );
 441
 442 /**
 443   Read data from the file.
 444
 445   @param  This       Protocol instance pointer.
 446   @param  BufferSize On input size of buffer, on output amount of data in buffer.
 447   @param  Buffer     The buffer in which data is read.
 448
 449   @retval EFI_SUCCESS          Data was read.
 450   @retval EFI_NO_MEDIA         The device has no media.
 451   @retval EFI_DEVICE_ERROR     The device reported an error.
 452   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 453   @retval EFI_BUFFER_TO_SMALL  BufferSize is too small. BufferSize contains required size.
 454
 455 **/
 456 EFI_STATUS
 457 EFIAPI
 458 UdfRead (
 459   IN      EFI_FILE_PROTOCOL  *This,
 460   IN OUT  UINTN              *BufferSize,
 461   OUT     VOID               *Buffer
 462   );
 463
 464 /**
 465   Close the file handle.
 466
 467   @param  This Protocol instance pointer.
 468
 469   @retval EFI_SUCCESS The file was closed.
 470
 471 **/
 472 EFI_STATUS
 473 EFIAPI
 474 UdfClose (
 475   IN EFI_FILE_PROTOCOL *This
 476   );
 477
 478 /**
 479   Close and delete the file handle.
 480
 481   @param  This Protocol instance pointer.
 482
 483   @retval EFI_SUCCESS              The file was closed and deleted.
 484   @retval EFI_WARN_DELETE_FAILURE  The handle was closed but the file was not
 485                                    deleted.
 486
 487 **/
 488 EFI_STATUS
 489 EFIAPI
 490 UdfDelete (
 491   IN EFI_FILE_PROTOCOL  *This
 492   );
 493
 494 /**
 495   Write data to a file.
 496
 497   @param  This       Protocol instance pointer.
 498   @param  BufferSize On input size of buffer, on output amount of data in buffer.
 499   @param  Buffer     The buffer in which data to write.
 500
 501   @retval EFI_SUCCESS          Data was written.
 502   @retval EFI_UNSUPPORTED      Writes to Open directory are not supported.
 503   @retval EFI_NO_MEDIA         The device has no media.
 504   @retval EFI_DEVICE_ERROR     The device reported an error.
 505   @retval EFI_DEVICE_ERROR     An attempt was made to write to a deleted file.
 506   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 507   @retval EFI_WRITE_PROTECTED  The device is write protected.
 508   @retval EFI_ACCESS_DENIED    The file was open for read only.
 509   @retval EFI_VOLUME_FULL      The volume is full.
 510
 511 **/
 512 EFI_STATUS
 513 EFIAPI
 514 UdfWrite (
 515   IN      EFI_FILE_PROTOCOL  *This,
 516   IN OUT  UINTN              *BufferSize,
 517   IN      VOID               *Buffer
 518   );
 519
 520 /**
 521   Get file's current position.
 522
 523   @param  This      Protocol instance pointer.
 524   @param  Position  Byte position from the start of the file.
 525
 526   @retval EFI_SUCCESS     Position was updated.
 527   @retval EFI_UNSUPPORTED Seek request for directories is not valid.
 528
 529 **/
 530 EFI_STATUS
 531 EFIAPI
 532 UdfGetPosition (
 533   IN   EFI_FILE_PROTOCOL  *This,
 534   OUT  UINT64             *Position
 535   );
 536
 537 /**
 538   Set file's current position.
 539
 540   @param  This      Protocol instance pointer.
 541   @param  Position  Byte position from the start of the file.
 542
 543   @retval EFI_SUCCESS      Position was updated.
 544   @retval EFI_UNSUPPORTED  Seek request for non-zero is not valid on open.
 545
 546 **/
 547 EFI_STATUS
 548 EFIAPI
 549 UdfSetPosition (
 550   IN EFI_FILE_PROTOCOL  *This,
 551   IN UINT64             Position
 552   );
 553
 554 /**
 555   Get information about a file.
 556
 557   @attention This is boundary function that may receive untrusted input.
 558   @attention The input is from FileSystem.
 559
 560   The File Set Descriptor is external input, so this routine will do basic
 561   validation for File Set Descriptor and report status.
 562
 563   @param  This            Protocol instance pointer.
 564   @param  InformationType Type of information to return in Buffer.
 565   @param  BufferSize      On input size of buffer, on output amount of data in
 566                           buffer.
 567   @param  Buffer          The buffer to return data.
 568
 569   @retval EFI_SUCCESS          Data was returned.
 570   @retval EFI_UNSUPPORTED      InformationType is not supported.
 571   @retval EFI_NO_MEDIA         The device has no media.
 572   @retval EFI_DEVICE_ERROR     The device reported an error.
 573   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 574   @retval EFI_WRITE_PROTECTED  The device is write protected.
 575   @retval EFI_ACCESS_DENIED    The file was open for read only.
 576   @retval EFI_BUFFER_TOO_SMALL Buffer was too small; required size returned in
 577                                BufferSize.
 578
 579 **/
 580 EFI_STATUS
 581 EFIAPI
 582 UdfGetInfo (
 583   IN      EFI_FILE_PROTOCOL  *This,
 584   IN      EFI_GUID           *InformationType,
 585   IN OUT  UINTN              *BufferSize,
 586   OUT     VOID               *Buffer
 587   );
 588
 589 /**
 590   Set information about a file.
 591
 592   @param  This            Protocol instance pointer.
 593   @param  InformationType Type of information in Buffer.
 594   @param  BufferSize      Size of buffer.
 595   @param  Buffer          The data to write.
 596
 597   @retval EFI_SUCCESS          Data was set.
 598   @retval EFI_UNSUPPORTED      InformationType is not supported.
 599   @retval EFI_NO_MEDIA         The device has no media.
 600   @retval EFI_DEVICE_ERROR     The device reported an error.
 601   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 602   @retval EFI_WRITE_PROTECTED  The device is write protected.
 603   @retval EFI_ACCESS_DENIED    The file was open for read only.
 604
 605 **/
 606 EFI_STATUS
 607 EFIAPI
 608 UdfSetInfo (
 609   IN EFI_FILE_PROTOCOL  *This,
 610   IN EFI_GUID           *InformationType,
 611   IN UINTN              BufferSize,
 612   IN VOID               *Buffer
 613   );
 614
 615 /**
 616   Flush data back for the file handle.
 617
 618   @param  This Protocol instance pointer.
 619
 620   @retval EFI_SUCCESS          Data was flushed.
 621   @retval EFI_UNSUPPORTED      Writes to Open directory are not supported.
 622   @retval EFI_NO_MEDIA         The device has no media.
 623   @retval EFI_DEVICE_ERROR     The device reported an error.
 624   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 625   @retval EFI_WRITE_PROTECTED  The device is write protected.
 626   @retval EFI_ACCESS_DENIED    The file was open for read only.
 627   @retval EFI_VOLUME_FULL      The volume is full.
 628
 629 **/
 630 EFI_STATUS
 631 EFIAPI
 632 UdfFlush (
 633   IN EFI_FILE_PROTOCOL *This
 634   );
 635
 636 /**
 637   Read volume information on a medium which contains a valid UDF file system.
 638
 639   @param[in]   BlockIo  BlockIo interface.
 640   @param[in]   DiskIo   DiskIo interface.
 641   @param[out]  Volume   UDF volume information structure.
 642
 643   @retval EFI_SUCCESS          Volume information read.
 644   @retval EFI_NO_MEDIA         The device has no media.
 645   @retval EFI_DEVICE_ERROR     The device reported an error.
 646   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 647   @retval EFI_OUT_OF_RESOURCES The volume was not read due to lack of resources.
 648
 649 **/
 650 EFI_STATUS
 651 ReadUdfVolumeInformation (
 652   IN   EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 653   IN   EFI_DISK_IO_PROTOCOL   *DiskIo,
 654   OUT  UDF_VOLUME_INFO        *Volume
 655   );
 656
 657 /**
 658   Find the root directory on an UDF volume.
 659
 660   @param[in]   BlockIo  BlockIo interface.
 661   @param[in]   DiskIo   DiskIo interface.
 662   @param[in]   Volume   UDF volume information structure.
 663   @param[out]  File     Root directory file.
 664
 665   @retval EFI_SUCCESS          Root directory found.
 666   @retval EFI_NO_MEDIA         The device has no media.
 667   @retval EFI_DEVICE_ERROR     The device reported an error.
 668   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 669   @retval EFI_OUT_OF_RESOURCES The root directory was not found due to lack of
 670                                resources.
 671
 672 **/
 673 EFI_STATUS
 674 FindRootDirectory (
 675   IN   EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 676   IN   EFI_DISK_IO_PROTOCOL   *DiskIo,
 677   IN   UDF_VOLUME_INFO        *Volume,
 678   OUT  UDF_FILE_INFO          *File
 679   );
 680
 681 /**
 682   Find either a File Entry or a Extended File Entry from a given ICB.
 683
 684   @param[in]   BlockIo    BlockIo interface.
 685   @param[in]   DiskIo     DiskIo interface.
 686   @param[in]   Volume     UDF volume information structure.
 687   @param[in]   Icb        ICB of the FID.
 688   @param[out]  FileEntry  File Entry or Extended File Entry.
 689
 690   @retval EFI_SUCCESS          File Entry or Extended File Entry found.
 691   @retval EFI_NO_MEDIA         The device has no media.
 692   @retval EFI_DEVICE_ERROR     The device reported an error.
 693   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 694   @retval EFI_OUT_OF_RESOURCES The FE/EFE entry was not found due to lack of
 695                                resources.
 696
 697 **/
 698 EFI_STATUS
 699 FindFileEntry (
 700   IN   EFI_BLOCK_IO_PROTOCOL           *BlockIo,
 701   IN   EFI_DISK_IO_PROTOCOL            *DiskIo,
 702   IN   UDF_VOLUME_INFO                 *Volume,
 703   IN   UDF_LONG_ALLOCATION_DESCRIPTOR  *Icb,
 704   OUT  VOID                            **FileEntry
 705   );
 706
 707 /**
 708   Find a file given its absolute path on an UDF volume.
 709
 710   @param[in]   BlockIo   BlockIo interface.
 711   @param[in]   DiskIo    DiskIo interface.
 712   @param[in]   Volume    UDF volume information structure.
 713   @param[in]   FilePath  File's absolute path.
 714   @param[in]   Root      Root directory file.
 715   @param[in]   Parent    Parent directory file.
 716   @param[in]   Icb       ICB of Parent.
 717   @param[out]  File      Found file.
 718
 719   @retval EFI_SUCCESS          FilePath was found.
 720   @retval EFI_NO_MEDIA         The device has no media.
 721   @retval EFI_DEVICE_ERROR     The device reported an error.
 722   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 723   @retval EFI_OUT_OF_RESOURCES The FilePath file was not found due to lack of
 724                                resources.
 725
 726 **/
 727 EFI_STATUS
 728 FindFile (
 729   IN   EFI_BLOCK_IO_PROTOCOL           *BlockIo,
 730   IN   EFI_DISK_IO_PROTOCOL            *DiskIo,
 731   IN   UDF_VOLUME_INFO                 *Volume,
 732   IN   CHAR16                          *FilePath,
 733   IN   UDF_FILE_INFO                   *Root,
 734   IN   UDF_FILE_INFO                   *Parent,
 735   IN   UDF_LONG_ALLOCATION_DESCRIPTOR  *Icb,
 736   OUT  UDF_FILE_INFO                   *File
 737   );
 738
 739 /**
 740   Read a directory entry at a time on an UDF volume.
 741
 742   @param[in]      BlockIo        BlockIo interface.
 743   @param[in]      DiskIo         DiskIo interface.
 744   @param[in]      Volume         UDF volume information structure.
 745   @param[in]      ParentIcb      ICB of the parent file.
 746   @param[in]      FileEntryData  FE/EFE of the parent file.
 747   @param[in, out] ReadDirInfo    Next read directory listing structure
 748                                  information.
 749   @param[out]     FoundFid       File Identifier Descriptor pointer.
 750
 751   @retval EFI_SUCCESS          Directory entry read.
 752   @retval EFI_UNSUPPORTED      Extended Allocation Descriptors not supported.
 753   @retval EFI_NO_MEDIA         The device has no media.
 754   @retval EFI_DEVICE_ERROR     The device reported an error.
 755   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 756   @retval EFI_OUT_OF_RESOURCES The directory entry was not read due to lack of
 757                                resources.
 758
 759 **/
 760 EFI_STATUS
 761 ReadDirectoryEntry (
 762   IN      EFI_BLOCK_IO_PROTOCOL           *BlockIo,
 763   IN      EFI_DISK_IO_PROTOCOL            *DiskIo,
 764   IN      UDF_VOLUME_INFO                 *Volume,
 765   IN      UDF_LONG_ALLOCATION_DESCRIPTOR  *ParentIcb,
 766   IN      VOID                            *FileEntryData,
 767   IN OUT  UDF_READ_DIRECTORY_INFO         *ReadDirInfo,
 768   OUT     UDF_FILE_IDENTIFIER_DESCRIPTOR  **FoundFid
 769   );
 770
 771 /**
 772   Get a filename (encoded in OSTA-compressed format) from a File Identifier
 773   Descriptor on an UDF volume.
 774
 775   @attention This is boundary function that may receive untrusted input.
 776   @attention The input is from FileSystem.
 777
 778   The File Identifier Descriptor is external input, so this routine will do
 779   basic validation for File Identifier Descriptor and report status.
 780
 781   @param[in]   FileIdentifierDesc  File Identifier Descriptor pointer.
 782   @param[in]   CharMax             The maximum number of FileName Unicode char,
 783                                    including terminating null char.
 784   @param[out]  FileName            Decoded filename.
 785
 786   @retval EFI_SUCCESS           Filename decoded and read.
 787   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 788   @retval EFI_BUFFER_TOO_SMALL  The string buffer FileName cannot hold the
 789                                 decoded filename.
 790 **/
 791 EFI_STATUS
 792 GetFileNameFromFid (
 793   IN   UDF_FILE_IDENTIFIER_DESCRIPTOR  *FileIdentifierDesc,
 794   IN   UINTN                           CharMax,
 795   OUT  CHAR16                          *FileName
 796   );
 797
 798 /**
 799   Resolve a symlink file on an UDF volume.
 800
 801   @attention This is boundary function that may receive untrusted input.
 802   @attention The input is from FileSystem.
 803
 804   The Path Component is external input, so this routine will do basic
 805   validation for Path Component and report status.
 806
 807   @param[in]   BlockIo        BlockIo interface.
 808   @param[in]   DiskIo         DiskIo interface.
 809   @param[in]   Volume         UDF volume information structure.
 810   @param[in]   Parent         Parent file.
 811   @param[in]   FileEntryData  FE/EFE structure pointer.
 812   @param[out]  File           Resolved file.
 813
 814   @retval EFI_SUCCESS          Symlink file resolved.
 815   @retval EFI_UNSUPPORTED      Extended Allocation Descriptors not supported.
 816   @retval EFI_NO_MEDIA         The device has no media.
 817   @retval EFI_DEVICE_ERROR     The device reported an error.
 818   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 819   @retval EFI_OUT_OF_RESOURCES The symlink file was not resolved due to lack of
 820                                resources.
 821
 822 **/
 823 EFI_STATUS
 824 ResolveSymlink (
 825   IN   EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 826   IN   EFI_DISK_IO_PROTOCOL   *DiskIo,
 827   IN   UDF_VOLUME_INFO        *Volume,
 828   IN   UDF_FILE_INFO          *Parent,
 829   IN   VOID                   *FileEntryData,
 830   OUT  UDF_FILE_INFO          *File
 831   );
 832
 833 /**
 834   Clean up in-memory UDF file information.
 835
 836   @param[in] File File information pointer.
 837
 838 **/
 839 VOID
 840 CleanupFileInformation (
 841   IN UDF_FILE_INFO *File
 842   );
 843
 844 /**
 845   Find a file from its absolute path on an UDF volume.
 846
 847   @param[in]   BlockIo  BlockIo interface.
 848   @param[in]   DiskIo   DiskIo interface.
 849   @param[in]   Volume   UDF volume information structure.
 850   @param[in]   File     File information structure.
 851   @param[out]  Size     Size of the file.
 852
 853   @retval EFI_SUCCESS          File size calculated and set in Size.
 854   @retval EFI_UNSUPPORTED      Extended Allocation Descriptors not supported.
 855   @retval EFI_NO_MEDIA         The device has no media.
 856   @retval EFI_DEVICE_ERROR     The device reported an error.
 857   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 858   @retval EFI_OUT_OF_RESOURCES The file size was not calculated due to lack of
 859                                resources.
 860
 861 **/
 862 EFI_STATUS
 863 GetFileSize (
 864   IN   EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 865   IN   EFI_DISK_IO_PROTOCOL   *DiskIo,
 866   IN   UDF_VOLUME_INFO        *Volume,
 867   IN   UDF_FILE_INFO          *File,
 868   OUT  UINT64                 *Size
 869   );
 870
 871 /**
 872   Set information about a file on an UDF volume.
 873
 874   @param[in]      File        File pointer.
 875   @param[in]      FileSize    Size of the file.
 876   @param[in]      FileName    Filename of the file.
 877   @param[in, out] BufferSize  Size of the returned file infomation.
 878   @param[out]     Buffer      Data of the returned file information.
 879
 880   @retval EFI_SUCCESS          File information set.
 881   @retval EFI_NO_MEDIA         The device has no media.
 882   @retval EFI_DEVICE_ERROR     The device reported an error.
 883   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 884   @retval EFI_OUT_OF_RESOURCES The file information was not set due to lack of
 885                                resources.
 886
 887 **/
 888 EFI_STATUS
 889 SetFileInfo (
 890   IN      UDF_FILE_INFO  *File,
 891   IN      UINT64         FileSize,
 892   IN      CHAR16         *FileName,
 893   IN OUT  UINTN          *BufferSize,
 894   OUT     VOID           *Buffer
 895   );
 896
 897 /**
 898   Get volume label of an UDF volume.
 899
 900   @attention This is boundary function that may receive untrusted input.
 901   @attention The input is from FileSystem.
 902
 903   The File Set Descriptor is external input, so this routine will do basic
 904   validation for File Set Descriptor and report status.
 905
 906   @param[in]   Volume   Volume information pointer.
 907   @param[in]   CharMax  The maximum number of Unicode char in String,
 908                         including terminating null char.
 909   @param[out]  String   String buffer pointer to store the volume label.
 910
 911   @retval EFI_SUCCESS           Volume label is returned.
 912   @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.
 913   @retval EFI_BUFFER_TOO_SMALL  The string buffer String cannot hold the
 914                                 volume label.
 915
 916 **/
 917 EFI_STATUS
 918 GetVolumeLabel (
 919   IN   UDF_VOLUME_INFO  *Volume,
 920   IN   UINTN            CharMax,
 921   OUT  CHAR16           *String
 922   );
 923
 924 /**
 925   Get volume and free space size information of an UDF volume.
 926
 927   @attention This is boundary function that may receive untrusted input.
 928   @attention The input is from FileSystem.
 929
 930   The Logical Volume Descriptor and the Logical Volume Integrity Descriptor are
 931   external inputs, so this routine will do basic validation for both descriptors
 932   and report status.
 933
 934   @param[in]   BlockIo        BlockIo interface.
 935   @param[in]   DiskIo         DiskIo interface.
 936   @param[in]   Volume         UDF volume information structure.
 937   @param[out]  VolumeSize     Volume size.
 938   @param[out]  FreeSpaceSize  Free space size.
 939
 940   @retval EFI_SUCCESS          Volume and free space size calculated.
 941   @retval EFI_NO_MEDIA         The device has no media.
 942   @retval EFI_DEVICE_ERROR     The device reported an error.
 943   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 944   @retval EFI_OUT_OF_RESOURCES The volume and free space size were not
 945                                calculated due to lack of resources.
 946
 947 **/
 948 EFI_STATUS
 949 GetVolumeSize (
 950   IN   EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 951   IN   EFI_DISK_IO_PROTOCOL   *DiskIo,
 952   IN   UDF_VOLUME_INFO        *Volume,
 953   OUT  UINT64                 *VolumeSize,
 954   OUT  UINT64                 *FreeSpaceSize
 955   );
 956
 957 /**
 958   Seek a file and read its data into memory on an UDF volume.
 959
 960   @param[in]      BlockIo       BlockIo interface.
 961   @param[in]      DiskIo        DiskIo interface.
 962   @param[in]      Volume        UDF volume information structure.
 963   @param[in]      File          File information structure.
 964   @param[in]      FileSize      Size of the file.
 965   @param[in, out] FilePosition  File position.
 966   @param[in, out] Buffer        File data.
 967   @param[in, out] BufferSize    Read size.
 968
 969   @retval EFI_SUCCESS          File seeked and read.
 970   @retval EFI_UNSUPPORTED      Extended Allocation Descriptors not supported.
 971   @retval EFI_NO_MEDIA         The device has no media.
 972   @retval EFI_DEVICE_ERROR     The device reported an error.
 973   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 974   @retval EFI_OUT_OF_RESOURCES The file's recorded data was not read due to lack
 975                                of resources.
 976
 977 **/
 978 EFI_STATUS
 979 ReadFileData (
 980   IN      EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 981   IN      EFI_DISK_IO_PROTOCOL   *DiskIo,
 982   IN      UDF_VOLUME_INFO        *Volume,
 983   IN      UDF_FILE_INFO          *File,
 984   IN      UINT64                 FileSize,
 985   IN OUT  UINT64                 *FilePosition,
 986   IN OUT  VOID                   *Buffer,
 987   IN OUT  UINT64                 *BufferSize
 988   );
 989
 990 /**
 991   Check if ControllerHandle supports an UDF file system.
 992
 993   @param[in]  This                Protocol instance pointer.
 994   @param[in]  ControllerHandle    Handle of device to test.
 995
 996   @retval EFI_SUCCESS             UDF file system found.
 997   @retval EFI_UNSUPPORTED         UDF file system not found.
 998
 999 **/
1000 EFI_STATUS
1001 SupportUdfFileSystem (
1002   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
1003   IN EFI_HANDLE                   ControllerHandle
1004   );
1005
1006 /**
1007   Mangle a filename by cutting off trailing whitespaces, "\\", "." and "..".
1008
1009   @param[in] FileName Filename.
1010
1011   @retval The mangled Filename.
1012
1013 **/
1014 CHAR16 *
1015 MangleFileName (
1016   IN CHAR16        *FileName
1017   );
1018
1019 /**
1020   Test to see if this driver supports ControllerHandle. Any ControllerHandle
1021   than contains a BlockIo and DiskIo protocol can be supported.
1022
1023   @param  This                Protocol instance pointer.
1024   @param  ControllerHandle    Handle of device to test
1025   @param  RemainingDevicePath Optional parameter use to pick a specific child
1026                               device to start.
1027
1028   @retval EFI_SUCCESS         This driver supports this device
1029   @retval EFI_ALREADY_STARTED This driver is already running on this device
1030   @retval other               This driver does not support this device
1031
1032 **/
1033 EFI_STATUS
1034 EFIAPI
1035 UdfDriverBindingSupported (
1036   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
1037   IN EFI_HANDLE                   ControllerHandle,
1038   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
1039   );
1040
1041 /**
1042   Start this driver on ControllerHandle by opening a Block IO and Disk IO
1043   protocol, reading Device Path, and creating a child handle with a
1044   Disk IO and device path protocol.
1045
1046   @param  This                 Protocol instance pointer.
1047   @param  ControllerHandle     Handle of device to bind driver to
1048   @param  RemainingDevicePath  Optional parameter use to pick a specific child
1049                                device to start.
1050
1051   @retval EFI_SUCCESS          This driver is added to ControllerHandle
1052   @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle
1053   @retval other                This driver does not support this device
1054
1055 **/
1056 EFI_STATUS
1057 EFIAPI
1058 UdfDriverBindingStart (
1059   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
1060   IN EFI_HANDLE                   ControllerHandle,
1061   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
1062   );
1063
1064 /**
1065   Stop this driver on ControllerHandle. Support stopping any child handles
1066   created by this driver.
1067
1068   @param  This              Protocol instance pointer.
1069   @param  ControllerHandle  Handle of device to stop driver on
1070   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of
1071                             children is zero stop the entire bus driver.
1072   @param  ChildHandleBuffer List of Child Handles to Stop.
1073
1074   @retval EFI_SUCCESS       This driver is removed ControllerHandle
1075   @retval other             This driver was not removed from this device
1076
1077 **/
1078 EFI_STATUS
1079 EFIAPI
1080 UdfDriverBindingStop (
1081   IN  EFI_DRIVER_BINDING_PROTOCOL   *This,
1082   IN  EFI_HANDLE                    ControllerHandle,
1083   IN  UINTN                         NumberOfChildren,
1084   IN  EFI_HANDLE                    *ChildHandleBuffer
1085   );
1086
1087 //
1088 // EFI Component Name Functions
1089 //
1090 /**
1091   Retrieves a Unicode string that is the user readable name of the driver.
1092
1093   This function retrieves the user readable name of a driver in the form of a
1094   Unicode string. If the driver specified by This has a user readable name in
1095   the language specified by Language, then a pointer to the driver name is
1096   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
1097   by This does not support the language specified by Language,
1098   then EFI_UNSUPPORTED is returned.
1099
1100   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
1101                                 EFI_COMPONENT_NAME_PROTOCOL instance.
1102
1103   @param  Language[in]          A pointer to a Null-terminated ASCII string
1104                                 array indicating the language. This is the
1105                                 language of the driver name that the caller is
1106                                 requesting, and it must match one of the
1107                                 languages specified in SupportedLanguages. The
1108                                 number of languages supported by a driver is up
1109                                 to the driver writer. Language is specified
1110                                 in RFC 4646 or ISO 639-2 language code format.
1111
1112   @param  DriverName[out]       A pointer to the Unicode string to return.
1113                                 This Unicode string is the name of the
1114                                 driver specified by This in the language
1115                                 specified by Language.
1116
1117   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
1118                                 This and the language specified by Language was
1119                                 returned in DriverName.
1120
1121   @retval EFI_INVALID_PARAMETER Language is NULL.
1122
1123   @retval EFI_INVALID_PARAMETER DriverName is NULL.
1124
1125   @retval EFI_UNSUPPORTED       The driver specified by This does not support
1126                                 the language specified by Language.
1127
1128 **/
1129 EFI_STATUS
1130 EFIAPI
1131 UdfComponentNameGetDriverName (
1132   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
1133   IN  CHAR8                        *Language,
1134   OUT CHAR16                       **DriverName
1135   );
1136
1137 /**
1138   Retrieves a Unicode string that is the user readable name of the controller
1139   that is being managed by a driver.
1140
1141   This function retrieves the user readable name of the controller specified by
1142   ControllerHandle and ChildHandle in the form of a Unicode string. If the
1143   driver specified by This has a user readable name in the language specified by
1144   Language, then a pointer to the controller name is returned in ControllerName,
1145   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
1146   managing the controller specified by ControllerHandle and ChildHandle,
1147   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
1148   support the language specified by Language, then EFI_UNSUPPORTED is returned.
1149
1150   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
1151                                 EFI_COMPONENT_NAME_PROTOCOL instance.
1152
1153   @param  ControllerHandle[in]  The handle of a controller that the driver
1154                                 specified by This is managing.  This handle
1155                                 specifies the controller whose name is to be
1156                                 returned.
1157
1158   @param  ChildHandle[in]       The handle of the child controller to retrieve
1159                                 the name of.  This is an optional parameter that
1160                                 may be NULL.  It will be NULL for device
1161                                 drivers.  It will also be NULL for a bus drivers
1162                                 that wish to retrieve the name of the bus
1163                                 controller.  It will not be NULL for a bus
1164                                 driver that wishes to retrieve the name of a
1165                                 child controller.
1166
1167   @param  Language[in]          A pointer to a Null-terminated ASCII string
1168                                 array indicating the language.  This is the
1169                                 language of the driver name that the caller is
1170                                 requesting, and it must match one of the
1171                                 languages specified in SupportedLanguages. The
1172                                 number of languages supported by a driver is up
1173                                 to the driver writer. Language is specified in
1174                                 RFC 4646 or ISO 639-2 language code format.
1175
1176   @param  ControllerName[out]   A pointer to the Unicode string to return.
1177                                 This Unicode string is the name of the
1178                                 controller specified by ControllerHandle and
1179                                 ChildHandle in the language specified by
1180                                 Language from the point of view of the driver
1181                                 specified by This.
1182
1183   @retval EFI_SUCCESS           The Unicode string for the user readable name in
1184                                 the language specified by Language for the
1185                                 driver specified by This was returned in
1186                                 DriverName.
1187
1188   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
1189
1190   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
1191                                 EFI_HANDLE.
1192
1193   @retval EFI_INVALID_PARAMETER Language is NULL.
1194
1195   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
1196
1197   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
1198                                 managing the controller specified by
1199                                 ControllerHandle and ChildHandle.
1200
1201   @retval EFI_UNSUPPORTED       The driver specified by This does not support
1202                                 the language specified by Language.
1203
1204 **/
1205 EFI_STATUS
1206 EFIAPI
1207 UdfComponentNameGetControllerName (
1208   IN   EFI_COMPONENT_NAME_PROTOCOL  *This,
1209   IN   EFI_HANDLE                   ControllerHandle,
1210   IN   EFI_HANDLE                   ChildHandle OPTIONAL,
1211   IN   CHAR8                        *Language,
1212   OUT  CHAR16                       **ControllerName
1213   );
1214
1215 #endif // _UDF_H_