MdePkg/Include/Protocol/Arp.h

   1 /** @file
   2   Copyright (c) 2006, Intel Corporation
   3   All rights reserved. This program and the accompanying materials
   4   are licensed and made available under the terms and conditions of the BSD License
   5   which accompanies this distribution.  The full text of the license may be found at
   6   http://opensource.org/licenses/bsd-license.php
   7
   8   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   9   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  10
  11 **/
  12
  13 #ifndef __EFI_ARP_PROTOCOL_H__
  14 #define __EFI_ARP_PROTOCOL_H__
  15
  16 #define EFI_ARP_SERVICE_BINDING_PROTOCOL_GUID \
  17   { \
  18     0xf44c00ee, 0x1f2c, 0x4a00, {0xaa, 0x9, 0x1c, 0x9f, 0x3e, 0x8, 0x0, 0xa3 } \
  19   }
  20
  21 #define EFI_ARP_PROTOCOL_GUID \
  22   { \
  23     0xf4b427bb, 0xba21, 0x4f16, {0xbc, 0x4e, 0x43, 0xe4, 0x16, 0xab, 0x61, 0x9c } \
  24   }
  25
  26 typedef struct _EFI_ARP_PROTOCOL EFI_ARP_PROTOCOL;
  27
  28 typedef struct {
  29 UINT32                      Size;
  30 BOOLEAN                     DenyFlag;
  31 BOOLEAN                     StaticFlag;
  32 UINT16                      HwAddressType;
  33 UINT16                      SwAddressType;
  34 UINT8                       HwAddressLength;
  35 UINT8                       SwAddressLength;
  36 } EFI_ARP_FIND_DATA;
  37
  38 typedef struct {
  39   UINT16                    SwAddressType;      // Host byte order
  40   UINT8                     SwAddressLength;
  41   VOID                      *StationAddress;    // Network byte order
  42   UINT32                    EntryTimeOut;
  43   UINT32                    RetryCount;
  44   UINT32                    RetryTimeOut;
  45 } EFI_ARP_CONFIG_DATA;
  46
  47
  48 /**
  49   Assigns a station address (protocol type and network address) to this instance of the ARP cache.
  50
  51   @param  This                   A pointer to the EFI_ARP_PROTOCOL instance.
  52   @param  ConfigData             A pointer to the EFI_ARP_CONFIG_DATA structure.Buffer
  53
  54   @retval EFI_SUCCESS           The new station address was successfully registered.
  55   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
  56   @retval EFI_ACCESS_DENIED     The SwAddressType, SwAddressLength, or
  57                                 StationAddress is different from the one that is already
  58                                 registered.
  59   @retval EFI_OUT_OF_RESOURCES  Storage for the new StationAddress could not be allocated.
  60
  61 **/
  62 typedef
  63 EFI_STATUS
  64 (EFIAPI *EFI_ARP_CONFIGURE) (
  65   IN EFI_ARP_PROTOCOL       *This,
  66   IN EFI_ARP_CONFIG_DATA    *ConfigData   OPTIONAL
  67   )
  68 ;
  69
  70 /**
  71   Inserts an entry to the ARP cache.
  72
  73   @param  This            A pointer to the EFI_ARP_PROTOCOL instance.
  74   @param  DenyFlag        Set to TRUE if this entry is a "deny" entry. Set to FALSE if this
  75                           entry is a "normal" entry.
  76   @param  TargetSwAddress Pointer to a protocol address to add (or deny). May be set to
  77                           NULL if DenyFlag is TRUE.
  78   @param  TargetHwAddress Pointer to a hardware address to add (or deny). May be set to
  79                           NULL if DenyFlag is TRUE.
  80   @param  TimeoutValue    Time in 100-ns units that this entry will remain in the ARP
  81                           cache. A value of zero means that the entry is permanent. A
  82                           nonzero value will override the one given by Configure() if
  83                           the entry to be added is dynamic entry.
  84   @param  Overwrite       If TRUE, the matching cache entry will be overwritten with the
  85                           supplied parameters. If FALSE, EFI_ACCESS_DENIED
  86
  87   @retval EFI_SUCCESS           The entry has been added or updated.
  88   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
  89   @retval EFI_OUT_OF_RESOURCES  The new ARP cache entry could not be allocated.
  90   @retval EFI_ACCESS_DENIED     The ARP cache entry already exists and Overwrite is not true.
  91   @retval EFI_NOT_STARTED       The ARP driver instance has not been configured.
  92
  93 **/
  94 typedef
  95 EFI_STATUS
  96 (EFIAPI *EFI_ARP_ADD) (
  97   IN EFI_ARP_PROTOCOL       *This,
  98   IN BOOLEAN                DenyFlag,
  99   IN VOID                   *TargetSwAddress  OPTIONAL,
 100   IN VOID                   *TargetHwAddress  OPTIONAL,
 101   IN UINT32                 TimeoutValue,
 102   IN BOOLEAN                Overwrite
 103   )
 104 ;
 105
 106 /**
 107   Locates one or more entries in the ARP cache.
 108
 109   @param  This            A pointer to the EFI_ARP_PROTOCOL instance.
 110   @param  BySwAddress     Set to TRUE to look for matching software protocol addresses.
 111                           Set to FALSE to look for matching hardware protocol addresses.
 112   @param  AddressBuffer   Pointer to address buffer. Set to NULL to match all addresses.
 113   @param  EntryLength     The size of an entry in the entries buffer. To keep the
 114                           EFI_ARP_FIND_DATA structure properly aligned, this field
 115                           may be longer than sizeof(EFI_ARP_FIND_DATA) plus
 116                           the length of the software and hardware addresses.
 117   @param  EntryCount      The number of ARP cache entries that are found by the specified criteria.
 118   @param  Entries         Pointer to the buffer that will receive the ARP cache entries.
 119   @param  Refresh         Set to TRUE to refresh the timeout value of the matching ARP
 120                           cache entry.
 121
 122   @retval EFI_SUCCESS           The requested ARP cache entries were copied into the buffer.
 123   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 124   @retval EFI_NOT_FOUND         No matching entries were found.
 125   @retval EFI_NOT_STARTED       The ARP driver instance has not been configured.
 126
 127 **/
 128 typedef
 129 EFI_STATUS
 130 (EFIAPI *EFI_ARP_FIND) (
 131   IN EFI_ARP_PROTOCOL       *This,
 132   IN BOOLEAN                BySwAddress,
 133   IN VOID                   *AddressBuffer    OPTIONAL,
 134   OUT UINT32                *EntryLength      OPTIONAL,
 135   OUT UINT32                *EntryCount       OPTIONAL,
 136   OUT EFI_ARP_FIND_DATA     **Entries         OPTIONAL,
 137   IN BOOLEAN                Refresh
 138   )
 139 ;
 140
 141
 142 /**
 143   Removes entries from the ARP cache.
 144
 145   @param  This          A pointer to the EFI_ARP_PROTOCOL instance.
 146   @param  BySwAddress   Set to TRUE to delete matching protocol addresses.
 147                         Set to FALSE to delete matching hardware addresses.
 148   @param  AddressBuffer Pointer to the address buffer that is used as a key to look for the
 149                         cache entry. Set to NULL to delete all entries.
 150
 151   @retval EFI_SUCCESS           The entry was removed from the ARP cache.
 152   @retval EFI_INVALID_PARAMETER This is NULL.
 153   @retval EFI_NOT_FOUND         The specified deletion key was not found.
 154   @retval EFI_NOT_STARTED       The ARP driver instance has not been configured.
 155
 156 **/
 157 typedef
 158 EFI_STATUS
 159 (EFIAPI *EFI_ARP_DELETE) (
 160   IN EFI_ARP_PROTOCOL       *This,
 161   IN BOOLEAN                BySwAddress,
 162   IN VOID                   *AddressBuffer   OPTIONAL
 163   )
 164 ;
 165
 166 /**
 167   Removes all dynamic ARP cache entries that were added by this interface.
 168
 169   @param  This                   A pointer to the EFI_ARP_PROTOCOL instance.
 170
 171   @retval EFI_SUCCESS           The cache has been flushed.
 172   @retval EFI_INVALID_PARAMETER This is NULL.
 173   @retval EFI_NOT_FOUND         There are no matching dynamic cache entries.
 174   @retval EFI_NOT_STARTED       The ARP driver instance has not been configured.
 175
 176 **/
 177 typedef
 178 EFI_STATUS
 179 (EFIAPI *EFI_ARP_FLUSH) (
 180   IN EFI_ARP_PROTOCOL       *This
 181   )
 182 ;
 183
 184 /**
 185   Starts an ARP request session.
 186
 187   @param  This            A pointer to the EFI_ARP_PROTOCOL instance.
 188   @param  TargetSwAddress Pointer to the protocol address to resolve.
 189   @param  ResolvedEvent   Pointer to the event that will be signaled when the address is
 190                           resolved or some error occurs.
 191   @param  TargetHwAddress Pointer to the buffer for the resolved hardware address in
 192                           network byte order. The buffer must be large enough to hold the
 193                           resulting hardware address. TargetHwAddress must not be
 194                           NULL.
 195
 196   @retval EFI_SUCCESS           The data was copied from the ARP cache into the
 197                                 TargetHwAddress buffer.
 198   @retval EFI_INVALID_PARAMETER This or TargetHwAddress is NULL.
 199   @retval EFI_ACCESS_DENIED     The requested address is not present in the normal ARP cache but
 200                                 is present in the deny address list. Outgoing traffic to that address is
 201                                 forbidden.
 202   @retval EFI_NOT_STARTED       The ARP driver instance has not been configured.
 203   @retval EFI_NOT_READY         The request has been started and is not finished.
 204   @retval EFI_UNSUPPORTED       The requested conversion is not supported in this implementation or
 205                                 configuration.
 206
 207 **/
 208 typedef
 209 EFI_STATUS
 210 (EFIAPI *EFI_ARP_REQUEST) (
 211   IN EFI_ARP_PROTOCOL       *This,
 212   IN VOID                   *TargetSwAddress  OPTIONAL,
 213   IN EFI_EVENT              ResolvedEvent     OPTIONAL,
 214   OUT VOID                  *TargetHwAddress
 215   )
 216 ;
 217
 218 /**
 219   Cancels an ARP request session.
 220
 221   @param  This            A pointer to the EFI_ARP_PROTOCOL instance.
 222   @param  TargetSwAddress Pointer to the protocol address in previous request session.
 223   @param  ResolvedEvent   Pointer to the event that is used as the notification event in
 224                           previous request session.
 225
 226   @retval EFI_SUCCESS           The pending request session(s) is/are aborted and corresponding
 227                                 event(s) is/are signaled.
 228   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 229   @retval EFI_NOT_STARTED       The ARP driver instance has not been configured.
 230   @retval EFI_NOT_FOUND         The request is not issued by
 231                                 EFI_ARP_PROTOCOL.Request().
 232
 233 **/
 234 typedef
 235 EFI_STATUS
 236 (EFIAPI *EFI_ARP_CANCEL) (
 237   IN EFI_ARP_PROTOCOL       *This,
 238   IN VOID                   *TargetSwAddress  OPTIONAL,
 239   IN EFI_EVENT              ResolvedEvent     OPTIONAL
 240   )
 241 ;
 242
 243 struct _EFI_ARP_PROTOCOL {
 244   EFI_ARP_CONFIGURE         Configure;
 245   EFI_ARP_ADD               Add;
 246   EFI_ARP_FIND              Find;
 247   EFI_ARP_DELETE            Delete;
 248   EFI_ARP_FLUSH             Flush;
 249   EFI_ARP_REQUEST           Request;
 250   EFI_ARP_CANCEL            Cancel;
 251 };
 252
 253
 254 extern EFI_GUID gEfiArpServiceBindingProtocolGuid;
 255 extern EFI_GUID gEfiArpProtocolGuid;
 256
 257 #endif