TdiRegisterPnPHandlers

NTSTATUS
   TdiRegisterPnPHandlers(
       IN PTDI_CLIENT_INTERFACE_INFO ClientInterfaceInfo,
       IN ULONG InterfaceInfoSize,
       OUT HANDLE *BindingHandle
       );

TdiRegisterPnPHandlers 함수는 기계에서 새로운 NIC 발견이나 기계에서 존재하는 NIC의 제거, 시스템 전원상태 변화, 그리고 하부의 트랜스포트에 의해서 등록되고 등록해제되는 네트웍 주소의 출발과 도착과 같은 동적 PnP 이벤트의 순차적인 통보를 받기위해서 클라이언트 제공 ClientPnPXxx 루틴의 모음을 등록한다.

매개변수

ClientInterfaceInfo

스택에서 이 구조체로 혹은 다음과 같이 포맷되는 호출자 할당, 그리고 0으로 초기화된 버퍼를 가리킨다:

typedef struct _TDI20_CLIENT_INTERFACE_INFO {

    union {

        struct {

            UCHAR MajorTdiVersion; // 현재 2

            UCHAR MinorTdiVersion; // 현재 0

        };

        // 다음은 사용하지 않는다. (쓰이지않는 트랜스포트)

        USHORT TdiVersion;

    };

    USHORT Unused;

    PUNICODE_STRING ClientName;

    TDI_PNP_POWER_HANDLER  PnPPowerHandler;

    union {

        TDI_BINDING_HANDLER BindingHandler;

        // 다음은 사용하지 않는다. (쓰이지않는 트랜스포트)

        struct {

            TDI_BIND_HANDLER BindHandler;

            TDI_UNBIND_HANDLER UnBindHandler;

        };

    };

    union {

        struct {

            TDI_ADD_ADDRESS_HANDLER_V2 AddAddressHandlerV2;

            TDI_DEL_ADDRESS_HANDLER_V2 DelAddressHandlerV2;

        };

        // 다음은 사용하지 않는다. (쓰이지않는 트랜스포트)

        struct {

            TDI_ADD_ADDRESS_HANDLER AddAddressHandler;

            TDI_DEL_ADDRESS_HANDLER DelAddressHandler;

        };

    };

} TDI20_CLIENT_INTERFACE_INFO, *PTDI20_CLIENT_INTERFACE_INFO;



typedef TDI20_CLIENT_INTERFACE_INFO TDI_CLIENT_INTERFACE_INFO;

InterfaceInfoSize

ClientInterfaceInfo에 버퍼의 바이트 수를 서술한다.

BindingHandle

TdiRegisterPnPHandlers 함수가 호출을 성공한다면 불투명한 TDI 제공 핸들을 리턴하는 호출자 제공 변수의 주소를 서술한다. 호출자는 TdiDeregisterPnPHandlers 함수나 매우 드물게 TdiEnumerateAddresses 함수로의 순차적인 호출을 위해서 이 핸들을 저장해야한다.

리턴값

TdiRegisterPnPHandlers 함수는 제공된 ClientPnPXxx 루틴이 순차적인 PnP와 전원상태 변화 이벤트를 인식한다면 STATUS_SUCCESS를 리턴한다. 그렇지 않으면 다음중 하나를 리턴할 수 있다:

TDI_STATUS_BAD_VERSION

호출자가 TDI_CURRENT_VERSION보다 큰 무언가로 ClientInterfaceInfo에 구조체 안에 버전 멤버를 설정한다면 호출자는 상위 레벨 네트웍 컴포넌트로 이 리턴값을 전달하지 말아야한다.

TDI_STATUS_BAD_CHARACTERISTICS

주어진 InterfaceInfoSize 값이 sizeof(TDI_CLIENT_INTERFACE_INFO)보다 작다. 호출자는 상위 레벨 네트웍 컴포넌트로 이 리턴값을 전달하지 말아야한다.

STATUS_INSUFFICIENT_RESOURCES

TDI는 등록 리퀘스트를 처리하기 위해서 필요한 클라이언트의 통보와 다른 자원을 위해서 상태를 유지하는 버퍼를 할당하지 않았다.(아마도 TdiRegisterPnPHandlers 함수로의 순차적인 호출은 현재 사용중인 자원이 해제된다면 이 이유를 위해서 실패하지 않을 것이다.)

주석

호출자는 PnP/전원상태 변화, 바인딩 변화, 그리고 네트웍 주소 변화의 순차적인 통보를 받기 위해서 ClientInterfaceInfo에 다음 정보를 제공해야한다:

