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