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 and free space size information 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 Logical Volume Descriptor and the Logical Volume Integrity Descriptor are
 910   external inputs, so this routine will do basic validation for both descriptors
 911   and report status.
 912
 913   @param[in]   BlockIo        BlockIo interface.
 914   @param[in]   DiskIo         DiskIo interface.
 915   @param[in]   Volume         UDF volume information structure.
 916   @param[out]  VolumeSize     Volume size.
 917   @param[out]  FreeSpaceSize  Free space size.
 918
 919   @retval EFI_SUCCESS          Volume and free space size calculated.
 920   @retval EFI_NO_MEDIA         The device has no media.
 921   @retval EFI_DEVICE_ERROR     The device reported an error.
 922   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 923   @retval EFI_OUT_OF_RESOURCES The volume and free space size were not
 924                                calculated due to lack of resources.
 925
 926 **/
 927 EFI_STATUS
 928 GetVolumeSize (
 929   IN   EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 930   IN   EFI_DISK_IO_PROTOCOL   *DiskIo,
 931   IN   UDF_VOLUME_INFO        *Volume,
 932   OUT  UINT64                 *VolumeSize,
 933   OUT  UINT64                 *FreeSpaceSize
 934   );
 935
 936 /**
 937   Seek a file and read its data into memory on an UDF volume.
 938
 939   @param[in]      BlockIo       BlockIo interface.
 940   @param[in]      DiskIo        DiskIo interface.
 941   @param[in]      Volume        UDF volume information structure.
 942   @param[in]      File          File information structure.
 943   @param[in]      FileSize      Size of the file.
 944   @param[in, out] FilePosition  File position.
 945   @param[in, out] Buffer        File data.
 946   @param[in, out] BufferSize    Read size.
 947
 948   @retval EFI_SUCCESS          File seeked and read.
 949   @retval EFI_UNSUPPORTED      Extended Allocation Descriptors not supported.
 950   @retval EFI_NO_MEDIA         The device has no media.
 951   @retval EFI_DEVICE_ERROR     The device reported an error.
 952   @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
 953   @retval EFI_OUT_OF_RESOURCES The file's recorded data was not read due to lack
 954                                of resources.
 955
 956 **/
 957 EFI_STATUS
 958 ReadFileData (
 959   IN      EFI_BLOCK_IO_PROTOCOL  *BlockIo,
 960   IN      EFI_DISK_IO_PROTOCOL   *DiskIo,
 961   IN      UDF_VOLUME_INFO        *Volume,
 962   IN      UDF_FILE_INFO          *File,
 963   IN      UINT64                 FileSize,
 964   IN OUT  UINT64                 *FilePosition,
 965   IN OUT  VOID                   *Buffer,
 966   IN OUT  UINT64                 *BufferSize
 967   );
 968
 969 /**
 970   Check if ControllerHandle supports an UDF file system.
 971
 972   @param[in]  This                Protocol instance pointer.
 973   @param[in]  ControllerHandle    Handle of device to test.
 974
 975   @retval EFI_SUCCESS             UDF file system found.
 976   @retval EFI_UNSUPPORTED         UDF file system not found.
 977
 978 **/
 979 EFI_STATUS
 980 SupportUdfFileSystem (
 981   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 982   IN EFI_HANDLE                   ControllerHandle
 983   );
 984
 985 /**
 986   Mangle a filename by cutting off trailing whitespaces, "\\", "." and "..".
 987
 988   @param[in] FileName Filename.
 989
 990   @retval The mangled Filename.
 991
 992 **/
 993 CHAR16 *
 994 MangleFileName (
 995   IN CHAR16        *FileName
 996   );
 997
 998 /**
 999   Test to see if this driver supports ControllerHandle. Any ControllerHandle
1000   than contains a BlockIo and DiskIo protocol can be supported.
1001
1002   @param  This                Protocol instance pointer.
1003   @param  ControllerHandle    Handle of device to test
1004   @param  RemainingDevicePath Optional parameter use to pick a specific child
1005                               device to start.
1006
1007   @retval EFI_SUCCESS         This driver supports this device
1008   @retval EFI_ALREADY_STARTED This driver is already running on this device
1009   @retval other               This driver does not support this device
1010
1011 **/
1012 EFI_STATUS
1013 EFIAPI
1014 UdfDriverBindingSupported (
1015   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
1016   IN EFI_HANDLE                   ControllerHandle,
1017   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
1018   );
1019
1020 /**
1021   Start this driver on ControllerHandle by opening a Block IO and Disk IO
1022   protocol, reading Device Path, and creating a child handle with a
1023   Disk IO and device path protocol.
1024
1025   @param  This                 Protocol instance pointer.
1026   @param  ControllerHandle     Handle of device to bind driver to
1027   @param  RemainingDevicePath  Optional parameter use to pick a specific child
1028                                device to start.
1029
1030   @retval EFI_SUCCESS          This driver is added to ControllerHandle
1031   @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle
1032   @retval other                This driver does not support this device
1033
1034 **/
1035 EFI_STATUS
1036 EFIAPI
1037 UdfDriverBindingStart (
1038   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
1039   IN EFI_HANDLE                   ControllerHandle,
1040   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
1041   );
1042
1043 /**
1044   Stop this driver on ControllerHandle. Support stopping any child handles
1045   created by this driver.
1046
1047   @param  This              Protocol instance pointer.
1048   @param  ControllerHandle  Handle of device to stop driver on
1049   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of
1050                             children is zero stop the entire bus driver.
1051   @param  ChildHandleBuffer List of Child Handles to Stop.
1052
1053   @retval EFI_SUCCESS       This driver is removed ControllerHandle
1054   @retval other             This driver was not removed from this device
1055
1056 **/
1057 EFI_STATUS
1058 EFIAPI
1059 UdfDriverBindingStop (
1060   IN  EFI_DRIVER_BINDING_PROTOCOL   *This,
1061   IN  EFI_HANDLE                    ControllerHandle,
1062   IN  UINTN                         NumberOfChildren,
1063   IN  EFI_HANDLE                    *ChildHandleBuffer
1064   );
1065
1066 //
1067 // EFI Component Name Functions
1068 //
1069 /**
1070   Retrieves a Unicode string that is the user readable name of the driver.
1071
1072   This function retrieves the user readable name of a driver in the form of a
1073   Unicode string. If the driver specified by This has a user readable name in
1074   the language specified by Language, then a pointer to the driver name is
1075   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
1076   by This does not support the language specified by Language,
1077   then EFI_UNSUPPORTED is returned.
1078
1079   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
1080                                 EFI_COMPONENT_NAME_PROTOCOL instance.
1081
1082   @param  Language[in]          A pointer to a Null-terminated ASCII string
1083                                 array indicating the language. This is the
1084                                 language of the driver name that the caller is
1085                                 requesting, and it must match one of the
1086                                 languages specified in SupportedLanguages. The
1087                                 number of languages supported by a driver is up
1088                                 to the driver writer. Language is specified
1089                                 in RFC 4646 or ISO 639-2 language code format.
1090
1091   @param  DriverName[out]       A pointer to the Unicode string to return.
1092                                 This Unicode string is the name of the
1093                                 driver specified by This in the language
1094                                 specified by Language.
1095
1096   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
1097                                 This and the language specified by Language was
1098                                 returned in DriverName.
1099
1100   @retval EFI_INVALID_PARAMETER Language is NULL.
1101
1102   @retval EFI_INVALID_PARAMETER DriverName is NULL.
1103
1104   @retval EFI_UNSUPPORTED       The driver specified by This does not support
1105                                 the language specified by Language.
1106
1107 **/
1108 EFI_STATUS
1109 EFIAPI
1110 UdfComponentNameGetDriverName (
1111   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
1112   IN  CHAR8                        *Language,
1113   OUT CHAR16                       **DriverName
1114   );
1115
1116 /**
1117   Retrieves a Unicode string that is the user readable name of the controller
1118   that is being managed by a driver.
1119
1120   This function retrieves the user readable name of the controller specified by
1121   ControllerHandle and ChildHandle in the form of a Unicode string. If the
1122   driver specified by This has a user readable name in the language specified by
1123   Language, then a pointer to the controller name is returned in ControllerName,
1124   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
1125   managing the controller specified by ControllerHandle and ChildHandle,
1126   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
1127   support the language specified by Language, then EFI_UNSUPPORTED is returned.
1128
1129   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
1130                                 EFI_COMPONENT_NAME_PROTOCOL instance.
1131
1132   @param  ControllerHandle[in]  The handle of a controller that the driver
1133                                 specified by This is managing.  This handle
1134                                 specifies the controller whose name is to be
1135                                 returned.
1136
1137   @param  ChildHandle[in]       The handle of the child controller to retrieve
1138                                 the name of.  This is an optional parameter that
1139                                 may be NULL.  It will be NULL for device
1140                                 drivers.  It will also be NULL for a bus drivers
1141                                 that wish to retrieve the name of the bus
1142                                 controller.  It will not be NULL for a bus
1143                                 driver that wishes to retrieve the name of a
1144                                 child controller.
1145
1146   @param  Language[in]          A pointer to a Null-terminated ASCII string
1147                                 array indicating the language.  This is the
1148                                 language of the driver name that the caller is
1149                                 requesting, and it must match one of the
1150                                 languages specified in SupportedLanguages. The
1151                                 number of languages supported by a driver is up
1152                                 to the driver writer. Language is specified in
1153                                 RFC 4646 or ISO 639-2 language code format.
1154
1155   @param  ControllerName[out]   A pointer to the Unicode string to return.
1156                                 This Unicode string is the name of the
1157                                 controller specified by ControllerHandle and
1158                                 ChildHandle in the language specified by
1159                                 Language from the point of view of the driver
1160                                 specified by This.
1161
1162   @retval EFI_SUCCESS           The Unicode string for the user readable name in
1163                                 the language specified by Language for the
1164                                 driver specified by This was returned in
1165                                 DriverName.
1166
1167   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
1168
1169   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
1170                                 EFI_HANDLE.
1171
1172   @retval EFI_INVALID_PARAMETER Language is NULL.
1173
1174   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
1175
1176   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
1177                                 managing the controller specified by
1178                                 ControllerHandle and ChildHandle.
1179
1180   @retval EFI_UNSUPPORTED       The driver specified by This does not support
1181                                 the language specified by Language.
1182
1183 **/
1184 EFI_STATUS
1185 EFIAPI
1186 UdfComponentNameGetControllerName (
1187   IN   EFI_COMPONENT_NAME_PROTOCOL  *This,
1188   IN   EFI_HANDLE                   ControllerHandle,
1189   IN   EFI_HANDLE                   ChildHandle OPTIONAL,
1190   IN   CHAR8                        *Language,
1191   OUT  CHAR16                       **ControllerName
1192   );
1193
1194 #endif // _UDF_H_