Intel Extensible Firmware Interface - Manual (Page 148)

Extensible Firmware Interface Specification
5-50 12/01/02 Version 1.10
ControllerHandle If the agent that is opening a protocol is a driver that follows the
EFI Driver Model, then this parameter is the controller handle
that requires the protocol interface. If the agent does not follow
the EFI Driver Model, then this parameter is optional and may
be
NULL .
Attributes The open mode of the protocol interface specified by Handle
and Protocol . See "Related Definitions" for the list of legal
attributes.
Description
This function opens a protocol interface on the handle specified by Handle for the protocol
specified by Protocol . The first three parameters are the same as HandleProtocol() . The
only difference is that the agent that is opening a protocol interface is tracked in EFI's internal
handle database. The tracking is used by the EFI Driver Model, and also used to determine if it is
safe to uninstall or reinstall a protocol interface.
The agent that is opening the protocol interface is specified by AgentHandle ,
ControllerHandle , and Attributes . If the protocol interface can be opened, then
AgentHandle , ControllerHandle , and Attributes are added to the list of agents that
are consuming the protocol interface specified by Handle and Protocol . In addition, the
protocol interface is returned in Interface , and EFI_SUCCESS is returned. If Attributes
is TEST_PROTOCOL , then Interface is optional, and can be NULL .
There are a number of reasons that this function call can return an error. If an error is returned, then
AgentHandle , ControllerHandle , and Attributes are not added to the list of agents
consuming the protocol interface specified by Handle and Protocol , and Interface is
returned unmodified. The following is the list of conditions that must be checked before this
function can return
EFI_SUCCESS .
If Protocol is NULL , then EFI_INVALID_PARAMETER is returned.
If Interface is NULL and Attributes is not TEST_PROTOCOL , then
EFI_INVALID_PARAMETER is returned.
If Handle is not a valid EFI_HANDLE , then EFI_INVALID_PARAMETER is returned.
If Handle does not support Protocol , then EFI_UNSUPPORTED is returned.
If Attributes is not a legal value, then EFI_INVALID_PARAMETER is returned. The legal
values are listed in “Related Definitions.”
If Attributes is BY_CHILD_CONTROLLER , BY_DRIVER , EXCLUSIVE , or
BY_DRIVER|EXCULSIVE , and AgentHandle is not a valid EFI_HANDLE , then
EFI_INVALID_PARAMETER is returned.
If Attributes is BY_CHILD_CONTROLLER , BY_DRIVER , or BY_DRIVER|EXCULSIVE ,
and ControllerHandle is not a valid EFI_HANDLE , then EFI_INVALID_PARAMETER
is returned.
If Attributes is BY_CHILD_CONTROLLER and Handle is identical to
ControllerHandle , then EFI_INVALID_PARAMETER is returned.