ProtocolCoRequest

The ProtocolCoRequest function is required. This function handles OID_CO_XXX requests initiated by calls to NdisCoRequest from the corresponding client(s) or stand-alone call manager or initiated by an MCM driver's calls to NdisMCmRequest.

NDIS_STATUS
  ProtocolCoRequest(
    IN NDIS_HANDLE  ProtocolAfContext,
    IN NDIS_HANDLE  ProtocolVcContext  OPTIONAL, 
    IN NDIS_HANDLE  ProtocolPartyContext  OPTIONAL, 
    IN OUT  PNDIS_REQUEST  NdisRequest
    );

Parameters

ProtocolAfContext

Specifies the handle to the driver's per-AF context area. The client supplied this handle when it called NdisClOpenAddressFamily to connect itself to the call manager. The call manager supplied this handle from its ProtocolCmOpenAf function, so this handle effectively identifies the particular client that issued this request.

ProtocolVcContext

Specifies the handle identifying the active VC for which the client or call manager is requesting or setting information if the request is VC-specific. Otherwise, this parameter is NULL.

ProtocolPartyContext

Specifies the handle identifying the party on a multipoint VC for which the client or call manager is requesting or setting information if the request is party-specific. Otherwise, this parameter is NULL.

NdisRequest

Pointer to a buffer, formatted as an NDIS_REQUEST structure specifying the operation to be carried out by ProtocolCoRequest. The Oid member of the NDIS_REQUEST structure contains the system-defined OID_GEN_CO_XXX code specifying the requested query or set operation, together with a buffer in which the protocol returns the requested information for a query or from which it transfers the given information for a set.

Return Value

ProtocolCoRequest can return one of the following:

NDIS_STATUS_SUCCESS

The client or call manager carried out the requested operation.

NDIS_STATUS_PENDING

The client or call manager is handling this request asynchronously, and it will call NdisCoRequestComplete (or, from a miniport driver with integrated call-management support, NdisMCmRequestComplete) when the requested operation is done.

NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT

The driver is failing this request because the caller of NdisCoRequest or NdisMCmRequest did not supply an adequate InformationBuffer for the given request. The driver set the BytesNeeded member in the buffer at NdisRequest to the Oid-specific value of the InformationBufferLength required to carry out the requested operation.

NDIS_STATUS_XXX

The client or call manager failed the request for some driver-determined reason, such as invalid input data specified for a set.

NDIS_STATUS_NOT_SUPPORTED

The client or call manager failed this request because it did not recognize the OID_GEN_CO_XXX code in the Oid member in the buffer at NdisRequest.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

Connection-oriented clients and stand-alone call managers communicate information to each other by specifying an explicit NdisAfHandle when they call NdisCoRequest. Similarly, a connection-oriented miniport driver with integrated call-management support calls NdisMCmRequest with explicit NdisAfHandles to communicate information to its individual clients. Such a call to NdisCoRequest or NdisMCmRequest with an explicit NdisAfHandle causes NDIS to call the ProtocolCoRequest function of the client, stand-alone call manager, or MCM driver that shares the given NdisAfHandle.

If the input NdisVcHandle and NdisPartyHandle are NULL, ProtocolCoRequest can consider the request global in nature. For example, ProtocolCoRequest satisfies any OID_GEN_CO_XXX query for which it is passed only an explicit NdisAfHandle by returning information about all currently active VCs, including any active multipoint VCs, on the given address family.

An explicit NdisVcHandle or NdisPartyHandle indicates that ProtocolCoRequest should satisfy the given request on a per-VC or per-party basis, respectively.

ProtocolCoRequest can assume that the buffer at NdisRequest was allocated from nonpaged pool and is, therefore, accessible at raised IRQL. The caller of NdisCoRequest (or NdisMCmRequest) is responsible for releasing this buffer and the internal buffer at InformationBuffer that it allocated when its request has been completed.

If ProtocolCoRequest returns NDIS_STATUS_PENDING, the driver must make a subsequent call to NdisCoRequestComplete or, for an MCM driver, to NdisMCmRequestComplete when the driver completes its operations to satisfy the given request.

For more information about the sets of OIDs defined for use with NdisCoRequest, NdisMCmRequest, and NdisRequest, see NDIS Object Identifiers.

ProtocolCoRequest must be written so that it can run at IRQL = DISPATCH_LEVEL.

See Also

NdisClOpenAddressFamily, NdisCoRequest, NdisCoRequestComplete, NdisMCmRequest, NdisMCmRequestComplete, NdisRequest, NDIS_REQUEST, ProtocolCmOpenAf, ProtocolCoRequestComplete