tyler.durden
/
audk
mirror of https://github.com/acidanthera/audk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add Dhcp6/Mtftp6/Udp6 three protocol's definitions into MdePkg to comply with UEFI2.3 spec. 

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@9087 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
eric_tian 2009-08-18 07:00:38 +00:00
parent 5e6f3ee295
commit 5d6a636c79
3 changed files with 2143 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

768
MdePkg/Include/Protocol/Dhcp6.h Normal file
View File

@ -0,0 +1,768 @@
/** @file
UEFI Dynamic Host Configuration Protocol 6 Definition, which is used to get IPv6
addresses and other configuration parameters from DHCPv6 servers.
Copyright (c) 2008 - 2009, 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 __EFI_DHCP6_PROTOCOL_H__
#define __EFI_DHCP6_PROTOCOL_H__
#define EFI_DHCP6_PROTOCOL_GUID \
{ \
0x87c8bad7, 0x595, 0x4053, {0x82, 0x97, 0xde, 0xde, 0x39, 0x5f, 0x5d, 0x5b } \
}
#define EFI_DHCP6_SERVICE_BINDING_PROTOCOL_GUID \
{ \
0x9fb9a8a1, 0x2f4a, 0x43a6, {0x88, 0x9c, 0xd0, 0xf7, 0xb6, 0xc4, 0x7a, 0xd5 } \
}
typedef struct _EFI_DHCP6_PROTOCOL EFI_DHCP6_PROTOCOL;
typedef enum {
///
/// The EFI DHCPv6 Protocol instance is configured, and start() needs
/// to be called
///
Dhcp6Init = 0x0,
///
/// A Solicit packet is sent out to discover DHCPv6 server, and the EFI
/// DHCPv6 Protocol instance is collecting Advertise packets.
///
Dhcp6Selecting = 0x1,
///
/// A Request is sent out to the DHCPv6 server, and the EFI DHCPv6
/// Protocol instance is waiting for Reply packet.
///
Dhcp6Requesting = 0x2,
///
/// A Decline packet is sent out to indicate one or more addresses of the
/// configured IA are in use by another node, and the EFI DHCPv6.
/// Protocol instance is waiting for Reply packet.
///
Dhcp6Declining = 0x3,
///
/// A Confirm packet is sent out to confirm the IPv6 addresses of the
/// configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet.
///
Dhcp6Confirming = 0x4,
///
/// A Release packet is sent out to release one or more IPv6 addresses of
/// the configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet.
///
Dhcp6Releasing = 0x5,
///
/// The DHCPv6 S.A.R.R process is completed for the configured IA.
///
Dhcp6Bound = 0x6,
///
/// A Renew packet is sent out to extend lifetime for the IPv6 addresses of
/// the configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet.
///
Dhcp6Renewing = 0x7,
///
/// A Rebind packet is sent out to extend lifetime for the IPv6 addresses of
/// the configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet.
///
Dhcp6Rebinding = 0x8
} EFI_DHCP6_STATE;
typedef enum {
///
/// A Solicit packet is about to be sent. The packet is passed to Dhcp6Callback and
/// can be modified or replaced in Dhcp6Callback.
///
Dhcp6SendSolicit = 0x0,
///
/// An Advertise packet is received and will be passed to Dhcp6Callback.
///
Dhcp6RcvdAdvertise = 0x1,
///
/// It is time for Dhcp6Callback to determine whether select the default Advertise
/// packet by RFC 3315 policy, or overwrite it by specific user policy.
///
Dhcp6SelectAdvertise = 0x2,
///
/// A Request packet is about to be sent. The packet is passed to Dhcp6Callback and
/// can be modified or replaced in Dhcp6Callback.
///
Dhcp6SendRequest = 0x3,
///
/// A Reply packet is received and will be passed to Dhcp6Callback.
///
Dhcp6RcvdReply = 0x4,
///
/// A Reconfigure packet is received and will be passed to Dhcp6Callback.
///
Dhcp6RcvdReconfigure = 0x5,
///
/// A Decline packet is about to be sent. The packet is passed to Dhcp6Callback and
/// can be modified or replaced in Dhcp6Callback.
///
Dhcp6SendDecline = 0x6,
///
/// A Confirm packet is about to be sent. The packet is passed to Dhcp6Callback and
/// can be modified or replaced in Dhcp6Callback.
///
Dhcp6SendConfirm = 0x7,
///
/// A Release packet is about to be sent. The packet is passed to Dhcp6Callback and
/// can be modified or replaced in Dhcp6Callback.
///
Dhcp6SendRelease = 0x8,
///
/// A Renew packet is about to be sent. The packet is passed to Dhcp6Callback and
/// can be modified or replaced in Dhcp6Callback.
///
Dhcp6EnterRenewing = 0x9,
///
/// A Rebind packet is about to be sent. The packet is passed to Dhcp6Callback and
/// can be modified or replaced in Dhcp6Callback.
///
Dhcp6EnterRebinding = 0xa
} EFI_DHCP6_EVENT;
///
/// An IA which carries assigned not temporary address.
///
#define EFI_DHCP6_IA_TYPE_NA 3
///
/// An IA which carries assigned temporary address.
///
#define EFI_DHCP6_IA_TYPE_TA 4
#pragma pack(1)
typedef struct {
///
/// The DHCPv6 option code.
///
UINT16 OpCode;
///
/// Length of the DHCPv6 option data. From the first byte to the last byte of the Data field.
///
UINT16 OpLen;
///
/// The data for the DHCPv6 option.
///
UINT8 Data[1];
} EFI_DHCP6_PACKET_OPTION;
typedef struct{
///
/// The DHCPv6 transaction ID.
///
UINT32 MessageType:8;
///
/// The DHCPv6 message type.
///
UINT32 TransactionId:24;
} EFI_DHCP6_HEADER;
typedef struct {
///
/// Size of the EFI_DHCP6_PACKET buffer.
///
UINT32 Size;
///
/// Length of the EFI_DHCP6_PACKET from the first byte of the Header field to the last
/// byte of the Option[] field.
///
UINT32 Length;
struct{
///
/// The DHCPv6 packet header.
///
EFI_DHCP6_HEADER Header;
///
/// Start of the DHCPv6 packed option data.
///
UINT8 Option[1];
} Dhcp6;
} EFI_DHCP6_PACKET;
#pragma pack()
typedef struct {
///
/// Length of DUID in octects.
///
UINT16 Length;
///
/// Array of DUID octects.
///
UINT8 Duid[1];
} EFI_DHCP6_DUID;
typedef struct {
///
/// Initial retransmission timeout.
///
UINT32 Irt;
///
/// Maximum retransmission count for one packet. If Mrc is zero, there¡¯s no upper limit
/// for retransmission count.
///
UINT32 Mrc;
///
/// Maximum retransmission timeout for each retry. It¡¯s the upper bound of the number of
/// retransmission timeout. If Mrt is zero, there is no upper limit for retransmission
/// timeout.
///
UINT32 Mrt;
///
/// Maximum retransmission duration for one packet. It¡¯s the upper bound of the numbers
/// the client may retransmit a message. If Mrd is zero, there¡¯s no upper limit for
/// retransmission duration.
///
UINT32 Mrd;
} EFI_DHCP6_RETRANSMISSION;
typedef struct {
///
/// The IPv6 address.
///
EFI_IPv6_ADDRESS IpAddress;
///
/// The preferred lifetime in unit of seconds for the IPv6 address.
///
UINT32 PreferredLifetime;
///
/// The valid lifetime in unit of seconds for the IPv6 address.
///
UINT32 ValidLifetime;
} EFI_DHCP6_IA_ADDRESS;
typedef struct {
UINT16 Type; ///< Type for an IA.
UINT32 IaId; ///< The identifier for an IA.
} EFI_DHCP6_IA_DESCRIPTOR;
typedef struct {
///
/// The descriptor for IA.
///
EFI_DHCP6_IA_DESCRIPTOR Descriptor;
///
/// The state of the configured IA.
///
EFI_DHCP6_STATE State;
///
/// Pointer to the cached latest Reply packet. May be NULL if no packet is cached.
///
EFI_DHCP6_PACKET *ReplyPacket;
///
/// Number of IPv6 addresses of the configured IA.
///
UINT32 IaAddressCount;
///
/// List of the IPv6 addresses of the configured IA. When the state of the configured IA is
/// in Dhcp6Bound, Dhcp6Renewing and Dhcp6Rebinding, the IPv6 addresses are usable.
///
EFI_DHCP6_IA_ADDRESS IaAddress[1];
} EFI_DHCP6_IA;
typedef struct {
///
/// Pointer to the DHCPv6 unique identifier. The caller is responsible for freeing this buffer.
///
EFI_DHCP6_DUID *ClientId;
///
/// Pointer to the configured IA of current instance. The caller can free this buffer after
/// using it.
///
EFI_DHCP6_IA *Ia;
} EFI_DHCP6_MODE_DATA;
/**
EFI_DHCP6_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol instance to
intercept events that occurs in the DHCPv6 S.A.R.R process.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this
callback function.
@param[in] Context Pointer to the context that is initialized by EFI_DHCP6_PROTOCOL.Configure().
@param[in] CurrentState The current state of the configured IA.
@param[in] Dhcp6Event The event that occurs in the current state, which usually means a state transition.
@param[in] Packet Pointer to the DHCPv6 packet that is about to be sent or has been received.
The EFI DHCPv6 Protocol instance is responsible for freeing the buffer.
@param[out] NewPacket Pointer to the new DHCPv6 packet to overwrite the Packet. NewPacket can not
share the buffer with Packet. If *NewPacket is not NULL, the EFI DHCPv6
Protocol instance is responsible for freeing the buffer.
@retval EFI_SUCCESS Tell the EFI DHCPv6 Protocol instance to continue the DHCPv6 S.A.R.R process.
@retval EFI_ABORTED Tell the EFI DHCPv6 Protocol instance to abort the DHCPv6 S.A.R.R process,
and the state of the configured IA will be transferred to Dhcp6Init.
**/
typedef
EFI_STATUS
(*EFI_DHCP6_CALLBACK)(
IN EFI_DHCP6_PROTOCOL *This,
IN VOID *Context,
IN EFI_DHCP6_STATE CurrentState,
IN EFI_DHCP6_EVENT Dhcp6Event,
IN EFI_DHCP6_PACKET *Packet,
OUT EFI_DHCP6_PACKET **NewPacket OPTIONAL
);
typedef struct {
///
/// The callback function is to intercept various events that occur in the DHCPv6 S.A.R.R
/// process. Set to NULL to ignore all those events.
///
EFI_DHCP6_CALLBACK Dhcp6Callback;
///
/// Pointer to the context that will be passed to Dhcp6Callback.
///
VOID *CallbackContext;
///
/// Number of the DHCPv6 options in the OptionList.
///
UINT32 OptionCount;
///
/// List of the DHCPv6 options to be included in Solicit and Request packet. The buffer
/// can be freed after EFI_DHCP6_PROTOCOL.Configure() returns. Ignored if
/// OptionCount is zero. OptionList should not contain Client Identifier option
/// and any IA option, which will be appended by EFI DHCPv6 Protocol instance
/// automatically.
///
EFI_DHCP6_PACKET_OPTION **OptionList;
///
/// The descriptor for the IA of the EFI DHCPv6 Protocol instance.
///
EFI_DHCP6_IA_DESCRIPTOR IaDescriptor;
///
/// If not NULL, the event will be signaled when any IPv6 address information of the
/// configured IA is updated, including IPv6 address, preferred lifetime and valid
/// lifetime, or the DHCPv6 S.A.R.R process fails. Otherwise, Start(),
/// renewrebind(), decline(), release() and stop() will be blocking
/// operations, and they will wait for the exchange process completion or failure.
///
EFI_EVENT IaInfoEvent;
///
/// If TRUE, the EFI DHCPv6 Protocol instance is willing to accept Reconfigure packet.
/// Otherwise, it will ignore it. Reconfigure Accept option can not be specified through
/// OptionList parameter.
///
BOOLEAN ReconfigureAccept;
///
/// If TRUE, the EFI DHCPv6 Protocol instance will send Solicit packet with Rapid
/// Commit option. Otherwise, Rapid Commit option will not be included in Solicit
/// packet. Rapid Commit option can not be specified through OptionList parameter.
///
BOOLEAN RapidCommit;
///
/// Parameter to control Solicit packet retransmission behavior. The
/// buffer can be freed after EFI_DHCP6_PROTOCOL.Configure() returns.
///
EFI_DHCP6_RETRANSMISSION *SolicitRetransmission;
} EFI_DHCP6_CONFIG_DATA;
/**
EFI_DHCP6_INFO_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol
instance to intercept events that occurs in the DHCPv6 Information Request exchange process.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this
callback function.
@param[in] Context Pointer to the context that is initialized in the EFI_DHCP6_PROTOCOL.InfoRequest().
@param[in] Packet Pointer to Reply packet that has been received. The EFI DHCPv6 Protocol instance is
responsible for freeing the buffer.
@retval EFI_SUCCESS Tell the EFI DHCPv6 Protocol instance to finish Information Request exchange process.
@retval EFI_NOT_READY Tell the EFI DHCPv6 Protocol instance to continue Information Request exchange process.
@retval EFI_ABORTED Tell the EFI DHCPv6 Protocol instance to abort the Information Request exchange process.
**/
typedef
EFI_STATUS
(*EFI_DHCP6_INFO_CALLBACK)(
IN EFI_DHCP6_PROTOCOL *This,
IN VOID *Context,
IN EFI_DHCP6_PACKET *Packet
);
/**
Retrieve the current operating mode data and configuration data for the EFI DHCPv6 Protocol instance.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance.
@param[out] Dhcp6ModeData Pointer to the DHCPv6 mode data structure. The caller is responsible for freeing this
structure and each reference buffer.
@param[out] Dhcp6ConfigData Pointer to the DHCPv6 configuration data structure. The caller is responsible for
freeing this structure and each reference buffer.
@retval EFI_SUCCESS The mode data was returned.
@retval EFI_ACCESS_DENIED The EFI DHCPv6 Protocol instance has not been configured when Dhcp6ConfigData is not NULL.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
- This is NULL.
- Both Dhcp6ConfigData and Dhcp6ModeData are NULL.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_GET_MODE_DATA)(
IN EFI_DHCP6_PROTOCOL *This,
OUT EFI_DHCP6_MODE_DATA *Dhcp6ModeData OPTIONAL,
OUT EFI_DHCP6_CONFIG_DATA *Dhcp6ConfigData OPTIONAL
);
/**
Initialize or clean up the configuration data for the EFI DHCPv6 Protocol instance.
The Configure() function is used to initialize or clean up the configuration data of the EFI
DHCPv6 Protocol instance.
- When Dhcp6CfgData is not NULL and Configure() is called successfully, the
configuration data will be initialized in the EFI DHCPv6 Protocol instance and the state of the
configured IA will be transferred into Dhcp6Init.
- When Dhcp6CfgData is NULL and Configure() is called successfully, the configuration
data will be cleaned up and no IA will be associated with the EFI DHCPv6 Protocol instance.
To update the configuration data for an EFI DCHPv6 Protocol instance, the original data must be
cleaned up before setting the new configuration data.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance.
@param[in] Dhcp6CfgData Pointer to the DHCPv6 configuration data structure.
@retval EFI_SUCCESS The mode data was returned.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE
- This is NULL.
- OptionCount > 0 and OptionList is NULL.
- OptionList is not NULL, and Client Id option, Reconfigure Accept option,
Rapid Commit option or any IA option is specified in the OptionList.
- IaDescriptor.Type is neither EFI_DHCP6_IA_TYPE_NA nor EFI_DHCP6_IA_TYPE_NA.
- IaDescriptor is not unique.
- Both IaInfoEvent and SolicitRetransimssion are NULL.
- SolicitRetransmission is not NULL, and both SolicitRetransimssion->Mrc and
SolicitRetransmission->Mrd are zero.
@retval EFI_ACCESS_DENIED The EFI DHCPv6 Protocol instance has been already configured
when Dhcp6CfgData is not NULL.
The EFI DHCPv6 Protocol instance has already started the
DHCPv6 S.A.R.R when Dhcp6CfgData is NULL.
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_CONFIGURE)(
IN EFI_DHCP6_PROTOCOL *This,
IN EFI_DHCP6_CONFIG_DATA *Dhcp6CfgData OPTIONAL
);
/**
Start the DHCPv6 S.A.R.R process.
The Start() function starts the DHCPv6 S.A.R.R process. This function can be called only when
the state of the configured IA is in the Dhcp6Init state. If the DHCPv6 S.A.R.R process completes
successfully, the state of the configured IA will be transferred through Dhcp6Selecting and
Dhcp6Requesting to Dhcp6Bound state. The update of the IPv6 addresses will be notified through
EFI_DHCP6_CONFIG_DATA.IaInfoEvent. At the time when each event occurs in this process, the
callback function set by EFI_DHCP6_PROTOCOL.Configure() will be called and the user can take
this opportunity to control the process. If EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the
Start() function call is a blocking operation. It will return after the DHCPv6 S.A.R.R process
completes or aborted by users. If the process is aborted by system or network error, the state of
the configured IA will be transferred to Dhcp6Init. The Start() function can be called again to
restart the process.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance.
@retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6
address has been bound to the configured IA when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL.
The DHCPv6 S.A.R.R process is started when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL.
@retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn¡¯t been configured.
@retval EFI_INVALID_PARAMETER This is NULL.
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
@retval EFI_ALREADY_STARTED The DHCPv6 S.A.R.R process has already started.
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
@retval EFI_NO_RESPONSE The DHCPv6 S.A.R.R process failed because of no response.
@retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the
DHCPv6 S.A.R.R process.
@retval EFI_ABORTED The DHCPv6 S.A.R.R process aborted by user.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_START)(
IN EFI_DHCP6_PROTOCOL *This
);
/**
Request configuration information without the assignment of any IA addresses of the client.
The InfoRequest() function is used to request configuration information without the assignment
of any IPv6 address of the client. Client sends out Information Request packet to obtain
the required configuration information, and DHCPv6 server responds with Reply packet containing
the information for the client. The received Reply packet will be passed to the user by
ReplyCallback function. If user returns EFI_NOT_READY from ReplyCallback, the EFI DHCPv6
Protocol instance will continue to receive other Reply packets unless timeout according to
the Retransmission parameter. Otherwise, the Information Request exchange process will be
finished successfully if user returns EFI_SUCCESS from ReplyCallback.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance.
@param[in] SendClientId If TRUE, the EFI DHCPv6 Protocol instance will build Client
Identifier option and include it into Information Request
packet. If FALSE, Client Identifier option will not be included.
Client Identifier option can not be specified through OptionList
parameter.
@param[in] OptionRequest Pointer to the Option Request option in the Information Request
packet. Option Request option can not be specified through
OptionList parameter.
@param[in] OptionCount Number of options in OptionList.
@param[in] OptionList List of other DHCPv6 options. These options will be appended
to the Option Request option. The caller is responsible for
freeing this buffer. Type is defined in EFI_DHCP6_PROTOCOL.GetModeData().
@param[in] Retransmission Parameter to control Information Request packet retransmission
behavior. The buffer can be freed after EFI_DHCP6_PROTOCOL.InfoRequest()
returns.
@param[in] TimeoutEvent If not NULL, this event is signaled when the information request
exchange aborted because of no response. If NULL, the function
call is a blocking operation; and it will return after the
information-request exchange process finish or aborted by users.
@param[in] ReplyCallback The callback function is to intercept various events that occur
in the Information Request exchange process. It should not be
set to NULL.
@param[in] CallbackContext Pointer to the context that will be passed to ReplyCallback.
@retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6
@retval EFI_SUCCESS The DHCPv6 information request exchange process completed
when TimeoutEvent is NULL. Information Request packet has been
sent to DHCPv6 server when TimeoutEvent is not NULL.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
- This is NULL.
- OptionRequest is NULL or OptionRequest->OpCode is invalid.
- OptionCount > 0 and OptionList is NULL.
- OptionList is not NULL, and Client Identify option or
Option Request option is specified in the OptionList.
- Retransimssion is NULL.
- Both Retransimssion->Mrc and Retransmission->Mrd are zero.
- ReplyCallback is NULL.
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
@retval EFI_NO_RESPONSE The DHCPv6 information request exchange process failed
because of no response, or not all requested-options are
responded by DHCPv6 servers when Timeout happened.
@retval EFI_ABORTED The DHCPv6 information request exchange process aborted by user.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_INFO_REQUEST)(
IN EFI_DHCP6_PROTOCOL *This,
IN BOOLEAN SendClientId,
IN EFI_DHCP6_PACKET_OPTION *OptionRequest,
IN UINT32 OptionCount,
IN EFI_DHCP6_PACKET_OPTION *OptionList[] OPTIONAL,
IN EFI_DHCP6_RETRANSMISSION *Retransmission,
IN EFI_EVENT TimeoutEvent OPTIONAL,
IN EFI_DHCP6_INFO_CALLBACK ReplyCallback,
IN VOID *CallbackContext OPTIONAL
);
/**
Manually extend the valid and preferred lifetimes for the IPv6 addresses of the configured
IA and update other configuration parameters by sending Renew or Rebind packet.
The RenewRebind() function is used to manually extend the valid and preferred lifetimes for the
IPv6 addresses of the configured IA and update other configuration parameters by sending Renew or
Rebind packet.
- When RebindRequest is FALSE and the state of the configured IA is Dhcp6Bound, it
will send Renew packet to the previously DHCPv6 server and transfer the state of the configured
IA to Dhcp6Renewing. If valid Reply packet received, the state transfers to Dhcp6Bound
and the valid and preferred timer restarts. If fails, the state transfers to Dhcp6Bound but the
timer continues.
- When RebindRequest is TRUE and the state of the configured IA is Dhcp6Bound, it will
send Rebind packet. If valid Reply packet received, the state transfers to Dhcp6Bound and the
valid and preferred timer restarts. If fails, the state transfers to Dhcp6Init and the IA can¡¯t
be used.
@param[in] This Pointer to the EFI_DHCP4_PROTOCOL instance.
@param[in] RebindRequest If TRUE, it will send Rebind packet and enter the Dhcp6Rebinding state.
Otherwise, it will send Renew packet and enter the Dhcp6Renewing state.
@retval EFI_SUCCESS The DHCPv6 renew/rebind exchange process has completed and at
least one IPv6 address of the configured IA has been bound again
when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL.
The EFI DHCPv6 Protocol instance has sent Renew or Rebind packet
when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL.
@retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn¡¯t been configured, or the state
of the configured IA is not in Dhcp6Bound.
@retval EFI_ALREADY_STARTED The state of the configured IA has already entered Dhcp6Renewing
when RebindRequest is FALSE.
The state of the configured IA has already entered Dhcp6Rebinding
when RebindRequest is TRUE.
@retval EFI_INVALID_PARAMETER This is NULL.
@retval EFI_DEVICE_ERROR An unexpected system or system error occurred.
@retval EFI_NO_RESPONSE The DHCPv6 renew/rebind exchange process failed because of no response.
@retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the DHCPv6
renew/rebind exchange process.
@retval EFI_ABORTED The DHCPv6 renew/rebind exchange process aborted by user.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_RENEW_REBIND)(
IN EFI_DHCP6_PROTOCOL *This,
IN BOOLEAN RebindRequest
);
/**
Inform that one or more IPv6 addresses assigned by a server are already in use by
another node.
The Decline() function is used to manually decline the assignment of IPv6 addresses, which
have been already used by another node. If all IPv6 addresses of the configured IA are declined
through this function, the state of the IA will switch through Dhcp6Declining to Dhcp6Init,
otherwise, the state of the IA will restore to Dhcp6Bound after the declining process. The
Decline() can only be called when the IA is in Dhcp6Bound state. If the
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, this function is a blocking operation. It
will return after the declining process finishes, or aborted by user.
@param[in] This Pointer to the EFI_DHCP4_PROTOCOL instance.
@param[in] AddressCount Number of declining IPv6 addresses.
@param[in] Addresses Pointer to the buffer stored all the declining IPv6 addresses.
@retval EFI_SUCCESS The DHCPv6 decline exchange process has completed when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL.
The EFI DHCPv6 Protocol instance has sent Decline packet when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE
- This is NULL.
- AddressCount is zero or Addresses is NULL.
@retval EFI_NOT_FOUND Any specified IPv6 address is not correlated with the configured IA
for this instance.
@retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn¡¯t been configured, or the
state of the configured IA is not in Dhcp6Bound.
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
@retval EFI_ABORTED The DHCPv6 decline exchange process aborted by user.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_DECLINE)(
IN EFI_DHCP6_PROTOCOL *This,
IN UINT32 AddressCount,
IN EFI_IPv6_ADDRESS *Addresses
);
/**
Release one or more IPv6 addresses associated with the configured IA for current instance.
The Release() function is used to manually release the one or more IPv6 address. If AddressCount
is zero, it will release all IPv6 addresses of the configured IA. If all IPv6 addresses of the IA
are released through this function, the state of the IA will switch through Dhcp6Releasing to
Dhcp6Init, otherwise, the state of the IA will restore to Dhcp6Bound after the releasing process.
The Release() can only be called when the IA is in Dhcp6Bound state. If the
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the function is a blocking operation. It will return
after the releasing process finishes, or aborted by user.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance.
@param[in] AddressCount Number of releasing IPv6 addresses.
@param[in] Addresses Pointer to the buffer stored all the releasing IPv6 addresses.
Ignored if AddressCount is zero.
@retval EFI_SUCCESS The DHCPv6 release exchange process has completed when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL.
The EFI DHCPv6 Protocol instance has sent Release packet when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE
- This is NULL.
- AddressCount is not zero or Addresses is NULL.
@retval EFI_NOT_FOUND Any specified IPv6 address is not correlated with the configured
IA for this instance.
@retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn¡¯t been configured, or the
state of the configured IA is not in Dhcp6Bound.
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
@retval EFI_ABORTED The DHCPv6 release exchange process aborted by user.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_RELEASE)(
IN EFI_DHCP6_PROTOCOL *This,
IN UINT32 AddressCount,
IN EFI_IPv6_ADDRESS *Addresses
);
/**
Stop the DHCPv6 S.A.R.R process.
The Stop() function is used to stop the DHCPv6 S.A.R.R process. If this function is called
successfully, all the IPv6 addresses of the configured IA will be released and the state of
the configured IA will be transferred to Dhcp6Init.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance.
@retval EFI_SUCCESS The DHCPv6 S.A.R.R process has been stopped when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL.
The EFI DHCPv6 Protocol instance has sent Release packet if
need release or has been stopped if needn¡¯t, when
EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL.
@retval EFI_INVALID_PARAMETER This is NULL.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_STOP)(
IN EFI_DHCP6_PROTOCOL *This
);
/**
Parse the option data in the DHCPv6 packet.
The Parse() function is used to retrieve the option list in the DHCPv6 packet.
@param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance.
@param[in] Packet Pointer to packet to be parsed.
@param[in] OptionCount On input, the number of entries in the PacketOptionList.
On output, the number of DHCPv6 options in the Packet.
@param[in] PacketOptionList List of pointers to the DHCPv6 options in the Packet.
The OpCode and OpLen in EFI_DHCP6_PACKET_OPTION are
both stored in network byte order.
@retval EFI_SUCCESS The packet was successfully parsed.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE
- This is NULL.
- Packet is NULL.
- Packet is not a well-formed DHCPv6 packet.
- OptionCount is NULL.
- *OptionCount is not zero and PacketOptionList is NULL.
@retval EFI_BUFFER_TOO_SMALL *OptionCount is smaller than the number of options that were
found in the Packet.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_DHCP6_PARSE)(
IN EFI_DHCP6_PROTOCOL *This,
IN EFI_DHCP6_PACKET *Packet,
IN OUT UINT32 *OptionCount,
OUT EFI_DHCP6_PACKET_OPTION *PacketOptionList[] OPTIONAL
);
///
/// The EFI DHCPv6 Protocol is used to get IPv6 addresses and other configuration parameters
/// from DHCPv6 servers.
///
struct _EFI_DHCP6_PROTOCOL {
EFI_DHCP6_GET_MODE_DATA GetModeData;
EFI_DHCP6_CONFIGURE Configure;
EFI_DHCP6_START Start;
EFI_DHCP6_INFO_REQUEST InfoRequest;
EFI_DHCP6_RENEW_REBIND RenewRebind;
EFI_DHCP6_DECLINE Decline;
EFI_DHCP6_RELEASE Release;
EFI_DHCP6_STOP Stop;
EFI_DHCP6_PARSE Parse;
};
extern EFI_GUID gEfiDhcp6ProtocolGuid;
extern EFI_GUID gEfiDhcp6ServiceBindingProtocolGuid;
#endif

806
MdePkg/Include/Protocol/Mtftp6.h Normal file
View File

@ -0,0 +1,806 @@
/** @file
UEFI Multicast Trivial File Tranfer Protocol v6 Definition, which is built upon
the EFI UDPv6 Protocol and provides basic services for client-side unicast and/or
multicast TFTP operations.
Copyright (c) 2008 - 2009, 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 __EFI_MTFTP6_PROTOCOL_H__
#define __EFI_MTFTP6_PROTOCOL_H__
#define EFI_MTFTP6_SERVICE_BINDING_PROTOCOL_GUID \
{ \
0xd9760ff3, 0x3cca, 0x4267, {0x80, 0xf9, 0x75, 0x27, 0xfa, 0xfa, 0x42, 0x23 } \
}
#define EFI_MTFTP6_PROTOCOL_GUID \
{ \
0xbf0a78ba, 0xec29, 0x49cf, {0xa1, 0xc9, 0x7a, 0xe5, 0x4e, 0xab, 0x6a, 0x51 } \
}
typedef struct _EFI_MTFTP6_PROTOCOL EFI_MTFTP6_PROTOCOL;
typedef struct _EFI_MTFTP6_TOKEN EFI_MTFTP6_TOKEN;
///
/// MTFTP Packet OpCodes
///@{
#define EFI_MTFTP6_OPCODE_RRQ 1 ///< The MTFTPv6 packet is a read request.
#define EFI_MTFTP6_OPCODE_WRQ 2 ///< The MTFTPv6 packet is a write request.
#define EFI_MTFTP6_OPCODE_DATA 3 ///< The MTFTPv6 packet is a data packet.
#define EFI_MTFTP6_OPCODE_ACK 4 ///< The MTFTPv6 packet is an acknowledgement packet.
#define EFI_MTFTP6_OPCODE_ERROR 5 ///< The MTFTPv6 packet is an error packet.
#define EFI_MTFTP6_OPCODE_OACK 6 ///< The MTFTPv6 packet is an option acknowledgement packet.
#define EFI_MTFTP6_OPCODE_DIR 7 ///< The MTFTPv6 packet is a directory query packet.
#define EFI_MTFTP6_OPCODE_DATA8 8 ///< The MTFTPv6 packet is a data packet with a big block number.
#define EFI_MTFTP6_OPCODE_ACK8 9 ///< The MTFTPv6 packet is an acknowledgement packet with a big block number.
///@}
///
/// MTFTP ERROR Packet ErrorCodes
///@{
///
/// The error code is not defined. See the error message in the packet (if any) for details.
///
#define EFI_MTFTP6_ERRORCODE_NOT_DEFINED 0
///
/// The file was not found.
///
#define EFI_MTFTP6_ERRORCODE_FILE_NOT_FOUND 1
///
/// There was an access violation.
///
#define EFI_MTFTP6_ERRORCODE_ACCESS_VIOLATION 2
///
/// The disk was full or its allocation was exceeded.
///
#define EFI_MTFTP6_ERRORCODE_DISK_FULL 3
///
/// The MTFTPv6 operation was illegal.
///
#define EFI_MTFTP6_ERRORCODE_ILLEGAL_OPERATION 6
///
/// The transfer ID is unknown.
///
#define EFI_MTFTP6_ERRORCODE_UNKNOWN_TRANSFER_ID 5
///
/// The file already exists.
///
#define EFI_MTFTP6_ERRORCODE_FILE_ALREADY_EXISTS 6
///
/// There is no such user.
///
#define EFI_MTFTP6_ERRORCODE_NO_SUCH_USER 7
///
/// The request has been denied due to option negotiation.
///
#define EFI_MTFTP6_ERRORCODE_REQUEST_DENIED 8
///@}
#pragma pack(1)
///
/// EFI_MTFTP6_REQ_HEADER
///
typedef struct {
///
/// For this packet type, OpCode = EFI_MTFTP6_OPCODE_RRQ for a read request
/// or OpCode = EFI_MTFTP6_OPCODE_WRQ for a write request.
///
UINT16 OpCode;
///
/// The file name to be downloaded or uploaded.
///
UINT8 Filename[1];
} EFI_MTFTP6_REQ_HEADER;
///
/// EFI_MTFTP6_OACK_HEADER
///
typedef struct {
///
/// For this packet type, OpCode = EFI_MTFTP6_OPCODE_OACK.
///
UINT16 OpCode;
///
/// The option strings in the option acknowledgement packet.
///
UINT8 Data[1];
} EFI_MTFTP6_OACK_HEADER;
///
/// EFI_MTFTP6_DATA_HEADER
///
typedef struct {
///
/// For this packet type, OpCode = EFI_MTFTP6_OPCODE_DATA.
///
UINT16 OpCode;
///
/// Block number of this data packet.
///
UINT16 Block;
///
/// The content of this data packet.
///
UINT8 Data[1];
} EFI_MTFTP6_DATA_HEADER;
///
/// EFI_MTFTP6_ACK_HEADER
///
typedef struct {
///
/// For this packet type, OpCode = EFI_MTFTP6_OPCODE_ACK.
///
UINT16 OpCode;
///
/// The block number of the data packet that is being acknowledged.
///
UINT16 Block[1];
} EFI_MTFTP6_ACK_HEADER;
///
/// EFI_MTFTP6_DATA8_HEADER
///
typedef struct {
///
/// For this packet type, OpCode = EFI_MTFTP6_OPCODE_DATA8.
///
UINT16 OpCode;
///
/// The block number of data packet.
///
UINT64 Block;
///
/// The content of this data packet.
///
UINT8 Data[1];
} EFI_MTFTP6_DATA8_HEADER;
///
/// EFI_MTFTP6_ACK8_HEADER
///
typedef struct {
///
/// For this packet type, OpCode = EFI_MTFTP6_OPCODE_ACK8.
///
UINT16 OpCode;
///
/// The block number of the data packet that is being acknowledged.
///
UINT64 Block[1];
} EFI_MTFTP6_ACK8_HEADER;
///
/// EFI_MTFTP6_ERROR_HEADER
///
typedef struct {
///
/// For this packet type, OpCode = EFI_MTFTP6_OPCODE_ERROR.
///
UINT16 OpCode;
///
/// The error number as defined by the MTFTPv6 packet error codes.
///
UINT16 ErrorCode;
///
/// Error message string.
///
UINT8 ErrorMessage[1];
} EFI_MTFTP6_ERROR_HEADER;
///
/// EFI_MTFTP6_PACKET
///
typedef union {
UINT16 OpCode; ///< Type of packets as defined by the MTFTPv6 packet opcodes.
EFI_MTFTP6_REQ_HEADER Rrq; ///< Read request packet header.
EFI_MTFTP6_REQ_HEADER Wrq; ///< write request packet header.
EFI_MTFTP6_OACK_HEADER Oack; ///< Option acknowledge packet header.
EFI_MTFTP6_DATA_HEADER Data; ///< Data packet header.
EFI_MTFTP6_ACK_HEADER Ack; ///< Acknowledgement packet header.
EFI_MTFTP6_DATA8_HEADER Data8; ///< Data packet header with big block number.
EFI_MTFTP6_ACK8_HEADER Ack8; ///< Acknowledgement header with big block number.
EFI_MTFTP6_ERROR_HEADER Error; ///< Error packet header.
} EFI_MTFTP6_PACKET;
#pragma pack()
///
/// EFI_MTFTP6_CONFIG_DATA
///
typedef struct {
///
/// The local IP address to use. Set to zero to let the underlying IPv6
/// driver choose a source address. If not zero it must be one of the
/// configured IP addresses in the underlying IPv6 driver.
///
EFI_IPv6_ADDRESS StationIp;
///
/// Local port number. Set to zero to use the automatically assigned port number.
///
UINT16 LocalPort;
///
/// The IP address of the MTFTPv6 server.
///
EFI_IPv6_ADDRESS ServerIp;
///
/// The initial MTFTPv6 server port number. Request packets are
/// sent to this port. This number is almost always 69 and using zero
/// defaults to 69.
UINT16 InitialServerPort;
///
/// The number of times to transmit MTFTPv6 request packets and wait for a response.
///
UINT16 TryCount;
///
/// The number of seconds to wait for a response after sending the MTFTPv6 request packet.
///
UINT16 TimeoutValue;
} EFI_MTFTP6_CONFIG_DATA;
///
/// EFI_MTFTP6_MODE_DATA
///
typedef struct {
///
/// The configuration data of this instance.
///
EFI_MTFTP6_CONFIG_DATA ConfigData;
///
/// The number of option strings in the following SupportedOptions array.
///
UINT8 SupportedOptionCount;
///
/// An array of option strings that are recognized and supported by
/// this EFI MTFTPv6 Protocol driver implementation. The buffer is
/// read only to the caller and the caller should NOT free the buffer.
///
UINT8 **SupportedOptions;
} EFI_MTFTP6_MODE_DATA;
///
/// EFI_MTFTP_OVERRIDE_DATA
///
typedef struct {
///
/// IP address of the MTFTPv6 server. If set to all zero, the value that
/// was set by the EFI_MTFTP6_PROTOCOL.Configure() function will be used.
///
EFI_IPv6_ADDRESS ServerIp;
///
/// MTFTPv6 server port number. If set to zero, it will use the value
/// that was set by the EFI_MTFTP6_PROTOCOL.Configure() function.
///
UINT16 ServerPort;
///
/// Number of times to transmit MTFTPv6 request packets and wait
/// for a response. If set to zero, the value that was set by
/// theEFI_MTFTP6_PROTOCOL.Configure() function will be used.
///
UINT16 TryCount;
///
/// Number of seconds to wait for a response after sending the
/// MTFTPv6 request packet. If set to zero, the value that was set by
/// the EFI_MTFTP6_PROTOCOL.Configure() function will be used.
///
UINT16 TimeoutValue;
} EFI_MTFTP6_OVERRIDE_DATA;
///
/// EFI_MTFTP6_OPTION
///
typedef struct {
UINT8 *OptionStr; ///< Pointer to the ASCIIZ MTFTPv6 option string.
UINT8 *ValueStr; ///< Pointer to the ASCIIZ MTFTPv6 value string.
} EFI_MTFTP6_OPTION;
/**
EFI_MTFTP6_TIMEOUT_CALLBACK is a callback function that the caller provides to capture the
timeout event in the EFI_MTFTP6_PROTOCOL.ReadFile(), EFI_MTFTP6_PROTOCOL.WriteFile() or
EFI_MTFTP6_PROTOCOL.ReadDirectory() functions.
Whenever a timeout occurs, the EFI MTFTPv6 Protocol driver will call the EFI_MTFTP6_TIMEOUT_CALLBACK
function to notify the caller of the timeout event. Any status code other than EFI_SUCCESS
that is returned from this function will abort the current download process.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] Token The token that the caller provided in the EFI_MTFTP6_PROTOCOl.ReadFile(),
WriteFile() or ReadDirectory() function.
@param[in] PacketLen Indicates the length of the packet.
@param[in] Packet Pointer to an MTFTPv6 packet.
@retval EFI_SUCCESS Operation sucess.
@retval Others Aborts session.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_CHECK_PACKET)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_TOKEN *Token,
IN UINT16 PacketLen,
IN EFI_MTFTP6_PACKET *Packet
);
/**
EFI_MTFTP6_TIMEOUT_CALLBACK is a callback function that the caller provides to capture the
timeout event in the EFI_MTFTP6_PROTOCOL.ReadFile(), EFI_MTFTP6_PROTOCOL.WriteFile() or
EFI_MTFTP6_PROTOCOL.ReadDirectory() functions.
Whenever a timeout occurs, the EFI MTFTPv6 Protocol driver will call the EFI_MTFTP6_TIMEOUT_CALLBACK
function to notify the caller of the timeout event. Any status code other than EFI_SUCCESS
that is returned from this function will abort the current download process.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] Token The token that is provided in the EFI_MTFTP6_PROTOCOL.ReadFile() or
EFI_MTFTP6_PROTOCOL.WriteFile() or EFI_MTFTP6_PROTOCOL.ReadDirectory()
functions by the caller.
@retval EFI_SUCCESS Operation sucess.
@retval Others Aborts session.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_TIMEOUT_CALLBACK)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_TOKEN *Token
);
/**
EFI_MTFTP6_PACKET_NEEDED is a callback function that the caller provides to feed data to the
EFI_MTFTP6_PROTOCOL.WriteFile() function.
EFI_MTFTP6_PACKET_NEEDED provides another mechanism for the caller to provide data to upload
other than a static buffer. The EFI MTFTP6 Protocol driver always calls EFI_MTFTP6_PACKET_NEEDED
to get packet data from the caller if no static buffer was given in the initial call to
EFI_MTFTP6_PROTOCOL.WriteFile() function. Setting *Length to zero signals the end of the session.
Returning a status code other than EFI_SUCCESS aborts the session.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] Token The token provided in the EFI_MTFTP6_PROTOCOL.WriteFile() by the caller.
@param[in, out] Length Indicates the length of the raw data wanted on input, and the
length the data available on output.
@param[out] Buffer Pointer to the buffer where the data is stored.
@retval EFI_SUCCESS Operation sucess.
@retval Others Aborts session.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_PACKET_NEEDED)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_TOKEN *Token,
IN OUT UINT16 *Length,
OUT VOID **Buffer
);
struct _EFI_MTFTP6_TOKEN {
///
/// The status that is returned to the caller at the end of the operation
/// to indicate whether this operation completed successfully.
/// Defined Status values are listed below.
///
EFI_STATUS Status;
///
/// The event that will be signaled when the operation completes. If
/// set to NULL, the corresponding function will wait until the read or
/// write operation finishes. The type of Event must be EVT_NOTIFY_SIGNAL.
///
EFI_EVENT Event;
///
/// If not NULL, the data that will be used to override the existing
/// configure data.
///
EFI_MTFTP6_OVERRIDE_DATA *OverrideData;
///
/// Pointer to the ASCIIZ file name string.
///
UINT8 *Filename;
///
/// Pointer to the ASCIIZ mode string. If NULL, octet is used.
///
UINT8 *ModeStr;
///
/// Number of option/value string pairs.
///
UINT32 OptionCount;
///
/// Pointer to an array of option/value string pairs. Ignored if
/// OptionCount is zero. Both a remote server and this driver
/// implementation should support these options. If one or more
/// options are unrecognized by this implementation, it is sent to the
/// remote server without being changed.
///
EFI_MTFTP6_OPTION *OptionList;
///
/// On input, the size, in bytes, of Buffer. On output, the number
/// of bytes transferred.
///
UINT64 BufferSize;
///
/// Pointer to the data buffer. Data that is downloaded from the
/// MTFTPv6 server is stored here. Data that is uploaded to the
/// MTFTPv6 server is read from here. Ignored if BufferSize is zero.
///
VOID *Buffer;
///
/// Pointer to the context that will be used by CheckPacket,
/// TimeoutCallback and PacketNeeded.
///
VOID *Context;
///
/// Pointer to the callback function to check the contents of the
/// received packet.
///
EFI_MTFTP6_CHECK_PACKET CheckPacket;
///
/// Pointer to the function to be called when a timeout occurs.
///
EFI_MTFTP6_TIMEOUT_CALLBACK TimeoutCallback;
///
/// Pointer to the function to provide the needed packet contents.
/// Only used in WriteFile() operation.
///
EFI_MTFTP6_PACKET_NEEDED PacketNeeded;
};
/**
Read the current operational settings.
The GetModeData() function reads the current operational settings of this EFI MTFTPv6
Protocol driver instance.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[out] ModeData The buffer in which the EFI MTFTPv6 Protocol driver mode
data is returned.
@retval EFI_SUCCESS The configuration data was successfully returned.
@retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
@retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_GET_MODE_DATA)(
IN EFI_MTFTP6_PROTOCOL *This,
OUT EFI_MTFTP6_MODE_DATA *ModeData
);
/**
Initializes, changes, or resets the default operational setting for this EFI MTFTPv6
Protocol driver instance.
The Configure() function is used to set and change the configuration data for this EFI
MTFTPv6 Protocol driver instance. The configuration data can be reset to startup defaults by calling
Configure() with MtftpConfigData set to NULL. Whenever the instance is reset, any
pending operation is aborted. By changing the EFI MTFTPv6 Protocol driver instance configuration
data, the client can connect to different MTFTPv6 servers. The configuration parameters in
MtftpConfigData are used as the default parameters in later MTFTPv6 operations and can be
overridden in later operations.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] MtftpConfigData Pointer to the configuration data structure.
@retval EFI_SUCCESS The EFI MTFTPv6 Protocol instance was configured successfully.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
- This is NULL.
- MtftpConfigData.StationIp is neither zero nor one
of the configured IP addresses in the underlying IPv6 driver.
- MtftpCofigData.ServerIp is not a valid IPv6 unicast address.
- The StationIP and LocalPort is already in use
@retval EFI_ACCESS_DENIED The configuration could not be changed at this time because there
is some MTFTP background operation in progress.
@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
address for this instance, but no source address was available for use
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_CONFIGURE)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_CONFIG_DATA *MtftpConfigData OPTIONAL
);
/**
Get information about a file from an MTFTPv6 server.
The GetInfo() function assembles an MTFTPv6 request packet with options, sends it to the
MTFTPv6 server, and may return an MTFTPv6 OACK, MTFTPv6 ERROR, or ICMP ERROR packet.
Retries occur only if no response packets are received from the MTFTPv6 server before the
timeout expires.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] OverrideData Data that is used to override the existing parameters. If NULL, the
default parameters that were set in the EFI_MTFTP6_PROTOCOL.Configure()
function are used.
@param[in] Filename Pointer to ASCIIZ file name string.
@param[in] ModeStr Pointer to ASCIIZ mode string. If NULL, octet will be used
@param[in] OptionCount Number of option/value string pairs in OptionList.
@param[in] OptionList Pointer to array of option/value string pairs. Ignored if
OptionCount is zero.
@param[out] PacketLength The number of bytes in the returned packet.
@param[out] Packet The pointer to the received packet. This buffer must be freed by
the caller.
@retval EFI_SUCCESS An MTFTPv6 OACK packet was received and is in the Buffer.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- This is NULL.
- Filename is NULL
- OptionCount is not zero and OptionList is NULL.
- One or more options in OptionList have wrong format.
- PacketLength is NULL.
- OverrideData.ServerIp is not valid unicast IPv6 addresses.
@retval EFI_UNSUPPORTED One or more options in the OptionList are unsupported by
this implementation.
@retval EFI_NOT_STARTED The EFI MTFTPv6 Protocol driver has not been started.
@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
address for this instance, but no source address was available for use.
@retval EFI_ACCESS_DENIED The previous operation has not completed yet.
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
@retval EFI_TFTP_ERROR An MTFTPv6 ERROR packet was received and is in the Packet.
@retval EFI_ICMP_ERROR An ICMP ERROR packet was received and the Packet is set to NULL.
@retval EFI_PROTOCOL_ERROR An unexpected MTFTPv6 packet was received and is in the Packet.
@retval EFI_TIMEOUT No responses were received from the MTFTPv6 server.
@retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_GET_INFO)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_OVERRIDE_DATA *OverrideData OPTIONAL,
IN UINT8 *Filename,
IN UINT8 *ModeStr OPTIONAL,
IN UINT8 OptionCount,
IN EFI_MTFTP6_OPTION *OptionList OPTIONAL,
OUT UINT32 *PacketLength,
OUT EFI_MTFTP6_PACKET **Packet OPTIONAL
);
/**
Parse the options in an MTFTPv6 OACK packet.
The ParseOptions() function parses the option fields in an MTFTPv6 OACK packet and
returns the number of options that were found and optionally a list of pointers to
the options in the packet.
If one or more of the option fields are not valid, then EFI_PROTOCOL_ERROR is returned
and *OptionCount and *OptionList stop at the last valid option.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] PacketLen Length of the OACK packet to be parsed.
@param[in] Packet Pointer to the OACK packet to be parsed.
@param[out] OptionCount Pointer to the number of options in the following OptionList.
@param[out] OptionList Pointer to EFI_MTFTP6_OPTION storage. Each pointer in the
OptionList points to the corresponding MTFTP option buffer
in the Packet. Call the EFI Boot Service FreePool() to
release the OptionList if the options in this OptionList
are not needed any more.
@retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
OptionList parameters have been updated.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- PacketLen is 0.
- Packet is NULL or Packet is not a valid MTFTPv6 packet.
- OptionCount is NULL.
@retval EFI_NOT_FOUND No options were found in the OACK packet.
@retval EFI_OUT_OF_RESOURCES Storage for the OptionList array can not be allocated.
@retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_PARSE_OPTIONS)(
IN EFI_MTFTP6_PROTOCOL *This,
IN UINT32 PacketLen,
IN EFI_MTFTP6_PACKET *Packet,
OUT UINT32 *OptionCount,
OUT EFI_MTFTP6_OPTION **OptionList OPTIONAL
);
/**
Download a file from an MTFTPv6 server.
The ReadFile() function is used to initialize and start an MTFTPv6 download process and
optionally wait for completion. When the download operation completes, whether successfully or
not, the Token.Status field is updated by the EFI MTFTPv6 Protocol driver and then
Token.Event is signaled if it is not NULL.
Data can be downloaded from the MTFTPv6 server into either of the following locations:
- A fixed buffer that is pointed to by Token.Buffer
- A download service function that is pointed to by Token.CheckPacket
If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
will be called first. If the call is successful, the packet will be stored in Token.Buffer.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] Token Pointer to the token structure to provide the parameters that are
used in this operation.
@retval EFI_SUCCESS The data file has been transferred successfully.
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
@retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded data
in downloading process.
@retval EFI_ABORTED Current operation is aborted by user.
@retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
@retval EFI_TIMEOUT No responses were received from the MTFTPv6 server.
@retval EFI_TFTP_ERROR An MTFTPv6 ERROR packet was received.
@retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_READ_FILE)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_TOKEN *Token
);
/**
Send a file to an MTFTPv6 server. May be unsupported in some implementations.
The WriteFile() function is used to initialize an uploading operation with the given option list
and optionally wait for completion. If one or more of the options is not supported by the server, the
unsupported options are ignored and a standard TFTP process starts instead. When the upload
process completes, whether successfully or not, Token.Event is signaled, and the EFI MTFTPv6
Protocol driver updates Token.Status.
The caller can supply the data to be uploaded in the following two modes:
- Through the user-provided buffer
- Through a callback function
With the user-provided buffer, the Token.BufferSize field indicates the length of the buffer,
and the driver will upload the data in the buffer. With an EFI_MTFTP6_PACKET_NEEDED
callback function, the driver will call this callback function to get more data from the user to upload.
See the definition of EFI_MTFTP6_PACKET_NEEDED for more information. These two modes
cannot be used at the same time. The callback function will be ignored if the user provides the
buffer.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] Token Pointer to the token structure to provide the parameters that are
used in this operation.
@retval EFI_SUCCESS The upload session has started.
@retval EFI_UNSUPPORTED The operation is not supported by this implementation.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- This is NULL.
- Token is NULL.
- Token.Filename is NULL.
- Token.OptionCount is not zero and Token.OptionList is NULL.
- One or more options in Token.OptionList have wrong format.
- Token.Buffer and Token.PacketNeeded are both NULL.
- Token.OverrideData.ServerIp is not valid unicast IPv6 addresses.
@retval EFI_UNSUPPORTED One or more options in the Token.OptionList are not
supported by this implementation.
@retval EFI_NOT_STARTED The EFI MTFTPv6 Protocol driver has not been started.
@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
address for this instance, but no source address was available for use.
@retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv6 session.
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
@retval EFI_ACCESS_DENIED The previous operation has not completed yet.
@retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_WRITE_FILE)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_TOKEN *Token
);
/**
Download a data file directory from an MTFTPv6 server. May be unsupported in some implementations.
The ReadDirectory() function is used to return a list of files on the MTFTPv6 server that are
logically (or operationally) related to Token.Filename. The directory request packet that is sent
to the server is built with the option list that was provided by caller, if present.
The file information that the server returns is put into either of the following locations:
- A fixed buffer that is pointed to by Token.Buffer
- A download service function that is pointed to by Token.CheckPacket
If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
will be called first. If the call is successful, the packet will be stored in Token.Buffer.
The returned directory listing in the Token.Buffer or EFI_MTFTP6_PACKET consists of a list
of two or three variable-length ASCII strings, each terminated by a null character, for each file in the
directory. If the multicast option is involved, the first field of each directory entry is the static
multicast IP address and UDP port number that is associated with the file name. The format of the
field is ip:ip:ip:ip:port. If the multicast option is not involved, this field and its terminating
null character are not present.
The next field of each directory entry is the file name and the last field is the file information string.
The information string contains the file size and the create/modify timestamp. The format of the
information string is filesize yyyy-mm-dd hh:mm:ss:ffff. The timestamp is
Coordinated Universal Time (UTC; also known as Greenwich Mean Time [GMT]).
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@param[in] Token Pointer to the token structure to provide the parameters that are
used in this operation.
@retval EFI_SUCCESS The MTFTPv6 related file "directory" has been downloaded.
@retval EFI_UNSUPPORTED The EFI MTFTPv6 Protocol driver does not support this function.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- This is NULL.
- Token is NULL.
- Token.Filename is NULL.
- Token.OptionCount is not zero and Token.OptionList is NULL.
- One or more options in Token.OptionList have wrong format.
- Token.Buffer and Token.CheckPacket are both NULL.
- Token.OverrideData.ServerIp is not valid unicast IPv6 addresses.
@retval EFI_UNSUPPORTED One or more options in the Token.OptionList are not
supported by this implementation.
@retval EFI_NOT_STARTED The EFI MTFTPv6 Protocol driver has not been started.
@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
address for this instance, but no source address was available for use.
@retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv6 session.
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
@retval EFI_ACCESS_DENIED The previous operation has not completed yet.
@retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_READ_DIRECTORY)(
IN EFI_MTFTP6_PROTOCOL *This,
IN EFI_MTFTP6_TOKEN *Token
);
/**
Polls for incoming data packets and processes outgoing data packets.
The Poll() function can be used by network drivers and applications to increase the rate that data
packets are moved between the communications device and the transmit and receive queues.
In some systems, the periodic timer event in the managed network driver may not poll the
underlying communications device fast enough to transmit and/or receive all data packets without
missing incoming packets or dropping outgoing packets. Drivers and applications that are
experiencing packet loss should try calling the Poll() function more often.
@param[in] This Pointer to the EFI_MTFTP6_PROTOCOL instance.
@retval EFI_SUCCESS Incoming or outgoing data was processed.
@retval EFI_NOT_STARTED This EFI MTFTPv6 Protocol instance has not been started.
@retval EFI_INVALID_PARAMETER This is NULL.
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
@retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
Consider increasing the polling rate.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_MTFTP6_POLL)(
IN EFI_MTFTP6_PROTOCOL *This
);
///
/// The EFI_MTFTP6_PROTOCOL is designed to be used by UEFI drivers and applications to transmit
/// and receive data files. The EFI MTFTPv6 Protocol driver uses the underlying EFI UDPv6 Protocol
/// driver and EFI IPv6 Protocol driver.
///
struct _EFI_MTFTP6_PROTOCOL {
EFI_MTFTP6_GET_MODE_DATA GetModeData;
EFI_MTFTP6_CONFIGURE Configure;
EFI_MTFTP6_GET_INFO GetInfo;
EFI_MTFTP6_PARSE_OPTIONS ParseOptions;
EFI_MTFTP6_READ_FILE ReadFile;
EFI_MTFTP6_WRITE_FILE WriteFile;
EFI_MTFTP6_READ_DIRECTORY ReadDirectory;
EFI_MTFTP6_POLL Poll;
};
extern EFI_GUID gEfiMtftp6ServiceBindingProtocolGuid;
extern EFI_GUID gEfiMtftp6ProtocolGuid;
#endif

569
MdePkg/Include/Protocol/Udp6.h Normal file
View File

@ -0,0 +1,569 @@
/** @file
The EFI UDPv6 (User Datagram Protocol version 6) Protocol Definition, which is built upon
the EFI IPv6 Protocol and provides simple packet-oriented services to transmit and receive
UDP packets.
Copyright (c) 2008 - 2009, 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 __EFI_UDP6_PROTOCOL_H__
#define __EFI_UDP6_PROTOCOL_H__
#include <Protocol/Ip6.h>
#define EFI_UDP6_SERVICE_BINDING_PROTOCOL_GUID \
{ \
0x66ed4721, 0x3c98, 0x4d3e, {0x81, 0xe3, 0xd0, 0x3d, 0xd3, 0x9a, 0x72, 0x54 } \
}
#define EFI_UDP6_PROTOCOL_GUID \
{ \
0x4f948815, 0xb4b9, 0x43cb, {0x8a, 0x33, 0x90, 0xe0, 0x60, 0xb3, 0x49, 0x55 } \
}
typedef struct {
///
/// The EFI UDPv6 Protocol instance handle that is using this address/port pair.
///
EFI_HANDLE InstanceHandle;
///
/// The IPv6 address to which this instance of the EFI UDPv6 Protocol is bound.
/// Set to 0::/128, if this instance is used to listen all packets from any
/// source address.
///
EFI_IPv6_ADDRESS LocalAddress;
///
/// The port number in host byte order on which the service is listening.
///
UINT16 LocalPort;
///
/// The IPv6 address of the remote host. May be 0::/128 if it is not connected
/// to any remote host or connected with more than one remote host.
///
EFI_IPv6_ADDRESS RemoteAddress;
///
/// The port number in host byte order on which the remote host is
/// listening. Maybe zero if it is not connected to any remote host.
///
UINT16 RemotePort;
} EFI_UDP6_SERVICE_POINT;
typedef struct {
///
/// The handle of the driver that creates this entry.
///
EFI_HANDLE DriverHandle;
///
/// The number of address/port pairs that follow this data structure.
///
UINT32 ServiceCount;
///
/// List of address/port pairs that are currently in use.
///
EFI_UDP6_SERVICE_POINT Services[1];
} EFI_UDP6_VARIABLE_DATA;
typedef struct _EFI_UDP6_PROTOCOL EFI_UDP6_PROTOCOL;
///
/// EFI_UDP6_FRAGMENT_DATA allows multiple receive or transmit buffers to be specified.
/// The purpose of this structure is to avoid copying the same packet multiple times.
///
typedef struct {
UINT32 FragmentLength; ///< Length of the fragment data buffer.
VOID *FragmentBuffer; ///< Pointer to the fragment data buffer.
} EFI_UDP6_FRAGMENT_DATA;
///
/// The EFI_UDP6_SESSION_DATA is used to retrieve the settings when receiving packets or
/// to override the existing settings (only DestinationAddress and DestinationPort can
/// be overridden) of this EFI UDPv6 Protocol instance when sending packets.
///
typedef struct {
///
/// Address from which this packet is sent. This field should not be used when
/// sending packets.
///
EFI_IPv6_ADDRESS SourceAddress;
///
/// Port from which this packet is sent. It is in host byte order. This field should
/// not be used when sending packets.
///
UINT16 SourcePort;
///
/// Address to which this packet is sent. When sending packet, it¡¯ll be ignored
/// if it is zero.
///
EFI_IPv6_ADDRESS DestinationAddress;
///
/// Port to which this packet is sent. When sending packet, it¡¯ll be
/// ignored if it is zero.
///
UINT16 DestinationPort;
} EFI_UDP6_SESSION_DATA;
typedef struct {
///
/// Set to TRUE to accept UDP packets that are sent to any address.
///
BOOLEAN AcceptPromiscuous;
///
/// Set to TRUE to accept UDP packets that are sent to any port.
///
BOOLEAN AcceptAnyPort;
///
/// Set to TRUE to allow this EFI UDPv6 Protocol child instance to open a port number
/// that is already being used by another EFI UDPv6 Protocol child instance.
///
BOOLEAN AllowDuplicatePort;
///
/// TrafficClass field in transmitted IPv6 packets.
///
UINT8 TrafficClass;
///
/// HopLimit field in transmitted IPv6 packets.
///
UINT8 HopLimit;
///
/// The receive timeout value (number of microseconds) to be associated with each
/// incoming packet. Zero means do not drop incoming packets.
///
UINT32 ReceiveTimeout;
///
/// The transmit timeout value (number of microseconds) to be associated with each
/// outgoing packet. Zero means do not drop outgoing packets.
///
UINT32 TransmitTimeout;
///
/// The station IP address that will be assigned to this EFI UDPv6 Protocol instance.
/// The EFI UDPv6 and EFI IPv6 Protocol drivers will only deliver incoming packets
/// whose destination matches this IP address exactly. Address 0::/128 is also accepted
/// as a special case. Under this situation, underlying IPv6 driver is responsible for
/// binding a source address to this EFI IPv6 protocol instance according to source
/// address selection algorithm. Only incoming packet from the selected source address
/// is delivered. This field can be set and changed only when the EFI IPv6 driver is
/// transitioning from the stopped to the started states. If no address is available
/// for selecting, the EFI IPv6 Protocol driver will use EFI_IP6_CONFIG_PROTOCOL to
/// retrieve the IPv6 address.
EFI_IPv6_ADDRESS StationAddress;
///
/// The port number to which this EFI UDPv6 Protocol instance is bound. If a client
/// of the EFI UDPv6 Protocol does not care about the port number, set StationPort
/// to zero. The EFI UDPv6 Protocol driver will assign a random port number to transmitted
/// UDP packets. Ignored it if AcceptAnyPort is TRUE.
///
UINT16 StationPort;
///
/// The IP address of remote host to which this EFI UDPv6 Protocol instance is connecting.
/// If RemoteAddress is not 0::/128, this EFI UDPv6 Protocol instance will be connected to
/// RemoteAddress; i.e., outgoing packets of this EFI UDPv6 Protocol instance will be sent
/// to this address by default and only incoming packets from this address will be delivered
/// to client. Ignored for incoming filtering if AcceptPromiscuous is TRUE.
EFI_IPv6_ADDRESS RemoteAddress;
///
/// The port number of the remote host to which this EFI UDPv6 Protocol instance is connecting.
/// If it is not zero, outgoing packets of this EFI UDPv6 Protocol instance will be sent to
/// this port number by default and only incoming packets from this port will be delivered
/// to client. Ignored if RemoteAddress is 0::/128 and ignored for incoming filtering if
/// AcceptPromiscuous is TRUE.
UINT16 RemotePort;
} EFI_UDP6_CONFIG_DATA;
///
/// The EFI UDPv6 Protocol client must fill this data structure before sending a packet.
/// The packet may contain multiple buffers that may be not in a continuous memory location.
///
typedef struct {
///
/// If not NULL, the data that is used to override the transmitting settings.Only the two
/// filed UdpSessionData.DestinationAddress and UdpSessionData.DestionPort can be used as
/// the transmitting setting filed.
///
EFI_UDP6_SESSION_DATA *UdpSessionData;
///
/// Sum of the fragment data length. Must not exceed the maximum UDP packet size.
///
UINT32 DataLength;
///
/// Number of fragments.
///
UINT32 FragmentCount;
///
/// Array of fragment descriptors.
///
EFI_UDP6_FRAGMENT_DATA FragmentTable[1];
} EFI_UDP6_TRANSMIT_DATA;
///
/// EFI_UDP6_RECEIVE_DATA is filled by the EFI UDPv6 Protocol driver when this EFI UDPv6
/// Protocol instance receives an incoming packet. If there is a waiting token for incoming
/// packets, the CompletionToken.Packet.RxData field is updated to this incoming packet and
/// the CompletionToken.Event is signaled. The EFI UDPv6 Protocol client must signal the
/// RecycleSignal after processing the packet.
/// FragmentTable could contain multiple buffers that are not in the continuous memory locations.
/// The EFI UDPv6 Protocol client might need to combine two or more buffers in FragmentTable to
/// form their own protocol header.
///
typedef struct {
///
/// Time when the EFI UDPv6 Protocol accepted the packet.
///
EFI_TIME TimeStamp;
///
/// Indicates the event to signal when the received data has been processed.
///
EFI_EVENT RecycleSignal;
///
/// The UDP session data including SourceAddress, SourcePort, DestinationAddress,
/// and DestinationPort.
///
EFI_UDP6_SESSION_DATA UdpSession;
///
/// The sum of the fragment data length.
///
UINT32 DataLength;
///
/// Number of fragments. Maybe zero.
///
UINT32 FragmentCount;
///
/// Array of fragment descriptors. Maybe zero.
///
EFI_UDP6_FRAGMENT_DATA FragmentTable[1];
} EFI_UDP6_RECEIVE_DATA;
///
/// The EFI_UDP6_COMPLETION_TOKEN structures are used for both transmit and receive operations.
/// When used for transmitting, the Event and TxData fields must be filled in by the EFI UDPv6
/// Protocol client. After the transmit operation completes, the Status field is updated by the
/// EFI UDPv6 Protocol and the Event is signaled.
/// When used for receiving, only the Event field must be filled in by the EFI UDPv6 Protocol
/// client. After a packet is received, RxData and Status are filled in by the EFI UDPv6 Protocol
/// and the Event is signaled.
///
typedef struct {
///
/// This Event will be signaled after the Status field is updated by the EFI UDPv6 Protocol
/// driver. The type of Event must be EVT_NOTIFY_SIGNAL.
///
EFI_EVENT Event;
///
/// Will be set to one of the following values:
/// - EFI_SUCCESS: The receive or transmit operation completed successfully.
/// - EFI_ABORTED: The receive or transmit was aborted.
/// - EFI_TIMEOUT: The transmit timeout expired.
/// - EFI_NETWORK_UNREACHABLE: The destination network is unreachable. RxData is set to
/// NULL in this situation.
/// - EFI_HOST_UNREACHABLE: The destination host is unreachable. RxData is set to NULL in
/// this situation.
/// - EFI_PROTOCOL_UNREACHABLE: The UDP protocol is unsupported in the remote system.
/// RxData is set to NULL in this situation.
/// - EFI_PORT_UNREACHABLE: No service is listening on the remote port. RxData is set to
/// NULL in this situation.
/// - EFI_ICMP_ERROR: Some other Internet Control Message Protocol (ICMP) error report was
/// received. For example, packets are being sent too fast for the destination to receive them
/// and the destination sent an ICMP source quench report. RxData is set to NULL in this situation.
/// - EFI_DEVICE_ERROR: An unexpected system or network error occurred.
/// - EFI_SECURITY_VIOLATION: The transmit or receive was failed because of IPsec policy check.
///
EFI_STATUS Status;
union {
///
/// When this token is used for receiving, RxData is a pointer to EFI_UDP6_RECEIVE_DATA.
///
EFI_UDP6_RECEIVE_DATA *RxData;
///
/// When this token is used for transmitting, TxData is a pointer to EFI_UDP6_TRANSMIT_DATA.
///
EFI_UDP6_TRANSMIT_DATA *TxData;
} Packet;
} EFI_UDP6_COMPLETION_TOKEN;
/**
Read the current operational settings.
The GetModeData() function copies the current operational settings of this EFI UDPv6 Protocol
instance into user-supplied buffers. This function is used optionally to retrieve the operational
mode data of underlying networks or drivers.
@param[in] This Pointer to the EFI_UDP6_PROTOCOL instance.
@param[out] Udp6ConfigData The buffer in which the current UDP configuration data is returned.
@param[out] Ip6ModeData The buffer in which the current EFI IPv6 Protocol mode data is returned.
@param[out] MnpConfigData The buffer in which the current managed network configuration data is
returned.
@param[out] SnpModeData The buffer in which the simple network mode data is returned.
@retval EFI_SUCCESS The mode data was read.
@retval EFI_NOT_STARTED When Udp6ConfigData is queried, no configuration data is available
because this instance has not been started.
@retval EFI_INVALID_PARAMETER This is NULL.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_UDP6_GET_MODE_DATA)(
IN EFI_UDP6_PROTOCOL *This,
OUT EFI_UDP6_CONFIG_DATA *Udp6ConfigData OPTIONAL,
OUT EFI_IP6_MODE_DATA *Ip6ModeData OPTIONAL,
OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL,
OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL
);
/**
Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv6
Protocol.
The Configure() function is used to do the following:
- Initialize and start this instance of the EFI UDPv6 Protocol.
- Change the filtering rules and operational parameters.
- Reset this instance of the EFI UDPv6 Protocol.
Until these parameters are initialized, no network traffic can be sent or received by this instance.
This instance can be also reset by calling Configure() with UdpConfigData set to NULL.
Once reset, the receiving queue and transmitting queue are flushed and no traffic is allowed through
this instance.
With different parameters in UdpConfigData, Configure() can be used to bind this instance to specified
port.
@param[in] This Pointer to the EFI_UDP6_PROTOCOL instance.
@param[in] UdpConfigData Pointer to the buffer contained the configuration data.
@retval EFI_SUCCESS The configuration settings were set, changed, or reset successfully.
@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
address for this instance, but no source address was available for use.
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
- This is NULL.
- UdpConfigData.StationAddress neither zero nor one of the configured IP
addresses in the underlying IPv6 driver.
- UdpConfigData.RemoteAddress is not a valid unicast IPv6 address if it
is not zero.
@retval EFI_ALREADY_STARTED The EFI UDPv6 Protocol instance is already started/configured and must be
stopped/reset before it can be reconfigured. Only TrafficClass, HopLimit,
ReceiveTimeout, and TransmitTimeout can be reconfigured without stopping
the current instance of the EFI UDPv6 Protocol.
@retval EFI_ACCESS_DENIED UdpConfigData.AllowDuplicatePort is FALSE and UdpConfigData.StationPort
is already used by other instance.
@retval EFI_OUT_OF_RESOURCES The EFI UDPv6 Protocol driver cannot allocate memory for this EFI UDPv6
Protocol instance.
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred and this instance was not
opened.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_UDP6_CONFIGURE)(
IN EFI_UDP6_PROTOCOL *This,
IN EFI_UDP6_CONFIG_DATA *UdpConfigData OPTIONAL
);
/**
Joins and leaves multicast groups.
The Groups() function is used to join or leave one or more multicast group.
If the JoinFlag is FALSE and the MulticastAddress is NULL, then all currently joined groups are left.
@param[in] This Pointer to the EFI_UDP6_PROTOCOL instance.
@param[in] JoinFlag Set to TRUE to join a multicast group. Set to FALSE to leave one
or all multicast groups.
@param[in] MulticastAddress Pointer to multicast group address to join or leave.
@retval EFI_SUCCESS The operation completed successfully.
@retval EFI_NOT_STARTED The EFI UDPv6 Protocol instance has not been started.
@retval EFI_OUT_OF_RESOURCES Could not allocate resources to join the group.
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- This is NULL.
- JoinFlag is TRUE and MulticastAddress is NULL.
- JoinFlag is TRUE and *MulticastAddress is not a valid multicast address.
@retval EFI_ALREADY_STARTED The group address is already in the group table (when JoinFlag is TRUE).
@retval EFI_NOT_FOUND The group address is not in the group table (when JoinFlag is FALSE).
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_UDP6_GROUPS)(
IN EFI_UDP6_PROTOCOL *This,
IN BOOLEAN JoinFlag,
IN EFI_IPv6_ADDRESS *MulticastAddress OPTIONAL
);
/**
Queues outgoing data packets into the transmit queue.
The Transmit() function places a sending request to this instance of the EFI UDPv6 Protocol,
alongside the transmit data that was filled by the user. Whenever the packet in the token is
sent out or some errors occur, the Token.Event will be signaled and Token.Status is updated.
Providing a proper notification function and context for the event will enable the user to
receive the notification and transmitting status.
@param[in] This Pointer to the EFI_UDP6_PROTOCOL instance.
@param[in] Token Pointer to the completion token that will be placed into the
transmit queue.
@retval EFI_SUCCESS The data has been queued for transmission.
@retval EFI_NOT_STARTED This EFI UDPv6 Protocol instance has not been started.
@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
address for this instance, but no source address was available
for use.
@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
- This is NULL.
- Token is NULL.
- Token.Event is NULL.
- Token.Packet.TxData is NULL.
- Token.Packet.TxData.FragmentCount is zero.
- Token.Packet.TxData.DataLength is not equal to the sum of fragment
lengths.
- One or more of the Token.Packet.TxData.FragmentTable[].FragmentLength
fields is zero.
- One or more of the Token.Packet.TxData.FragmentTable[].FragmentBuffer
fields is NULL.
- Token.Packet.TxData.UdpSessionData.DestinationAddress is not zero
and is not valid unicast Ipv6 address if UdpSessionData is not NULL.
- Token.Packet.TxData.UdpSessionData is NULL and this instance¡¯s
UdpConfigData.RemoteAddress is unspecified.
- Token.Packet.TxData.UdpSessionData.DestinationAddress is non-zero
when DestinationAddress is configured as non-zero when doing Configure()
for this EFI Udp6 protocol instance.
- Token.Packet.TxData.UdpSesionData.DestinationAddress is zero when
DestinationAddress is unspecified when doing Configure() for this
EFI Udp6 protocol instance.
@retval EFI_ACCESS_DENIED The transmit completion token with the same Token.Event was already
in the transmit queue.
@retval EFI_NOT_READY The completion token could not be queued because the transmit queue
is full.
@retval EFI_OUT_OF_RESOURCES Could not queue the transmit data.
@retval EFI_NOT_FOUND There is no route to the destination network or address.
@retval EFI_BAD_BUFFER_SIZE The data length is greater than the maximum UDP packet size.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_UDP6_TRANSMIT)(
IN EFI_UDP6_PROTOCOL *This,
IN EFI_UDP6_COMPLETION_TOKEN *Token
);
/**
Places an asynchronous receive request into the receiving queue.
The Receive() function places a completion token into the receive packet queue. This function is
always asynchronous.
The caller must fill in the Token.Event field in the completion token, and this field cannot be
NULL. When the receive operation completes, the EFI UDPv6 Protocol driver updates the Token.Status
and Token.Packet.RxData fields and the Token.Event is signaled.
Providing a proper notification function and context for the event will enable the user to receive
the notification and receiving status. That notification function is guaranteed to not be re-entered.
@param[in] This Pointer to the EFI_UDP6_PROTOCOL instance.
@param[in] Token Pointer to a token that is associated with the receive data descriptor.
@retval EFI_SUCCESS The receive completion token was cached.
@retval EFI_NOT_STARTED This EFI UDPv6 Protocol instance has not been started.
@retval EFI_NO_MAPPING The underlying IPv6 driver was responsible for choosing a source
address for this instance, but no source address was available
for use.
@retval EFI_INVALID_PARAMETER One or more of the following is TRUE:
- This is NULL.
- Token is NULL.
- Token.Event is NULL.
@retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of system
resources (usually memory).
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI UDPv6 Protocol
instance has been reset to startup defaults.
@retval EFI_ACCESS_DENIED A receive completion token with the same Token.Event was already in
the receive queue.
@retval EFI_NOT_READY The receive request could not be queued because the receive queue is full.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_UDP6_RECEIVE)(
IN EFI_UDP6_PROTOCOL *This,
IN EFI_UDP6_COMPLETION_TOKEN *Token
);
/**
Aborts an asynchronous transmit or receive request.
The Cancel() function is used to abort a pending transmit or receive request. If the token is in the
transmit or receive request queues, after calling this function, Token.Status will be set to
EFI_ABORTED and then Token.Event will be signaled. If the token is not in one of the queues,
which usually means that the asynchronous operation has completed, this function will not signal the
token and EFI_NOT_FOUND is returned.
@param[in] This Pointer to the EFI_UDP6_PROTOCOL instance.
@param[in] Token Pointer to a token that has been issued by EFI_UDP6_PROTOCOL.Transmit()
or EFI_UDP6_PROTOCOL.Receive().If NULL, all pending tokens are aborted.
@retval EFI_SUCCESS The asynchronous I/O request was aborted and Token.Event was signaled.
When Token is NULL, all pending requests are aborted and their events
are signaled.
@retval EFI_INVALID_PARAMETER This is NULL.
@retval EFI_NOT_STARTED This instance has not been started.
@retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O request was not found in
the transmit or receive queue. It has either completed or was not issued
by Transmit() and Receive().
**/
typedef
EFI_STATUS
(EFIAPI *EFI_UDP6_CANCEL)(
IN EFI_UDP6_PROTOCOL *This,
IN EFI_UDP6_COMPLETION_TOKEN *Token OPTIONAL
);
/**
Polls for incoming data packets and processes outgoing data packets.
The Poll() function can be used by network drivers and applications to increase the rate that data
packets are moved between the communications device and the transmit and receive queues.
In some systems, the periodic timer event in the managed network driver may not poll the underlying
communications device fast enough to transmit and/or receive all data packets without missing incoming
packets or dropping outgoing packets. Drivers and applications that are experiencing packet loss should
try calling the Poll() function more often.
@param[in] This Pointer to the EFI_UDP6_PROTOCOL instance.
@retval EFI_SUCCESS Incoming or outgoing data was processed.
@retval EFI_INVALID_PARAMETER This is NULL.
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
@retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
Consider increasing the polling rate.
**/
typedef
EFI_STATUS
(EFIAPI *EFI_UDP6_POLL)(
IN EFI_UDP6_PROTOCOL *This
);
///
/// The EFI_UDP6_PROTOCOL defines an EFI UDPv6 Protocol session that can be used by any network drivers,
/// applications, or daemons to transmit or receive UDP packets. This protocol instance can either be
/// bound to a specified port as a service or connected to some remote peer as an active client.
/// Each instance has its own settings, such as group table, that are independent from each other.
///
struct _EFI_UDP6_PROTOCOL {
EFI_UDP6_GET_MODE_DATA GetModeData;
EFI_UDP6_CONFIGURE Configure;
EFI_UDP6_GROUPS Groups;
EFI_UDP6_TRANSMIT Transmit;
EFI_UDP6_RECEIVE Receive;
EFI_UDP6_CANCEL Cancel;
EFI_UDP6_POLL Poll;
};
extern EFI_GUID gEfiUdp6ServiceBindingProtocolGuid;
extern EFI_GUID gEfiUdp6ProtocolGuid;
extern EFI_GUID gEfiUdp6RegistryDataGuid;
#endif