FilterRestart (Compact 7)

3/12/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.

• FilterRestartParameters
  A pointer to an NDIS_FILTER_RESTART_PARAMETERS structure that defines the restart parameters for the filter module.

Return Value

FilterRestart returns one of the following status values:

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

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