Partager via

FilterRestart (Compact 2013)

  • Article

3/26/2014

This function initiates a restart operation for the specified filter module.

Syntax

NDIS_STATUS
  FilterRestart(
    IN NDIS_HANDLE  FilterModuleContext,
    IN PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    );

Parameters

  • FilterModuleContext
    A handle to the context area for the filter module that the filter driver should restart. The filter driver created and initialized this context area in the FilterAttach function.

Return Value

FilterRestart returns one of the following status values:

Value

Description

NDIS_STATUS_SUCCESS

FilterRestart successfully restarted the specified filter module.

NDIS_STATUS_PENDING

The filter driver will complete the request asynchronously with a call to the NdisFRestartComplete function after it completes the restart operation.

NDIS_STATUS_RESOURCES

FilterRestart failed because of insufficient resources.

NDIS_STATUS_FAILURE

None of the previous status values applies. The filter driver should call the NdisWriteEventLogEntry function together with parameters that specify the reason for the failure.

Remarks

FilterRestart is a required function for filter drivers. NDIS can call FilterRestart when a filter module is in the Paused state. The filter module enters the Restarting state at the start of the execution of FilterRestart.

When NDIS calls FilterRestart, a filter driver must perform these actions:

  • Complete the operations that are required to restart typical send and receive operations
  • Optionally read or write configuration parameters
  • Optionally reallocate buffer pools
  • Optionally modify the restart attributes that are specified in the RestartAttributes member of the NDIS_FILTER_RESTART_PARAMETERS structure. If the pointer in RestartAttributes is NULL, the filter driver should not modify or add to the restart attributes list. If the pointer in RestartAttributes is non-NULL, it points to the first NDIS_RESTART_ATTRIBUTES structure in the list of restart attributes. If a filter driver does not restart, it should not modify any attributes.
  • Optionally use OID requests to query or set information in the underlying drivers. Filter drivers should not issue OID requests for information that is already provided in the list of restart attributes.
  • Return NDIS_STATUS_SUCCESS or a failure status.

If a filter driver modifies the list of restart attributes, the filter driver:

  • Should not modify any media-specific attributes if it does not recognize the OID in the Oid member of the NDIS_RESTART_ATTRIBUTES structure.
  • Can add new media-specific attributes to the list of restart attributes. In this situation, the filter driver must allocate a new NDIS_RESTART_ATTRIBUTES structure-for example, with the NdisAllocateMemoryWithTagPriority function-and provide memory space for the new attributes. After propagating the restart attributes to overlying drivers, NDIS frees the attributes memory for filter drivers.
  • Can modify the media-specific attributes in the list of restart attributes. If the filter driver requires more memory space, it can free the NDIS_RESTART_ATTRIBUTES structure with the NdisFreeMemory function and allocate a new structure to contain the modified information. After propagating the restart attributes to overlying drivers, NDIS frees the attributes memory for filter drivers.
  • Should, if the Oid member in the NDIS_RESTART_ATTRIBUTES structure is OID_GEN_MINIPORT_RESTART_ATTRIBUTES, make sure that the NDIS_RESTART_GENERAL_ATTRIBUTES structure contains the information that the filter driver requires. To make sure that the NDIS_RESTART_GENERAL_ATTRIBUTES structure contains the required information, you should check the Revision member in the NDIS_OBJECT_HEADER structure that is specified in the Header member of the NDIS_RESTART_GENERAL_ATTRIBUTES structure.
    Note   A filter driver can modify any member in the NDIS_RESTART_GENERAL_ATTRIBUTES structure. If some attributes that the filter driver should modify are not included in the revision of the structure that NDIS provided, the filter driver should rely on overlying drivers to issue OID requests for the missing attributes. The filter driver can modify the attributes when it completes the OID request.
  • If the filter driver changes restart attributes, must provide a FilterOidRequest function. The filter driver must ensure that the information that overlying drivers receive in the restart attributes is consistent with the information that they receive in response to OID requests.

After the filter driver returns its status or calls the NdisFRestartComplete function, the restart operation is complete. If the operation completed successfully, the filter module is in the Running state and typical send and receive processing is resumed. If the restart operation failed, the filter module returns to the Paused state.

NDIS calls FilterRestart at IRQL = PASSIVE_LEVEL.

Requirements

Header

filter.h

See Also

Reference

NDIS Filter Driver Functions
FilterAttach
FilterOidRequest
FilterStatus
NDIS_FILTER_RESTART_PARAMETERS
NDIS_OBJECT_HEADER
NDIS_RESTART_ATTRIBUTES
NDIS_RESTART_GENERAL_ATTRIBUTES
NDIS_STATUS_LINK_STATE
NdisAllocateMemoryWithTagPriority
NdisFreeMemory
NdisFRegisterFilterDriver
NdisFRestartComplete
OID_GEN_LINK_STATE
OID_GEN_MINIPORT_RESTART_ATTRIBUTES