PROTOCOL_CM_REG_SAP 콜백 함수(ndis.h)

아티클
03/01/2024

ProtocolCmRegisterSap 함수는 호출 관리자가 연결 지향 클라이언트를 대신하여 SAP(서비스 액세스 지점)를 등록하도록 요청하기 위해 NDIS에서 호출하는 필수 함수입니다.

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

구문

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

매개 변수

[in] CallMgrAfContext

호출 관리자가 열려 있는 AF별 상태를 유지하는 호출 관리자 할당 컨텍스트 영역에 대한 핸들을 지정합니다. 호출 관리자는 ProtocolCmOpenAf 함수에서 이 핸들을 NDIS에 제공했습니다.

[in] Sap

연결 지향 클라이언트가 등록하는 특정 SAP를 포함하는 미디어별 CO_SAP 구조체에 대한 포인터입니다.

[in] NdisSapHandle

이 SAP를 고유하게 식별하는 NDIS에서 제공하는 핸들을 지정합니다. 이 핸들은 호출 관리자에 대해 불투명하며 NDIS 라이브러리 사용을 위해 예약되어 있습니다.

[out] CallMgrSapContext

반환 시 호출 관리자가 이 SAP에 대한 상태를 유지하는 호출 관리자 제공 컨텍스트 영역에 대한 핸들을 지정합니다.

반환 값

ProtocolCmRegisterSap은 작업의 상태 다음 중 하나로 반환합니다.

반환 코드	설명
NDIS_STATUS_SUCCESS	호출 관리자가 SAP를 등록하고 유지 관리하는 데 필요한 리소스를 성공적으로 할당 및/또는 초기화했음을 나타냅니다. 또한 호출 관리자가 지원하는 네트워크 미디어에서 요구하는 대로 SAP가 성공적으로 등록되었음을 나타냅니다.
NDIS_STATUS_PENDING	호출 관리자가 이 요청의 처리를 비동기적으로 완료했음을 나타냅니다. 통화 관리자가 호출해야 합니다. NdisCmRegisterSapComplete 모든 처리가 완료된 경우 등록이 완료되었음을 NDIS에 알릴 수 있습니다.
NDIS_STATUS_RESOURCES	호출 관리자가 연결 지향 클라이언트를 대신하여 SAP를 등록하는 데 필요한 리소스를 할당 및/또는 초기화할 수 없음을 나타냅니다.
NDIS_STATUS_INVALID_DATA	Sap에 제공된 사양이 잘못되었거나 지원될 수 없음을 나타냅니다.
NDIS_STATUS_XXX	연결 지향 클라이언트에 SAP를 등록하려고 할 때 호출 관리자가 오류가 발생했음을 나타냅니다. 반환 코드는 오류에 적합하며 다른 NDIS 라이브러리 함수에서 전파된 반환 코드일 수 있습니다.

설명

ProtocolCmMakeCall은 필요에 따라 네트워크 제어 디바이스 또는 기타 미디어 관련 에이전트와 통신하여 SAP에 지정된 대로 연결 지향 클라이언트에 대한 네트워크에서 SAP를 등록합니다. 이러한 작업에는 하드웨어 전환, 네트워크 제어 스테이션과의 통신 또는 네트워크 매체에 적합한 기타 작업과 통신하는 것이 포함될 수 있지만 이에 국한되지는 않습니다.

호출 관리자가 네트워킹 제어 에이전트(즉, 네트워크 스위치)와 통신해야 하는 경우 ProtocolBindAdapterEx 함수에서 설정한 네트워크 제어 에이전트에 대한 가상 연결을 사용해야 합니다. 독립 실행형 통화 관리자는 NdisCoSendNetBufferLists를 호출하여 기본 미니포트 드라이버를 통해 통신합니다. 통합 통화 관리 지원이 있는 미니포트 드라이버는 NdisCoSendNetBufferLists를 호출하지 않습니다. 대신 네트워크를 통해 직접 데이터를 전송합니다.

또한 ProtocolCmRegisterSap 은 호출 관리자가 연결 지향 클라이언트를 대신하여 SAP에 대한 상태 정보를 유지하는 데 필요한 동적 리소스 및 구조의 필요한 할당을 수행해야 합니다. 이러한 리소스에는 메모리 버퍼, 데이터 구조, 이벤트 및 기타 유사한 리소스가 포함되지만 이에 국한되지는 않습니다. 또한 호출 관리자는 컨트롤을 NDIS로 반환하기 전에 할당하는 모든 리소스를 초기화해야 합니다. 통화 관리자는 나중에 사용할 수 있도록 NdisSapHandle에 제공된 SAP를 식별하는 NDIS 제공 핸들을 컨텍스트 영역에 저장해야 합니다.

ProtocolCmRegisterSap이 NDIS_STATUS_SUCCESS 반환하는 경우 SAP별 상태 영역을 할당한 후 제어를 NDIS로 반환하기 전에 CallMgrSapContext에서 이 상태 영역의 주소를 설정해야 합니다. 이렇게 하려면 CallMgrSapContext 를 역참조하고 데이터 영역에 대한 포인터를 핸들 값으로 저장합니다. 예를 들면 다음과 같습니다.

*CallMgrSapContext = SomeBuffer ;

다른 연결 지향 클라이언트에 의해 이미 등록된 지정된 SAP인 경우 호출 관리자는 요청에 실패하고 NDIS_STATUS_INVALID_DATA 반환해야 합니다.

통화 관리자가 연결 지향 클라이언트를 대신하여 SAP를 등록한 후에는 호출을 통해 해당 SAP로 전달되는 수신 호출 제안의 클라이언트에 알 수 있습니다. NdisCmDispatchIncomingCall.

예

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

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

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

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

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

요구 사항

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