SET_OPTIONS 콜백 함수(ndis.h)

아티클
08/07/2023

NDIS는 드라이버의 XxxSetOptions 함수를 호출하여 드라이버가 선택적 서비스를 등록할 수 있도록 합니다. 이 함수는 미니포트 드라이버의 경우 MiniportSetOptions , 프로토콜 드라이버의 경우 ProtocolSetOptions 또는 필터 드라이버의 FilterSetOptions 로 정의됩니다.

참고Xxx_SET_OPTIONS 형식을 사용하여 함수를 선언해야 합니다. 자세한 내용은 예 섹션을 참조하십시오.

구문

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

매개 변수

[in] NdisDriverHandle

드라이버를 식별하는 핸들입니다. NDIS는 드라이버 등록 함수(미니포트 드라이버의 경우 NdisMRegisterMiniportDriver , 프로토콜 드라이버의 경우 NdisRegisterProtocolDriver , 필터 드라이버의 경우 NdisFRegisterFilterDriver )에서 반환할 때 드라이버에 이 핸들을 반환합니다.

[in] DriverContext

드라이버 컨텍스트 영역을 식별하는 드라이버가 NdisRegisterXxxDriver 에 전달한 핸들입니다. 여기서 Xxx는 드라이버 유형(미니포트, 프로토콜 또는 필터)입니다.

반환 값

XxxSetOptions는 다음 상태 값 중 하나를 반환합니다.

반환 코드	설명
NDIS_STATUS_SUCCESS	XxxSetOptions는 드라이버의 선택적 서비스 및 리소스를 성공적으로 등록했습니다.
NDIS_STATUS_RESOURCES	XxxSetOptions는 드라이버에 필요한 리소스를 할당할 수 없습니다.
NDIS_STATUS_XXX 또는 NTSTATUS_XXX	드라이버의 옵션 등록 시도가 실패했습니다. 일반적으로 이러한 오류 상태 NdisXxx 함수 또는 커널 모드 지원 루틴에서 전파됩니다.

설명

XxxSetOptions 는 선택적 함수입니다. NDIS는 드라이버의 에 대한 호출 컨텍스트 내에서 XxxSetOptions 를 호출합니다. NdisRegisterXxxDriver 함수입니다. 여기서 Xxx는 드라이버 유형(미니포트, 프로토콜 또는 필터)입니다.

XxxSetOptions는 선택적 서비스를 등록하고 다른 드라이버 리소스를 할당할 수 있습니다. 선택적 MiniportXxx, ProtocolXxx 또는 FilterXxx 함수를 등록하기 위해 드라이버는 NdisSetOptionalHandlers 함수를 호출합니다 . 드라이버는 NdisSetOptionalHandlers의 NdisHandle 매개 변수에 있는 NdisDriverHandle 매개 변수의 핸들을 전달하고 OptionalHandlers 매개 변수에서 특성 구조를 전달합니다.

미니포트 드라이버는 다음 특성 구조에 정의된 선택적 서비스에 적용할 수 있습니다.

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS( NDIS 6.0 TCP 굴뚝 오프로드 설명서 참조)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS( NDIS 6.0 TCP 굴뚝 오프로드 설명서 참조)

프로토콜 드라이버는 다음 특성 구조에 정의된 선택적 서비스에 적용할 수 있습니다.

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

현재 Windows 버전에는 선택적 필터 드라이버 서비스가 없습니다.

NDIS는 XxxSetOptions가 반환된 후 언제든지 드라이버의 다른 MiniportXxx, ProtocolXxx 또는 FilterXxx 함수를 호출할 수 있습니다. 드라이버는 초기화 함수:(미니포트 드라이버의 경우 MiniportInitializeEx , 프로토콜 드라이버의 경우 ProtocolBindAdapterEx , 필터 드라이버의 경우 FilterAttach )에서 다시 호출되도록 준비해야 합니다.

미니포트 드라이버의 경우 미니포트 어댑터는 NDIS가 MiniportInitializeEx를 호출하기 전에 중지됨 상태입니다. 프로토콜 드라이버의 경우 프로토콜 바인딩은 NDIS가 ProtocolBindAdapterEx를 호출하기 전에 언바운드 상태입니다. 필터 드라이버의 경우 필터 모듈은 NDIS가 FilterAttach를 호출하기 전에 분리된 상태입니다.

리소스 또는 서비스 할당 시도가 실패하면 XxxSetOptions는 NDIS_STATUS_SUCCESS 이외의 상태 사용하여 컨트롤을 반환하기 전에 성공한 모든 할당을 실행 취소해야 합니다.

미니포트 및 필터 드라이버의 XxxDriverUnload는 XxxSetOptions에서 수행된 모든 작업을 실행 취소해야 합니다.

NDIS는 IRQL = PASSIVE_LEVEL XxxSetOptions 를 호출합니다.

예

XxxSetOptions 함수를 정의하려면 먼저 정의하려는 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 함수 형식 집합을 제공합니다. 함수 형식을 사용하여 함수를 선언하면 드라이버에 대한 코드 분석, SDV( 정적 드라이버 검증 도구 ) 및 기타 확인 도구에서 오류를 찾을 수 있으며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

Ndis.h 헤더 파일에서 SET_OPTIONS 콜백 함수는 다음과 같이 추가로 정의됩니다.

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

이렇게 하면 모든 NDIS 드라이버가 동일한 구문을 사용하여 XxxSetOptions 콜백 함수를 구현할 수 있습니다. 미니포트 드라이버는 MINIPORT_SET_OPTIONS 형식을 사용하고, 프로토콜 드라이버는 PROTOCOL_SET_OPTIONS 형식을 사용하고, 필터 드라이버는 FILTER_SET_OPTIONS 형식을 사용합니다.

예를 들어 " MySetOptions"라는 MiniportSetOptions 함수를 정의하려면 다음 코드 예제와 같이 MINIPORT_SET_OPTIONS 형식을 사용합니다.

MINIPORT_SET_OPTIONS MySetOptions;

그런 다음 다음과 같이 함수를 구현합니다.

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

SET_OPTIONS 함수 형식은 Ndis.h 헤더 파일에 정의되어 있습니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 Use_decl_annotations 주석을 추가해야 합니다. Use_decl_annotations 주석은 헤더 파일의 SET_OPTIONS 함수 형식에 적용되는 주석이 사용되도록 합니다. 함수 선언 요구 사항에 대한 자세한 내용은 NDIS 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요.

Use_decl_annotations 대한 자세한 내용은 함수 동작 주석 지정을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	NDIS 6.0 이상에서 지원됩니다.
대상 플랫폼	Windows
헤더	ndis.h(Ndis.h 포함)
IRQL	PASSIVE_LEVEL