modify coding style to pass ecc tool and provide comments that complied with Doxgen.

[mirror_edk2.git] / MdeModulePkg / Include / Library / IpIoLib.h

/** @file
  This library provides IpIo layer upon EFI IP4 Protocol.\r

Copyright (c) 2005 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution.  The full text of the license may be found at
http://opensource.org/licenses/bsd-license.php

THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

**/

#ifndef _IP_IO_H_
#define _IP_IO_H_

#include <PiDxe.h>
#include <Protocol/Ip4.h>\r
#include <Library/IpIoLib.h>\r
#include <Library/NetLib.h>

//\r
// type and code define for ICMP protocol error got\r
// from IP\r
//\r
#define ICMP_TYPE_UNREACH              3\r
#define ICMP_TYPE_TIMXCEED            11\r
#define ICMP_TYPE_PARAMPROB            12\r
#define ICMP_TYPE_SOURCEQUENCH         4\r
\r
#define ICMP_CODE_UNREACH_NET          0\r
#define ICMP_CODE_UNREACH_HOST         1\r
#define ICMP_CODE_UNREACH_PROTOCOL     2\r
#define ICMP_CODE_UNREACH_PORT         3\r
#define ICMP_CODE_UNREACH_NEEDFRAG     4\r
#define ICMP_CODE_UNREACH_SRCFAIL      5\r
#define ICMP_CODE_UNREACH_NET_UNKNOWN  6\r
#define ICMP_CODE_UNREACH_HOST_UNKNOWN 7\r
#define ICMP_CODE_UNREACH_ISOLATED     8\r
#define ICMP_CODE_UNREACH_NET_PROHIB   9\r
#define ICMP_CODE_UNREACH_HOST_PROHIB  10\r
#define ICMP_CODE_UNREACH_TOSNET       11\r
#define ICMP_CODE_UNREACH_TOSHOST      12\r
\r
//\r
// this error will be delivered to the\r
// listening transportation layer protocol\r
// consuming IpIO\r
//\r
typedef enum {\r
  ICMP_ERR_UNREACH_NET      = 0,\r
  ICMP_ERR_UNREACH_HOST,\r
  ICMP_ERR_UNREACH_PROTOCOL,\r
  ICMP_ERR_UNREACH_PORT,\r
  ICMP_ERR_MSGSIZE,\r
  ICMP_ERR_UNREACH_SRCFAIL,\r
  ICMP_ERR_TIMXCEED_INTRANS,\r
  ICMP_ERR_TIMXCEED_REASS,\r
  ICMP_ERR_QUENCH,\r
  ICMP_ERR_PARAMPROB\r
} ICMP_ERROR;\r
\r
typedef struct _ICMP_ERROR_INFO {\r
  BOOLEAN     IsHard;\r
  BOOLEAN     Notify;\r
} ICMP_ERROR_INFO;\r

#define EFI_IP4_HEADER_LEN(HdrPtr) ((HdrPtr)->HeaderLength << 2)

extern EFI_IP4_CONFIG_DATA  mIpIoDefaultIpConfigData;

typedef struct _EFI_NET_SESSION_DATA {
  IP4_ADDR        Source;
  IP4_ADDR        Dest;
  EFI_IP4_HEADER  *IpHdr;
} EFI_NET_SESSION_DATA;

typedef
VOID
(*PKT_RCVD_NOTIFY) (
  IN EFI_STATUS           Status,  // rcvd pkt result
  IN ICMP_ERROR           IcmpErr, // if Status == EFI_ICMP_ERROR, this
                                  // field is valid for user
  IN EFI_NET_SESSION_DATA *NetSession, // the communication point
  IN NET_BUF              *Pkt,    // packet received
  IN VOID                 *Context // the Context provided by user for recive data
  );

typedef
VOID
(*PKT_SENT_NOTIFY) (
  IN EFI_STATUS  Status,      // sent pkt result
  IN VOID        *Context,    // the context provided by user for sending data
  IN VOID        *Sender,     // the sender to be notified
  IN VOID        *NotifyData  // sent pkt related data to notify
  );

