SET_OPTIONS 콜백 함수(ndis.h)

아티클
02/06/2022
읽는 데 7분 걸림

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는 NdisRegisterXxxDriver 함수에 대한 드라이버 호출 컨텍스트 내에서 XxxSetOptions를 호출합니다. 여기서 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를 호출하기 전에 Unbound 상태에 있습니다. 필터 드라이버의 경우 필터 모듈은 NDIS가 FilterAttach를 호출하기 전에 분리된 상태입니다.

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

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

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

예제

XxxSetOptions 함수를 정의하려면 먼저 정의하는 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows 드라이버에 대한 함수 형식 집합을 제공합니다. 함수 형식을 사용하여 함수를 선언하면 드라이버, SDV(정적 드라이버 검증 도구) 및 기타 확인 도구에 대한 Code Analysis 오류를 찾는 데 도움이 되며 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