NdisClOpenAddressFamily

NDIS_STATUS NdisClOpenAddressFamily( IN NDIS_HANDLE NdisBindingHandle, IN PCO_ADDRESS_FAMILY AddressFamily, IN NDIS_HANDLE ProtocolAfContext, IN PNDIS_CLIENT_CHARACTERISTICS ClCharacteristics, IN UINT SizeOfClCharacteristics, OUT PNDIS_HANDLE NdisAfHandle );

NdisClOpenAddressFamily함수는 특별한 콜 메니져에의해 등록되는 어드레스 패밀리를 사용하는 특별한 NIC을 통해 연결지향 통신에대한 클라이언트 제공 함수들의 설정을 등록한다.

매개변수

NdisBindingHandle

타겟 닉을 확인하거나 호출자가 바인딩된 다음 하위드라이버의 가상 아답터를 확인하는 NdisOpenAdapter함수에의해 리턴된 핸들을 지정한다.

AddressFamily

열려진 어드레스 패밀리와 콜매니저를 설명하는 CO_ADDRESS_FAMILY타입의 구조체의 포인터.

이 포인터는 클라이언트의 ProtocolCoAfRegisterNotify함수에대한 입력 파라미터이다. 이것은 NdisClOpenAddressFamily함수를 호출한다.

ProtocolAfContext

클라이언트가 열려진후 이 어드레스 패밀리에대한 상태를 유지하는 호출자 제공 상주 컨택스트 영역에대한 핸들을 지정한다. 만약 NdisClOpenAddressFamily함수의 호출이 성공하면, NDIS는 이핸들을 다시 이 어드레스 패밀리로 생각하는 모든 순차적인 호출내의 클라이언트에게 넘겨준다.

ClCharacteristics

호출자에의해 설정되는 NDIS_CLIENT_CHARACTERISTICS의 포인터. ClCharacteristics의 구조체는 다음과 같이 정의된다.:

typedef struct _NDIS_CLIENT_CHARACTERISTICS {

    UCHAR   MajorVersion;

    UCHAR   MinorVersion;

    USHORT  Filler;           // 시스템 사용을 위해 예약

    UINT    Reserved;         // 시스템 사용을 위해 예약

    CO_CREATE_VC_HANDLER  ClCreateVcHandler;

    CO_DELETE_VC_HANDLER  ClDeleteVcHandler;

    CO_REQUEST_HANDLER  ClRequestHandler;

    CO_REQUEST_COMPLETE_HANDLER  ClRequestCompleteHandler;

    CL_OPEN_AF_COMPLETE_HANDLER  ClOpenAfCompleteHandler;

    CL_CLOSE_AF_COMPLETE_HANDLER  ClCloseAfCompleteHandler;

    CL_REG_SAP_COMPLETE_HANDLER  ClRegisterSapCompleteHandler;

    CL_DEREG_SAP_COMPLETE_HANDLER  ClDeregisterSapCompleteHandler;

    CL_MAKE_CALL_COMPLETE_HANDLER  ClMakeCallCompleteHandler;

    CL_MODIFY_CALL_QOS_COMPLETE_HANDLER

                                    ClModifyCallQoSCompleteHandler;

    CL_CLOSE_CALL_COMPLETE_HANDLER  ClCloseCallCompleteHandler;

    CL_ADD_PARTY_COMPLETE_HANDLER  ClAddPartyCompleteHandler;

    CL_DROP_PARTY_COMPLETE_HANDLER  ClDropPartyCompleteHandler;

    CL_INCOMING_CALL_HANDLER  ClIncomingCallHandler;

    CL_INCOMING_CALL_QOS_CHANGE_HANDLER

                                    ClIncomingCallQoSChangeHandler;

    CL_INCOMING_CLOSE_CALL_HANDLER  ClIncomingCloseCallHandler;

    CL_INCOMING_DROP_PARTY_HANDLER  ClIncomingDropPartyHandler;

    CL_CALL_CONNECTED_HANDLER  ClCallConnectedHandler;

} NDIS_CLIENT_CHARACTERISTICS, *PNDIS_CLIENT_CHARACTERISTICS;

