PROTOCOL_CL_OPEN_AF_COMPLETE_EX - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// ndis.h
PROTOCOL_CL_OPEN_AF_COMPLETE_EX ProtocolClOpenAfCompleteEx;
VOID ProtocolClOpenAfCompleteEx(
[in] NDIS_HANDLE ProtocolAfContext,
[in] NDIS_HANDLE NdisAfHandle,
[in] NDIS_STATUS Status
)
{...}
View the official Windows Driver Kit DDI referenceNo description available.
The ProtocolClOpenAfCompleteEx function completes the opening of an address family (AF) that was started when a CoNDIS client called the NdisClOpenAddressFamilyEx function.
Note You must declare the function by using the PROTOCOL_CL_OPEN_AF_COMPLETE_EX type. For more information, see the following Examples section.
ProtocolAfContext [in]A client-supplied handle to its context area for an address AF. The client allocated this context area and passed this handle to NDIS in its call to the NdisClOpenAddressFamilyEx function.
NdisAfHandle [in]An NDIS-supplied handle to an AF, if Status is NDIS_STATUS_SUCCESS. Otherwise, this parameter is NULL. This handle represents an association that NDIS established between the client and a call manager that is bound to a CoNDIS miniport adapter. If the handle is not NULL, the client must save the handle for use in subsequent calls to NdisCl*Xxx* and NdisCo*Xxx* functions.
Status [in]The final status of the client's call to NdisClOpenAddressFamilyEx, which can be any of the following:
The AF has been opened, so the client can initialize its state at ProtocolAfContext and use the returned handle from NdisAfHandle in subsequent calls to NdisCl*Xxx* and NdisCo*Xxx* functions, such as NdisCoOidRequest.
The requested operation failed because NDIS or the call manager could not allocate sufficient memory or initialize the state that one of them uses to track the client's open of the AF that ProtocolAfContext specifies.
NDIS failed the call, possibly for one of the following reasons:
The ProtocolClOpenAfCompleteEx function is required for CoNDIS clients. CoNDIS clients must provide ProtocolClOpenAfCompleteEx to complete the asynchronous operations that the clients initiate by calling the NdisClOpenAddressFamilyEx function.
NDIS calls ProtocolClOpenAfCompleteEx to indicate that some or all of the following have occurred:
If the client's attempt to open an AF fails, NDIS cleans up its saved state before calling ProtocolClOpenAfCompleteEx. In this case, ProtocolClOpenAfCompleteEx can release the resources that the client allocated for its call to NdisClOpenAddressFamilyEx or prepare them for reuse.
Otherwise, ProtocolClOpenAfCompleteEx should set up whatever client-determined state the client will need for subsequent operations on the newly opened AF. In particular, the client must save the handle from the NdisAfHandle parameter, typically in the client's ProtocolAfContext context area.
If the client accepts incoming calls, it might allocate a per-service access point (SAP) state area and call the NdisClRegisterSap function. If the client makes outgoing calls, it might allocate a per-virtual connection (VC) state area and create a VC with the NdisCoCreateVc function to prepare for an incoming request from one of the client's own clients to make an outgoing call to a remote node.
NDIS calls ProtocolClOpenAfCompleteEx at IRQL = PASSIVE_LEVEL.
To define a ProtocolClOpenAfCompleteEx function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.
For example, to define a ProtocolClOpenAfCompleteEx function that is named "MyClOpenAfCompleteEx", use the PROTOCOL_CL_OPEN_AF_COMPLETE_EX type as shown in this code example:
PROTOCOL_CL_OPEN_AF_COMPLETE_EX MyClOpenAfCompleteEx;
Then, implement your function as follows:
_Use_decl_annotations_
VOID
MyClOpenAfCompleteEx(
NDIS_HANDLE ProtocolAfContext,
NDIS_HANDLE NdisAfHandle,
NDIS_STATUS Status
)
{...}
The PROTOCOL_CL_OPEN_AF_COMPLETE_EX function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the PROTOCOL_CL_OPEN_AF_COMPLETE_EX function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.
For information about _Use_decl_annotations_, see Annotating Function Behavior.