Filter
Top Products
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,andAttributes. If the protocol interface can be opened, then
AgentHandle, ControllerHandle,andAttributes 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,andEFI_SUCCESS is returned. If Attributes
is TEST_PROTOCOL,thenInterface 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,andAttributes are not added to the list of agents
consuming the protocol interface specified by Handle and Protocol,andInterface 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,thenEFI_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,thenEFI_INVALID_PARAMETER is returned.
If Handle does not support Protocol,thenEFI_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,andAgentHandle is not a valid EFI_HANDLE,then
EFI_INVALID_PARAMETER is returned.
If Attributes is BY_CHILD_CONTROLLER, BY_DRIVER,orBY_DRIVER|EXCULSIVE,
and ControllerHandle is not a valid EFI_HANDLE,thenEFI_INVALID_PARAMETER
is returned.
If Attributes is BY_CHILD_CONTROLLER and Handle is identical to
ControllerHandle,thenEFI_INVALID_PARAMETER is returned.