OID_WW_GEN_INDICATION_REQUEST

  • Article

The OID_WW_GEN_INDICATION_REQUEST OID notifies the underlying miniport driver to place the specified indication request on its event queue.

This OID allows bound protocols to register themselves to be notified of changes associated with particular wireless OIDs. Such a protocol passes an NDIS_WW_INDICATION_REQUEST structure, defined below, to NdisRequest that specifies an OID_WW_XXX code and, for some OID codes, a trigger value. On return from such an OID_WW_GEN_INDICATION_REQUEST, the current value of the specified OID code will be in the InitialValue member, unless otherwise stated in the definition for the OID_WW_XXX specified in the Oid member.

Because a miniport driver calls NdisMIndicateStatus to indicate status related to an OID to every bound protocol, this miniport driver must maintain its own copy of the NDIS_WW_INDICATION_REQUEST structure for the request. This miniport driver can free this structure after NdisMIndicateStatus returns. A miniport driver maintains its own copy of this structure for the following reason. After a protocol receives notification of an event related to an OID for which the protocol registered, the protocol releases its own indication-request structure. Because the miniport driver has its own copy of this structure, its copy remains valid. Therefore, other bound protocols will also receive valid status related to the OID.

The NDIS_WW_INDICATION_REQUEST structure is defined as follows:

    typedef struct _NDIS_WW_INDICATION_REQUEST {
         NDIS_OID Oid;
         UINT uIndicationFlag;
         UINT uApplicationToken;
         HANDLE hIndicationHandle;
         INT iPollingInterval;
         NDIS_VAR_DATA_DESC InitialValue;
         NDIS_VAR_DATA_DESC OIDIndicationValue;
         NDIS_VAR_DATA_DESC TriggerValue;
 
    } NDIS_WW_INDICATION_REQUEST;

The members of this structure contain the following information:

  • Oid
    The OID_WW_XXX code for which the miniport driver should indicate events.

    A protocol sets this member.

  • uIndicationFlag
    Specifies a bitmask in which one of the following flags can be set:

    • OID_INDICATION_REQUEST_ENABLE
      The miniport driver should call NdisMIndicateStatus if the event specified in this structure occurs.

    • OID_INDICATION_REQUEST_CANCEL
      The miniport driver should cancel notifications for the specified event. The values supplied in the Oid and hIndicationHandle members must match the values specified in a preceding OID_WW_GEN_INDICATION_REQUEST.

    All other bits in uIndicationFlag are reserved for future use.

    A protocol sets this member.

  • uApplicationToken
    Specifies an application-defined (or protocol-defined) token that is returned by the miniport driver when it posts the specified event. The miniport driver must copy this member during indication-request operations prior to placing the event on the driver's internal event queue. The miniport driver does so to ensure that the requesting protocol can correctly demulitplex the specified indication event.

    The miniport driver ignores this member during cancel operations.

    A protocol sets this member.

  • hIndicationHandle
    Specifies a miniport driver-determined handle. The protocol or application will save this handle and possibly use it to cancel this request subsequently (see uIndicationFlag). The miniport driver must initialize this member during indication-request operations prior to placing the event on the driver's internal event queue. The miniport driver does so to ensure that the requesting protocol can correctly demulitplex the specified indication event.

    This member is returned by the miniport driver or is set by a protocol to cancel.

  • iPollingInterval
    Specifies an interval, in milliseconds, at which the miniport driver should poll the wireless NIC to monitor the value of the given OID.

    If this member is set to -1, the miniport driver should use its own default settings to poll the device. Before returning, the miniport driver must set this member to the actual polling interval, in milliseconds, it will use for this indication. This allows the protocol or application to determine if the miniport driver is sampling the OID too often. The protocol or application can then possibly cancel its original request and make another request that requires the miniport driver to poll the NIC at a more appropriate interval. The returned value may be larger or smaller than the value that the protocol or application specifies.

    The miniport driver ignores this member during cancel operations.

    This member is set by a protocol and is returned by the miniport driver.

  • InitialValue
    On input, a NDIS_VAR_DATA_DESC-type buffer that can contain information necessary to initialize the requested notification, for instance, as in the case of OID_WW_GEN_CURRENT_ADDRESS. The miniport driver sets information about the current value of the specified OID in this buffer before returning. This same value is also returned by the miniport driver through its call to NdisMIndicateStatus after the actual indication event is triggered.

    The miniport driver ignores this member during cancel operations.

    This member is set by a protocol and is returned by the miniport driver.

  • OIDIndicationValue
    On input, contains an initialized NDIS_VAR_DATA_DESC-type buffer. The protocol must initialize at least the MaximumLength member of OIDIndicationValue during the indication request so that the miniport driver can determine if its response will fit in the protocol's buffer. Before the miniport driver makes the event notification, it allocates a NDIS_VAR_DATA_DESC-type buffer to contain the value of the specified OID, and fills in its copy of the NDIS_WW_INDICATION_REQUEST structure.

    A protocol can reference the miniport-allocated buffer only during the status indication of the event. The allocating driver can deallocate this buffer and release all resources necessary to trigger the event on return from its call to NdisMIndicateStatus with this event.

    The miniport driver ignores this member during cancel operations.

    Only the MaximumLength member of OIDIndicationValue is verified by the miniport driver at the time of the request. The other members of OIDIndicationValue are assigned by the miniport driver and only valid during the event notification.

  • TriggerValue
    On input, specifies a NDIS_VAR_DATA_DESC-type buffer containing a value that the underlying miniport driver might use to determine when to indicate the specified event. The value of this member can be NULL depending on the specific OID code for which a protocol requests notification. If the value of this member is NULL, the miniport driver can ignore it. For example, the miniport driver can ignore this member for OID codes that trigger on a change in status. For more information, see the descriptions of individual OID_WW_XXX codes. The miniport driver ignores this member during cancel operations.

