ProtocolSetOptions routine

NDIS calls a protocol driver's ProtocolSetOptions function to allow the protocol driver to register optional services.

Note  You must declare the function by using the SET_OPTIONS type. For more information, see the following Examples section.

Syntax


SET_OPTIONS ProtocolSetOptions;

NDIS_STATUS ProtocolSetOptions(
  _In_  NDIS_HANDLE NdisDriverHandle,
  _In_  NDIS_HANDLE DriverContext
)
{ ... }

Parameters

NdisDriverHandle [in]

A handle that identifies a protocol driver. NDIS returns this handle to the protocol driver when it returns from the NdisRegisterProtocolDriver function.

DriverContext [in]

The handle that the driver passed to NdisRegisterProtocolDriver that identifies the driver context area.

Return value

ProtocolSetOptions returns one of the following status values:

Return codeDescription
NDIS_STATUS_SUCCESS

ProtocolSetOptions successfully registered the protocol driver's optional services and resources.

NDIS_STATUS_RESOURCES

ProtocolSetOptions could not allocate the resources that the protocol driver requires.

NDIS_STATUS_XXX or NTSTATUS_XXX

The protocol driver's attempt to register options failed. Usually, such an error status is propagated from an NdisXxx function or a kernel-mode support routine.

 

Remarks

ProtocolSetOptions is an optional function. NDIS calls ProtocolSetOptions within the context of the protocol driver's call to the NdisRegisterProtocolDriver function.

ProtocolSetOptions registers optional services and can allocate other driver resources. To register optional ProtocolXxx functions, the protocol driver calls the NdisSetOptionalHandlers function. The protocol driver passes the handle from the NdisDriverHandle parameter at the NdisHandle parameter of NdisSetOptionalHandlers and passes a characteristics structure at the OptionalHandlers parameter.

The optional services are defined in the following structures:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS can call the protocol driver's other ProtocolXxx functions at any time after ProtocolSetOptions returns. The driver should be prepared to be called back at the ProtocolBindAdapterEx function. The protocol bindings are in the Unbound state before the NDIS calls ProtocolBindAdapterEx.

If an attempt to allocate resources or services fails, ProtocolSetOptions should undo all the allocations that succeeded before it returns control with a status other than NDIS_STATUS_SUCCESS.

NDIS calls ProtocolSetOptions at IRQL = PASSIVE_LEVEL.

Examples

To define a ProtocolSetOptions function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a ProtocolSetOptions function that is named "MySetOptions", use the SET_OPTIONS type as shown in this code example:


SET_OPTIONS MySetOptions;

Then, implement your function as follows:


_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

The SET_OPTIONS function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the SET_OPTIONS function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

ProtocolBindAdapterEx
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS
NDIS_CO_CLIENT_OPTIONAL_HANDLERS
NDIS_PROTOCOL_CO_CHARACTERISTICS
NdisOpenAdapterEx
NdisRegisterProtocolDriver
NdisSetOptionalHandlers

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft