ProtocolCmOpenAf (NDIS 5.1) function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
The ProtocolCmOpenAf function is required. This function allocates per-open resources for a call manager to interact with a connection-oriented NDIS client that is opening the address family.
Syntax
NDIS_STATUS ProtocolCmOpenAf(
_In_ NDIS_HANDLE CallMgrBindingContext,
_In_ PCO_ADDRESS_FAMILY AddressFamily,
_In_ NDIS_HANDLE NdisAfHandle,
_Out_ PNDIS_HANDLE CallMgrAfContext
);
Parameters
CallMgrBindingContext [in]
Specifies the handle to a call manager-allocated context area in which the call managers maintains its per-binding state information. The call manager supplied this handle when it called NdisOpenAdapter.AddressFamily [in]
Specifies the address family that a client is opening. This address family was registered by the call manager when it called NdisCmRegisterAddressFamily.NdisAfHandle [in]
Specifies a handle, supplied by NDIS, that uniquely identifies this address family instance. This handle is opaque to the call manager and reserved for system use.CallMgrAfContext [out]
Specifies the handle to a call manager-supplied context area in which the call manager maintains state about this open of an address family it provides.
Return value
ProtocolCmOpenAf returns the status of its operation(s) as one of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | Indicates that the call manager has successfully allocated and initialized any resources necessary to accept requests from the client to this address family. |
| NDIS_STATUS_PENDING | Indicates that the requested operation is being handled asynchronously. The call manager must call NdisCmOpenAddressFamilyComplete when it has completed all its open-AF operations to indicate to NDIS (and the client) that the operation(s) has been completed. |
| NDIS_STATUS_RESOURCES | Indicates that the call manager could not complete its necessary operation(s) because of a lack of available system resources, such as memory. |
| NDIS_STATUS_XXX | Indicates that the call manager could not set itself into a state where it can accept requests from the client to operate on this address family. This could be an error status propagated from another NDIS library function or any error status determined appropriate by the driver writer. |
Remarks
ProtocolCmOpenAf performs any required allocations of dynamic resources and structures that the call manager writer deems necessary to perform operations on behalf of the client that is opening an instance of this address family. Such resources include, but are not limited to, memory buffers, data structures, events, and other such similar resources. A call manager should also initialize any relevant per-open data before returning control to NDIS.
When a call manager has allocated its per-open state area, the address of the state area should be set in the CallMgrAfContext handle before returning control to NDIS. To do this, dereference CallMgrAfContext and store a pointer to the data area as the value of the handle. For example:
*CallMgrAfContext = SomeBuffer;
If ProtocolCmOpenAf cannot allocate the per-open resources it needs to carry out subsequent requests on behalf of the client opening this address family, it should free all resources that it allocated for the open and return control to the NDIS with NDIS_STATUS_RESOURCES.
If ProtocolCmOpenAf has completed its required operations and the CM is ready to accept requests from the client, ProtocolCmOpenAf should return control as quickly as possible with a status of NDIS_STATUS_SUCCESS.
Requirements
Target platform |
Desktop |
Version |
See ProtocolCmOpenAf. |
Header |
Ndis.h (include Ndis.h) |
IRQL |
<= DISPATCH_LEVEL |
See also
NdisCmOpenAddressFamilyComplete