드라이버는 이 구조체를 다음 멤벋르의 설정전에 0으로 초기화 해야한다.:

MajorVersion

클라이언트가 사용하는 이 구조체의 메이져 버전을 지정한다. 현재 값은 0x05이다.

MinorVersion

클라이언트가 사용한느 이 구조체의 마이너 버전을 지정한다. 현재 값은 0x00이다.

Filler 와 Reserved

호출자는 이 구조체를 0으로 초기화 한후 이러한 멤버들을 무시해야만한다.

ClCreateVcHandler

호출자의 ProtocolCoCreateVc함수의 포인터 엔트리를 지정한다.

ClDeleteVcHandler

호출자의 ProtocolCoDeleteVc함수의 포인터 엔트리를 지정한다.

ClRequestHandler

호출자의 ProtocolCoRequest함수의 포인터 엔트리를 지정한다.

ClRequestCompleteHandler

호출자의 ProtocolCoRequestComplete함수의 포인터 엔트리를 지정한다.

ClOpenAfCompleteHandler

호출자의 ProtocolClOpenAfComplete함수의 포인터 엔트리를 지정한다.

ClCloseAfCompleteHandler

호출자의 ProtocolClCloseAfComplete함수의 포인터 엔트리를 지정한다.

ClRegisterSapCompleteHandler

호출자의 ProtocolClRegisterSapComplete함수의 포인터 엔트리를 지정한다. 클라이언트는 리모트 머신으로부터 들어오는 호출을 받아들이기위해 이 함수를 사용한다.

ClDeregisterSapCompleteHandler

호출자의 ProtocolClDeregisterSapComplete함수의 포인터 엔트리를 지정한다.

ClMakeCallCompleteHandler

호출자의 ProtocolClMakeCallComplete함수의 포인터 엔트리를 지정한다. 클라이언트는 리모트 머신으로 나가는는 호출을 만들기위해 이 함수를 사용한다.

ClModifyCallQoSCompleteHandler

호출자의 ProtocolClModifyCallQoSComplete함수의 포인터 엔트리를 지정한다. 클라이언트는 성립된 VC에대한 서비스 질에 변화를 동적으로 만들기 위해 이함수를 호출한다. 혹은 콜매니저와 들어오는 호출을 설정할때 QoS를 설정하기위한 협상을 하기위해 호출한다.

ClCloseCallCompleteHandler

호출자의 ProtocolClCloseCallComplete함수의 포인터 엔트리를 지정한다.

ClAddPartyCompleteHandler

호출자의 ProtocolClAddPartyComplete함수의 포인터 엔트리를 지정한다. 클라이언트는 리모트 머신으로 나가는 호출에대한 포인트-TO-멀티포인트를 설정하기위해 이 함수를 사용한다.

ClDropPartyCompleteHandler

호출자의 ProtocolClDropPartyComplete함수의 포인터 엔트리를 지정한다.

ClIncomingCallHandler

호출자의 ProtocolClIncomingCall함수의 포인터 엔트리를 지정한다. 클라이언트는 리모트 머신으로부터 들어오는 호출을 받아들이기위해 이함수를 사용한다.

ClIncomingCallQoSChangeHandler

호출자의 ProtocolClIncomingCallQoSChange함수의 포인터 엔트리를 지정한다. 클라이언트는 보내기 클라이언트가 QoS를 동적으로 변화시킬수 있다는것에대해 리모트 머신으로부터 들어오는 호출을 받아들이기위해 이 함수를 사용한다.

ClIncomingCloseCallHandler

호출자의 ProtocolClIncomingCloseCall함수의 포인터 엔트리를 지정한다.

ClIncomingDropPartyHandler

호출자의 ProtocolClIncomingDropParty함수의 포인터 엔트리를 지정한다.

ClCallConnectedHandler

호출자의 ProtocolClCallConnected함수의 포인터 엔트리를 지정한다. 클라이언트는 리모트 머신으로 부터 들어오는 호출을 받아들이기위해 이함수를 사용한다.