• MajorTdiVersion은 2나 TDI_CURRENT_MAJOR_VERSION으로 설정한다.
• MinorTdiVersion은 0이나 TDI_CURRENT_MINOR_VERSION으로 설정한다.
• ClientName은 레지스트리 registry HKLM\System\CCS\Services 트리에 클라이언트로 명명된 키를 서술하는 버퍼화된 유니코드의 주소를 설정한다.
• PnPPowerHandler는 호출자의 ClientPnPPowerChange 루틴의 엔트리 포인트를 설정한다.
• BindingHandler는 호출자의 ClientPnPBindingChange 루틴의 엔트리 포인트를 설정한다.
• AddAddressHandlerV2는 호출자의 ClientPnPAddNetAddress 루틴의 엔트리 포인트를 설정한다.
• DelAddressHandlerV2는 호출자의 ClientPnPDelNetAddress 루틴의 엔트리 포인트를 설정한다.

• ClientPnPBindingChange 함수는 이미 TDI를 가지고 등록된 트랜스포트에 의해서 성립된 트랜스포트와 NIC의 바인딩을 구현하기 위해서 생성된 장치 객체의 버퍼화된 이름과 값이 TDI_PNP_OP_ADD인 PnPOpcode를 가지고 한번이상 호출됐다. 또한 ClientPnPBindingChange 함수는 기대되는 트랜스포트와 NIC의 바인딩에서 네트웍 I/O 연산을 수행하기 위해서 준비된 자신을 선언한 TDI 트랜스포트 드라이버의 버퍼화된 이름과 값이 TDI_PNP_OP_PROVIDERREADY인 PnPOpcode를 가지고 한번이상 호출됐다.

  값이 TDI_PNP_OP_ADD인 PnPOpcode를 가진 ClientPnPBindingChange 함수로의 각각의 호출에서 이 루틴은 ZwCreateFile 함수로의 호출을 가지고 하부의 트랜스포트와 NIC의 바인딩에 자신을 바인딩할 것인지를 결정한다.(ZwCreateFile 함수 호출에 대한 특징에 대해서는 커널 모드 레퍼런스를 봐라.)

• ClientPnPAddNetAddress 함수는 TdiRegisterNetworkAddress 함수로의 호출을 가지고 성립된 바인딩상에서 트랜스포트가 이미 등록한 각각의 네트웍 주소를 가지고 한번이상 호출됐다.

  ClientPnPAddNetAddress 함수로의 각각의 호출에서 이 루틴은 이 네트웍 프로토콜을 인식하고 즉시 통제를 리턴하는지를 결정하기 위해서 입력 Address에 구조체의 AddressType 멤버를 검사한다. 그렇지 않으면 ClientPnPAddNetAddress 함수는 클라이언트가 이미 이 트랜스포트와 자신을 바인딩했는지를 결정하기 위해서 DeviceName에 버퍼화된 문자열을 검사한다. 그렇다면 ClientPnpAddNetAddress 함수는 유효하고 등록된 네트웍 주소의 클라이언트 할당 내부 리스트에 대한 엔트리를 추가하기 위해서 입력 프로토콜 특정 주소 정보를 사용한다. 클라이언트는 네트웍 주소를 열고 다시 ZwCreateFile 함수의 호출을 가지고 그 후에 순차적인 네트웍 I/O 리퀘스트를 위해서 등록된 네트웍 주소를 사용한다.

게다가 TDI가 컴퓨터를 위해서 구성된 모든 가능한 트랜스포트와 NIC과의 바인딩이 성립됐고 모든 트랜스포트가 네트웍 데이타를 전송하기 위해서 그 준비를 인디케이트했다는 것을 결정했을 때 TDI는 값이 TDI_PNP_OP_NETREADY인 PnPOpcode와 NULL DeviceName 포인터를 가지고 한번이상 모든 등록된 ClientPnPBindingChange 루틴을 호출한다. ClientPnPBindingChange 함수로의 마지막 초기화시에 호출은 네트웍 통신 설정의 시스템 초기화 시기가 지금 행해졌음을 알린다.

시스템 설정에 따라 TDI는 클라이언트가 *BindingHandle에 리턴된 핸들을 가지고 TdiDeregisterPnPHandlers 함수로의 상호적인 호출을 할 때까지 클라이언트가 바인딩한 트랜스포트가 TdiRegisterDeviceObject, TdiDeregisterDeviceObject, TdiRegisterNetAddress, TdiDeregisterNetAddress, 그리고 TdiPnPPowerRequest 함수로의 실시간 호출을 할 때 등록된 ClientPnPXxx 루틴으로의 동적인 호출을 한다.

TdiRegisterPnPHandlers 함수의 호출자는 IRQL < DISPATCH_LEVEL에서 실행되어야한다.