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  DevicePath A pointer to a device path data structure.
  81
  82   @param  DevicePathNode A pointer to a single device path node.
  83
  84   @return A pointer to the new device path.
  85   If there is not enough temporary pool memory available to complete this function,
  86   then NULL is returned.
  87
  88 **/
  89 EFI_DEVICE_PATH_PROTOCOL *
  90 EFIAPI
  91 AppendDevicePathNode (
  92   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
  93   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePathNode
  94   )
  95 ;
  96
  97 /**
  98   This function appends the device path instance Instance to the device path Source.
  99   If Source is NULL, then a new device path with one instance is created.
 100
 101   @param  Source A pointer to a device path data structure.
 102   @param  Instance A pointer to a device path instance.
 103
 104   @return
 105   A pointer to the new device path.
 106   If there is not enough temporary pool memory available to complete this function,
 107   then NULL is returned.
 108
 109 **/
 110 EFI_DEVICE_PATH_PROTOCOL *
 111 EFIAPI
 112 AppendDevicePathInstance (
 113   IN CONST EFI_DEVICE_PATH_PROTOCOL  *Source,
 114   IN CONST EFI_DEVICE_PATH_PROTOCOL  *Instance
 115   )
 116 ;
 117
 118 /**
 119   Function retrieves the next device path instance from a device path data structure.
 120
 121   @param  DevicePath A pointer to a device path data structure.
 122
 123   @param  Size A pointer to the size of a device path instance in bytes.
 124
 125   @return
 126   This function returns a pointer to the current device path instance.
 127   In addition, it returns the size in bytes of the current device path instance in Size,
 128   and a pointer to the next device path instance in DevicePath.
 129   If there are no more device path instances in DevicePath, then DevicePath will be set to NULL.
 130
 131 **/
 132 EFI_DEVICE_PATH_PROTOCOL *
 133 EFIAPI
 134 GetNextDevicePathInstance (
 135   IN OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath,
 136      OUT UINTN                     *Size
 137   )
 138 ;
 139
 140 /**
 141   Return TRUE is this is a multi instance device path.
 142
 143   @param  DevicePath A pointer to a device path data structure.
 144
 145   @retval  TRUE If DevicePath is multi-instance.
 146   @retval  FALSE If DevicePath is not multi-instance or DevicePath is NULL.
 147
 148 **/
 149 BOOLEAN
 150 EFIAPI
 151 IsDevicePathMultiInstance (
 152   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath
 153   )
 154 ;
 155
 156 /**
 157   This function retrieves the device path protocol from a handle.
 158
 159   @param  Handle The handle from which to retrieve the device path protocol.
 160
 161   @return
 162   This function returns the device path protocol from the handle specified by Handle.
 163   If Handle is NULL or Handle does not contain a device path protocol, then NULL is returned.
 164
 165 **/
 166 EFI_DEVICE_PATH_PROTOCOL *
 167 EFIAPI
 168 DevicePathFromHandle (
 169   IN EFI_HANDLE  Handle
 170   )
 171 ;
 172
 173 /**
 174   This function allocates a device path for a file and appends it to an existing device path.
 175
 176   @param  Device A pointer to a device handle.  This parameter is optional and may be NULL.
 177   @param  FileName A pointer to a Null-terminated Unicode string.
 178
 179   @return
 180   If Device is a valid device handle that contains a device path protocol,
 181   then a device path for the file specified by FileName is allocated
 182   and appended to the device path associated with the handle Device. The allocated device path is returned.
 183   If Device is NULL or Device is a handle that does not support the device path protocol,
 184   then a device path containing a single device path node for the file specified by FileName
 185   is allocated and returned.
 186
 187 **/
 188 EFI_DEVICE_PATH_PROTOCOL *
 189 EFIAPI
 190 FileDevicePath (
 191   IN EFI_HANDLE    Device,     OPTIONAL
 192   IN CONST CHAR16  *FileName
 193   )
 194 ;
 195
 196 #endif