MdePkg/Include/Library/DevicePathLib.h

   1 /** @file
   2         Entry point to a DXE Boot Services Driver
   3
   4         Copyright (c) 2006, Intel Corporation
   5         All rights reserved. This program and the accompanying materials
   6         are licensed and made available under the terms and conditions of the BSD License
   7         which accompanies this distribution.  The full text of the license may be found at
   8         http://opensource.org/licenses/bsd-license.php
   9
  10         THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11         WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13         Module Name:    DevicePathLib.h
  14
  15 **/
  16
  17 #ifndef __DEVICE_PATH_LIB_H__
  18 #define __DEVICE_PATH_LIB_H__
  19
  20 /**
  21         This function returns the size, in bytes,
  22         of the device path data structure specified by DevicePath.
  23         If DevicePath is NULL, then 0 is returned.
  24
  25         @param  DevicePath A pointer to a device path data structure.
  26
  27         @return The size of a device path in bytes.
  28
  29 **/
  30 UINTN
  31 EFIAPI
  32 GetDevicePathSize (
  33   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
  34   )
  35 ;
  36
  37 /**
  38         This function allocates space for a new copy of the device path
  39         specified by DevicePath.
  40
  41         @param  DevicePath A pointer to a device path data structure.
  42
  43         @return The duplicated device path.
  44
  45 **/
  46 EFI_DEVICE_PATH_PROTOCOL *
  47 EFIAPI
  48 DuplicateDevicePath (
  49   IN CONST EFI_DEVICE_PATH_PROTOCOL   *DevicePath
  50   )
  51 ;
  52
  53 /**
  54         This function appends the device path SecondDevicePath
  55         to every device path instance in FirstDevicePath.
  56
  57         @param  FirstDevicePath A pointer to a device path data structure.
  58
  59         @param  SecondDevicePath A pointer to a device path data structure.
  60
  61         @return
  62         A pointer to the new device path is returned.
  63         NULL is returned if space for the new device path could not be allocated from pool.
  64         It is up to the caller to free the memory used by FirstDevicePath and SecondDevicePath
  65         if they are no longer needed.
  66
  67 **/
  68 EFI_DEVICE_PATH_PROTOCOL *
  69 EFIAPI
  70 AppendDevicePath (
  71   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,
  72   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath
  73   )
  74 ;
  75
  76 /**
  77         This function appends the device path node SecondDevicePath
  78         to every device path instance in FirstDevicePath.
  79
  80         @param  FirstDevicePath A pointer to a device path data structure.
  81
  82         @param  SecondDevicePath A pointer to a single device path node.
  83
  84         @return
  85         A pointer to the new device path.
  86         If there is not enough temporary pool memory available to complete this function,
  87         then NULL is returned.
  88
  89 **/
  90 EFI_DEVICE_PATH_PROTOCOL *
  91 EFIAPI
  92 AppendDevicePathNode (
  93   IN CONST EFI_DEVICE_PATH_PROTOCOL  *FirstDevicePath,
  94   IN CONST EFI_DEVICE_PATH_PROTOCOL  *SecondDevicePath
  95   )
  96 ;
  97
  98 /**
  99         This function appends the device path instance Instance to the device path Source.
 100         If Source is NULL, then a new device path with one instance is created.
 101
 102         @param  Source A pointer to a device path data structure.
 103         @param  Instance A pointer to a device path instance.
 104
 105         @return
 106         A pointer to the new device path.
 107         If there is not enough temporary pool memory available to complete this function,
 108         then NULL is returned.
 109
 110 **/
 111 EFI_DEVICE_PATH_PROTOCOL *
 112 EFIAPI
 113 AppendDevicePathInstance (
 114   IN CONST EFI_DEVICE_PATH_PROTOCOL  *Source,
 115   IN CONST EFI_DEVICE_PATH_PROTOCOL  *Instance
 116   )
 117 ;
 118
 119 /**
 120         Function retrieves the next device path instance from a device path data structure.
 121
 122         @param  DevicePath A pointer to a device path data structure.
 123
 124         @param  Size A pointer to the size of a device path instance in bytes.
 125
 126         @return
 127         This function returns a pointer to the current device path instance.
 128         In addition, it returns the size in bytes of the current device path instance in Size,
 129         and a pointer to the next device path instance in DevicePath.
 130         If there are no more device path instances in DevicePath, then DevicePath will be set to NULL.
 131
 132 **/
 133 EFI_DEVICE_PATH_PROTOCOL *
 134 EFIAPI
 135 GetNextDevicePathInstance (
 136   IN OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath,
 137      OUT UINTN                     *Size
 138   )
 139 ;
 140
 141 /**
 142         Return TRUE is this is a multi instance device path.
 143
 144         @param  DevicePath A pointer to a device path data structure.
 145
 146         @retval TRUE If DevicePath is multi-instance.
 147         @retval FALSE If DevicePath is not multi-instance or DevicePath is NULL.
 148
 149 **/
 150 BOOLEAN
 151 EFIAPI
 152 IsDevicePathMultiInstance (
 153   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 154   )
 155 ;
 156
 157 /**
 158         This function retrieves the device path protocol from a handle.
 159
 160         @param  Handle The handle from which to retrieve the device path protocol.
 161
 162         @return
 163         This function returns the device path protocol from the handle specified by Handle.
 164         If Handle is NULL or Handle does not contain a device path protocol, then NULL is returned.
 165
 166 **/
 167 EFI_DEVICE_PATH_PROTOCOL *
 168 EFIAPI
 169 DevicePathFromHandle (
 170   IN EFI_HANDLE  Handle
 171   )
 172 ;
 173
 174 /**
 175         This function allocates a device path for a file and appends it to an existing device path.
 176
 177         @param  Device A pointer to a device handle.  This parameter is optional and may be NULL.
 178         @param  FileName A pointer to a Null-terminated Unicode string.
 179
 180         @return
 181         If Device is a valid device handle that contains a device path protocol,
 182         then a device path for the file specified by FileName is allocated
 183         and appended to the device path associated with the handle Device. The allocated device path is returned.
 184         If Device is NULL or Device is a handle that does not support the device path protocol,
 185         then a device path containing a single device path node for the file specified by FileName
 186         is allocated and returned.
 187
 188 **/
 189 EFI_DEVICE_PATH_PROTOCOL *
 190 EFIAPI
 191 FileDevicePath (
 192   IN EFI_HANDLE    Device,     OPTIONAL
 193   IN CONST CHAR16  *FileName
 194   )
 195 ;
 196
 197 #endif