SizeOfClCharacteristics

ClCharacteristics의 구조체의 바이트 사이즈를 지정한다.

NdisAfHandle

이함수가 새롭게 열린 어드레스 패밀리를 나타내는 핸들을 리턴하는 것에서의 호출자 제공 변수의 포인터.

리턴값

NdisClOpenAddressFamily함수가 NDIS_STATUS_PENDING이외의 다른것을 리턴할때, 클라이언튼 ProtocolClOpenAfComplete함수의 내부적인 호출을 만들어야만한다. 그렇지 않으면, NDIS는 클라이언트의 ProtocolClOpenAfComplete함수를 이연산이 완료될때 호출한다.

주석

클라이언트가 콜메니저와 등록된 어드레스들을 인정하는지를 결정하기위해 AddressFamily의 입력 버퍼를 채킹한후, 연결지향 클라이언트는 ProtocolCoAfRegisterNotify함수로 부터 NdisClOpenAddressFamily함수를호출한다. NDIS는 클라이언트의 NdisClOpenAddressFamily호출을 콜 메니져의 ProtocolCmOpenAf함수에게 포워드한다. 이것은 클라이언트가 타당한 어드레스 패밀리 구조체내에 넘겨주는 것을 확신한다.

클라이언트는 모든 ClXxx멤버를 호출자 제공 ProtocolCl/CoXxx함수로 NDIS_CLIENT_CHARACTERISTICS구조체내에 설정해야만한다. NdisClOpenAddressFamily함수를 호출할때, 심지어 만약 들어오는 호출, 나가는 호출 혹은 포인터-TO-멀티포인트 연결을 지원하지 않는다 하여도. 그런 클라이언트가 지원하지않는 연결 지향 기능의 어떠한 부분일지라도 ProtocolCl/CoXxx함수는 간단히 NDIS_STATUS_NOT_SUPPORTED를 리턴한다.

NdisClOpenAddressFamily의 성공적인 호출은 클라이언트로부터 같은 닉과 바인딩하는 특별한 콜 매니저를 통한 연결지향 닉 드라이버까지 혹은 클라이언트가 바인딩된 닉에대해 통합 MCM드라이버까지 통신을 설정한다. 클라이언트는 그리고나서 스스로 NdisClRegisterSap함수로 들어오는 호출을 받을 준비를 할수있거나 혹은 NdisClMakeCall함수로 나가는 호출을 만들기위해 NdisCoCreateVc함수로 가상 연결을 설정할수있다.

만약 NdisClOpenAddressFamily함수의 호출이 실패하면, 클라이언트는 하위 닉 드라이버와의 바인딩을 해제하기위해 NdisCloseAdapter함수를 호출해야만한다.

그렇지 않으면, 클라이언트는 NdisAfHandle에 리턴된 핸들을 저장해야만한다. 이 핸들은 주어진 어드레스 패밀리로 간주하는 순차적인 요청들에대한 콜매니저를 확인한다. 클라이언트는 이 리턴된 핸들을 순차적인 호출에서 수정되지않고 해석되지않는 것을 어떤NDIS라이브러리 함수에게 넘겨주는 모호한 변수로써 다루어야만한다. 일반적으로, NdisClOpenAddressFamily의 호출자는 NdisAfHandle포인터를 ProtocolAfContext에 클라이언트 할당 상태 영역내에 저장된 변수에게 넘겨준다.

클라이언트가 같은 NdisAfHandle로 NdisClCloseAddressFamily함수를 호출 할때까지 NDIS는 ProtocolAfContext포인터를 이 어드레스 패밀리로 간주하는 모든 순차적인 호출내의 클라이언트의 등록된 ProtocolClXxx함수들에게 넘긴다. 어드레스 패밀리가 닫혀진후, 클라이언트는 ProtocolAfContext에 할당한 저장장소를 해재하고 재사용할 수있다.

NdisClOpenAddressFamily함수의 호출자는 IRQL < DISPATCH_LEVEL에서 동작될수있다.