PROTOCOL_CO_CREATE_VC 콜백 함수(ndis.h)

아티클
08/07/2023

ProtocolCoCreateVc 함수는 호출 관리자 또는 클라이언트가 VC(가상 연결)를 활성화하고 유지하는 데 필요한 리소스를 할당하는 필수 함수입니다.

참고PROTOCOL_CO_CREATE_VC 형식을 사용하여 함수를 선언해야 합니다. 자세한 내용은 다음 예제 섹션을 참조하세요.

구문

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

매개 변수

[in] ProtocolAfContext

호출 관리자 또는 클라이언트가 열려 있는 상태를 유지하는 프로토콜 할당 컨텍스트 영역에 대한 핸들을 지정합니다. 호출 관리자는 ProtocolCmOpenAf 함수에서 이 핸들을 제공했습니다. 클라이언트는 ProtocolCoAfRegisterNotify 함수에서 NdisClOpenAddressFamilyEx를 호출할 때 이 핸들을 제공했습니다.

[in] NdisVcHandle

이 가상 연결을 고유하게 식별하는 NDIS에서 제공하는 핸들을 지정합니다. 이 핸들은 프로토콜 드라이버에 대해 불투명하며 NDIS 라이브러리 사용을 위해 예약되어 있습니다. 그러나 호출 관리자와 클라이언트는 이 VC와 관련된 NdisCo/Cl/Cm/MCmXxx 함수에 대한 후속 호출을 전달하려면 이 핸들을 저장해야 합니다.

[out] ProtocolVcContext

호출 관리자 또는 클라이언트가 이 가상 연결에 대한 상태를 유지하는 프로토콜 제공 컨텍스트 영역에 대한 핸들을 지정합니다.

반환 값

ProtocolCoCreateVc는 작업의 상태 다음 값 중 하나로 반환합니다.

반환 코드	설명
NDIS_STATUS_SUCCESS	호출 관리자 또는 클라이언트가 가상 연결을 설정하고 유지하는 데 필요한 모든 리소스를 성공적으로 할당 및/또는 초기화했음을 나타냅니다.
NDIS_STATUS_RESOURCES	호출 관리자 또는 클라이언트가 가상 연결을 설정하고 유지 관리하기 위해 리소스를 할당 및/또는 초기화할 수 없음을 나타냅니다.
NDIS_STATUS_XXX	호출 관리자 또는 클라이언트가 가상 연결을 설정할 수 있는 상태로 자신을 설정할 수 없음을 나타냅니다. 다른 NDIS 라이브러리 루틴에서 전파되는 오류 반환 값일 수 있습니다. 참고 호출 관리자 또는 클라이언트는 ProtocolCoCreateVc 함수에서 NDIS_STATUS_PENDING 반환할 수 없습니다. 보류 중이면 이 가상 연결을 사용할 수 없게 되며 NDIS 라이브러리는 클라이언트 또는 호출 관리자를 호출하여 삭제합니다.

설명

호출 관리자 또는 클라이언트의 ProtocolCoCreateVc 함수는 해당 클라이언트 또는 호출 관리자가 각각 NdisCoCreateVc를 호출할 때마다 호출됩니다. 클라이언트는 NdisClMakeCall을 호출하기 전에 발신 호출을 설정하는 과정에서 VC 만들기를 시작합니다. 호출 관리자는 CM이 CM을 호출하기 전에 해당 클라이언트에 의해 CM에 이미 등록된 SAP로 전달된 원격 노드에서 수신 호출 제안을 수신했음을 클라이언트에 알리는 프로세스에서 VC 만들기를 시작합니다. NdisCmDispatchIncomingCall.

ProtocolCoCreateVc 는 호출 관리자 또는 클라이언트가 활성화될 VC에서 후속 작업을 수행하는 데 필요한 동적 리소스 및 구조의 필요한 할당을 수행합니다. 이러한 리소스에는 메모리 버퍼, 데이터 구조, 이벤트 및 기타 유사한 리소스가 포함되지만 이에 국한되지는 않습니다. 또한 호출 관리자와 클라이언트는 호출이 설정될 때 필요한 모든 관련 VC별 구조를 초기화해야 합니다.

연결 지향 프로토콜 드라이버는 이 가상 연결에 대한 향후 작업에 사용할 VC별 상태 영역에 NdisVcHandle에 지정된 VC에 대한 핸들을 저장해야 합니다. NdisVcHandle은 이러한 연결 지향 프로토콜이 이후에 호출하는 NdisCoXxx, NdisCmXxx 및/또는 NdisClXxx에 대한 필수 매개 변수입니다.

호출 관리자 또는 클라이언트가 자체 VC별 데이터에 대한 메모리를 할당하고 상태를 초기화한 경우 컨트롤을 NDIS로 반환하기 전에 이 데이터 구조의 주소를 핸들에 설정해야 합니다. 이렇게 하려면 핸들을 역참조하고 프로토콜 할당 데이터 영역에 대한 포인터를 핸들 값으로 저장합니다. 예를 들면 다음과 같습니다.

*ProtocolVcContext = SomeBuffer;

ProtocolCoCreateVc가 후속 네트워크 I/O 작업을 수행하는 데 필요한 리소스를 할당할 수 없는 경우 이 VC에 할당된 모든 리소스를 해제하고 NDIS_STATUS_RESOURCES 상태 컨트롤을 반환해야 합니다.

ProtocolCoCreateVc가 필요한 작업을 완료하고 호출 관리자 또는 클라이언트가 이 가상 연결에 대한 호출 초기화를 수행할 준비가 된 경우 ProtocolCoCreateVc는 NDIS_STATUS_SUCCESS 상태 가능한 한 빨리 제어를 반환해야 합니다.

ProtocolCoCreateVc에 대한 호출은 본질적으로 본질적으로 동기적입니다. 즉, ProtocolCoCreateVc는 NDIS_STATUS_PENDING 반환할 수 없습니다.

호출 관리자의 ProtocolCoCreateVc 함수가 컨트롤을 반환하면 호출 관리자의 ProtocolCmMakeCall 함수가 호출되어 원격 노드에 대한 연결을 설정합니다. 호출 관리자는 연결 지향 NDIS의 다른 구성 요소에서 오류 조건으로 인해 호출이 설정되기 전에 VC가 제거될 수 있으므로 실제로 호출을 설정하는 ProtocolCmMakeCall 에서 어떠한 작업도 수행해서는 안 됩니다.

클라이언트의 ProtocolCoCreateVc 함수가 컨트롤을 반환하면 클라이언트가 이전에 등록한 SAP에서 연결하기 위한 원격 시작 요청이 네트워크를 통해 들어오면 클라이언트의 ProtocolClIncomingCall 함수가 알림을 받습니다.

예

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

예를 들어 이름이 " MyCoCreateVc"인 ProtocolCoCreateVc 함수를 정의하려면 이 코드 예제와 같이 PROTOCOL_CO_CREATE_VC 형식을 사용합니다.

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

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

Use_decl_annotations 대한 자세한 내용은 함수 동작에 주석을 추가를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista에서 NDIS 6.0 및 NDIS 5.1 드라이버(ProtocolCoCreateVc(NDIS 5.1 참조))에 대해 지원됩니다. Windows XP에서 NDIS 5.1 드라이버(ProtocolCoCreateVc(NDIS 5.1) 참조)에 대해 지원됩니다.
대상 플랫폼	Windows
헤더	ndis.h(Ndis.h 포함)
IRQL	<= DISPATCH_LEVEL