typedef struct _IP_IO {

  //
  // the node used to link this IpIo to the active IpIo list.
  //
  LIST_ENTRY                    Entry;

  // the list used to maintain the IP instance for different sending purpose.
  //
  LIST_ENTRY                    IpList;

  //
  // the ip instance consumed by this IP IO
  //
  EFI_HANDLE                    Controller;
  EFI_HANDLE                    Image;
  EFI_HANDLE                    ChildHandle;
  EFI_IP4_PROTOCOL              *Ip;
  BOOLEAN                       IsConfigured;

  //
  // some ip config data can be changed
  //
  UINT8                         Protocol;

  //
  // token and event used to get data from IP
  //
  EFI_IP4_COMPLETION_TOKEN      RcvToken;

  //
  // list entry used to link the token passed to IP_IO
  //
  LIST_ENTRY                    PendingSndList;

  //
  // User interface used to get notify from IP_IO
  //
  VOID                          *RcvdContext;
  VOID                          *SndContext;
  PKT_RCVD_NOTIFY               PktRcvdNotify;
  PKT_SENT_NOTIFY               PktSentNotify;
} IP_IO;

typedef struct _IP_IO_OPEN_DATA {
  EFI_IP4_CONFIG_DATA IpConfigData;
  VOID                *RcvdContext;
  VOID                *SndContext;
  PKT_RCVD_NOTIFY     PktRcvdNotify;
  PKT_SENT_NOTIFY     PktSentNotify;
} IP_IO_OPEN_DATA;

typedef struct _IP_IO_SEND_ENTRY {
  LIST_ENTRY                Entry;
  IP_IO                     *IpIo;
  VOID                      *Context;
  VOID                      *NotifyData;
  EFI_IP4_PROTOCOL          *Ip;
  NET_BUF                   *Pkt;
  EFI_IP4_COMPLETION_TOKEN  *SndToken;
} IP_IO_SEND_ENTRY;

typedef EFI_IP4_OVERRIDE_DATA IP_IO_OVERRIDE;

typedef struct _IP_IO_IP_INFO {
  IP4_ADDR                  Addr;
  IP4_ADDR                  SubnetMask;
  LIST_ENTRY                Entry;
  EFI_HANDLE                ChildHandle;
  EFI_IP4_PROTOCOL          *Ip;
  EFI_IP4_COMPLETION_TOKEN  DummyRcvToken;
  INTN                      RefCnt;
} IP_IO_IP_INFO;

/**\r
  Create a new IP_IO instance.\r
\r
  @param  Image                 The image handle of an IP_IO consumer protocol.\r
  @param  Controller            The controller handle of an IP_IO consumer protocol\r
                                installed on.\r
\r
  @return Pointer to a newly created IP_IO instance.\r
\r
**/
IP_IO *
EFIAPI
IpIoCreate (
  IN EFI_HANDLE Image,
  IN EFI_HANDLE Controller
  );

/**\r
  Destroy an IP_IO instance.\r
\r
  @param  IpIo                  Pointer to the IP_IO instance that needs to\r
                                destroy.\r
\r
  @retval EFI_SUCCESS           The IP_IO instance destroyed successfully.\r
  @retval other                 Error condition occurred.\r
\r
**/
EFI_STATUS
EFIAPI
IpIoDestroy (
  IN IP_IO *IpIo
  );

/**\r
  Stop an IP_IO instance.\r
\r
  @param  IpIo                  Pointer to the IP_IO instance that needs to stop.\r
\r
  @retval EFI_SUCCESS           The IP_IO instance stopped successfully.\r
  @retval other                 Error condition occurred.\r
\r
**/
EFI_STATUS
EFIAPI
IpIoStop (
  IN IP_IO *IpIo
  );

/**\r
  Open an IP_IO instance for use.\r
\r
  @param  IpIo                  Pointer to an IP_IO instance that needs to open.\r
  @param  OpenData              The configuration data for the IP_IO instance.\r
\r
  @retval EFI_SUCCESS           The IP_IO instance opened with OpenData\r
                                successfully.\r
  @retval other                 Error condition occurred.\r
\r
**/
EFI_STATUS
IpIoOpen (
  IN IP_IO           *IpIo,
  IN IP_IO_OPEN_DATA *OpenData
  );