The miniport driver must fill in the InitialValue and iPollingInterval members in both the protocol's and miniport driver's copy of the given structure with the state of the miniport driver's current information. After the requested OID has reached the trigger value or after status related to the OID changes, the miniport driver fills in the OIDIndicationValue member in its copy of this structure. The protocol that initiates this request cannot access anything in the NDIS_WW_INDICATION_REQUEST structure it allocated until ownership is returned to the protocol. The protocol can easily determine if it again owns this structure by validating that the status that NdisRequestreturns is not NDIS_STATUS_PENDING. Also, the status that is returned from OID_WW_GEN_INDICATION_REQUEST only indicates the successful queuing or canceling of the event by the miniport driver and is not indicative of the actual event firing.

After event notifications for a particular OID have been enabled by this request, a wireless WAN miniport driver should fill in the appropriate information and call NdisMIndicateStatuswith NDIS_STATUS_WW_INDICATION to notify NDIS, which forwards such a notification to all bound protocols, according to the following guidelines:

  • For OID_WW_GEN_XXX codes that use the TriggerValue:
    • While InitialValue < TriggerValue, the miniport driver continues to monitor for the specified condition. It posts such an event when the present value for the OID becomes >= the given TriggerValue.
    • If InitialValue = TriggerValue, the miniport driver fills in remaining information in the given structure and calls NdisMIndicateStatus to post the event immediately.
    • If InitialValue > TriggerValue, the miniport driver should post the event when the present value for the OID becomes <= TriggerValue.
    • If InitialValue is unknown, an event is posted after the current value of the OID changes to a value other than unknown.
  • For OID_WW_XXX codes that do not use the TriggerValue: The miniport driver should post the event when a status change occurs, as described for that OID_WW_XXX.

After a requested event is posted, the calling protocol must submit another indication request to receive another NDIS_STATUS_WW_INDICATION event. Due to the asynchronous nature of calls to NdisRequest, a protocol writer should be aware that the requested event could be posted prior to the return of a call to NdisRequestwith OID_WW_GEN_INDICATION_REQUEST. The uApplicationToken member can be used to facilitate demultiplexing of each such event.

Any attempt to cancel an OID_WW_GEN_INDICATION_REQUEST that has already occurred can be ignored by the underlying driver.

Many OID_WW_GEN_INDICATION_REQUESTs can be outstanding for a particular OID. Making several calls to NdisRequestwith this OID can establish several trigger points. When one of several OID_WW_GEN_INDICATION_REQUESTs causes an event notification, only that trigger is canceled, but all other OID_WW_GEN_INDICATION_REQUESTs remain enabled.

NDIS delivers a miniport driver's event indications to every protocol that is bound to that underlying driver serially. Consequently, NIC drivers must copy the contents of the indication request. A NIC driver must fill in the hIndicationHandle value prior to scheduling the request on its internal event queue and returning from the call to its set-information routine. This ensures that bound protocol(s) can detect their own respective event notifications when they occur. Consequently, a miniport driver should set a value in hIndicationHandle that is unique each time it processes this request, such as a monotonically increasing 32-bit value (transaction ID), to ensure that collisions do not occur. The value for this member can be reset to zero every time the miniport driver initializes.

When a miniport driver indicates an event for this OID, it must pass a pointer to its copy of the indication request as the Statusparameter when it calls NdisMIndicateStatus. Bound protocol drivers that receive the indication must copy the indicated information into their own internal buffer space, assuming any particular protocol determines that the hIndicationHandle value indicates an event of interest to that protocol.

As a general rule, every protocol should check the hIndicationHandle value when an event notification is made and return control as soon as each protocol's ProtocolStatusfunction determines the indicated event is not of interest. Otherwise, the effect of notifying all bound protocols of miniport driver-indicated events is a degradation in performance for the miniport driver and for all bound protocols.

Event data is guaranteed to be valid only until a ProtocolStatusfunction returns control. On return from NdisMIndicateStatus, the indicating miniport driver can release all context for the specified event.

Queries and indications are irrelevant for this OID.

Note   This OID is not available for use beginning with Windows Vista.

 

 

 

Send comments about this topic to Microsoft