/**\r
  Send out an IP packet.\r
\r
  @param  IpIo                  Pointer to an IP_IO instance used for sending IP\r
                                packet.\r
  @param  Pkt                   Pointer to the IP packet to be sent.\r
  @param  Sender                The IP protocol instance used for sending.\r
  @param  NotifyData\r
  @param  Dest                  The destination IP address to send this packet to.\r
  @param  OverrideData          The data to override some configuration of the IP\r
                                instance used for sending.\r
\r
  @retval EFI_SUCCESS           The operation is completed successfully.\r
  @retval EFI_NOT_STARTED       The IpIo is not configured.\r
  @retval EFI_OUT_OF_RESOURCES  Failed due to resource limit.\r
\r
**/
EFI_STATUS
EFIAPI
IpIoSend (
  IN IP_IO           *IpIo,
  IN NET_BUF         *Pkt,
  IN IP_IO_IP_INFO   *Sender,
  IN VOID            *Context    OPTIONAL,
  IN VOID            *NotifyData OPTIONAL,
  IN IP4_ADDR        Dest,
  IN IP_IO_OVERRIDE  *OverrideData
  );

/**\r
  Add a new IP instance for sending data.\r
\r
  @param  IpIo                  Pointer to a IP_IO instance to add a new IP\r
                                instance for sending purpose.\r
\r
  @return Pointer to the created IP_IO_IP_INFO structure, NULL is failed.\r
\r
**/
VOID
EFIAPI
IpIoCancelTxToken (
  IN IP_IO  *IpIo,
  IN VOID   *Packet
  );

/**\r
  Add a new IP instance for sending data.\r
\r
  @param  IpIo                  Pointer to a IP_IO instance to add a new IP\r
                                instance for sending purpose.\r
\r
  @return Pointer to the created IP_IO_IP_INFO structure, NULL is failed.\r
\r
**/
IP_IO_IP_INFO *
EFIAPI
IpIoAddIp (
  IN IP_IO  *IpIo
  );

/**\r
  Configure the IP instance of this IpInfo and start the receiving if Ip4ConfigData\r
  is not NULL.\r
\r
  @param  IpInfo                Pointer to the IP_IO_IP_INFO instance.\r
  @param  Ip4ConfigData         The IP4 configure data used to configure the ip\r
                                instance, if NULL the ip instance is reseted. If\r
                                UseDefaultAddress is set to TRUE, and the configure\r
                                operation succeeds, the default address information\r
                                is written back in this Ip4ConfigData.\r
\r
  @retval EFI_STATUS            The status returned by IP4->Configure or\r
                                IP4->Receive.\r
\r
**/
EFI_STATUS
EFIAPI
IpIoConfigIp (
  IN     IP_IO_IP_INFO        *IpInfo,
  IN OUT EFI_IP4_CONFIG_DATA  *Ip4ConfigData OPTIONAL
  );

/**\r
  Destroy an IP instance maintained in IpIo->IpList for\r
  sending purpose.\r
\r
  @param  IpIo                  Pointer to the IP_IO instance.\r
  @param  IpInfo                Pointer to the IpInfo to be removed.\r
\r
  @return None.\r
\r
**/
VOID
EFIAPI
IpIoRemoveIp (
  IN IP_IO            *IpIo,
  IN IP_IO_IP_INFO    *IpInfo
  );

/**\r
  Find the first IP protocol maintained in IpIo whose local\r
  address is the same with Src.\r
\r
  @param  IpIo                  Pointer to the pointer of the IP_IO instance.\r
  @param  Src                   The local IP address.\r
\r
  @return Pointer to the IP protocol can be used for sending purpose and its local\r
  @return address is the same with Src.\r
\r
**/
IP_IO_IP_INFO *
EFIAPI
IpIoFindSender (
  IN OUT IP_IO     **IpIo,
  IN     IP4_ADDR  Src
  );

/**\r
  Get the ICMP error map information, the ErrorStatus will be returned.\r
  The IsHard and Notify are optional. If they are not NULL, this rouine will\r
  fill them.\r
  We move IcmpErrMap[] to local variable to enable EBC build.\r
\r
  @param  IcmpError             IcmpError Type\r
  @param  IsHard                Whether it is a hard error\r
  @param  Notify                Whether it need to notify SockError\r
\r
  @return ICMP Error Status\r
\r
**/\r
EFI_STATUS
EFIAPI
IpIoGetIcmpErrStatus (
  IN  ICMP_ERROR  IcmpError,
  OUT BOOLEAN     *IsHard, OPTIONAL
  OUT BOOLEAN     *Notify OPTIONAL
  );

#endif