ClientPnPPowerChange

NTSTATUS
   ClientPnPPowerChange(
       IN PUNICODE_STRING DeviceName,
       IN PNET_PNP_EVENT PowerEvent,
       IN PTDI_PNP_CONTEXT Context1,
       IN PTDI_PNP_CONTEXT Context2
       );

TDI는 TdiPnPPowerRequest 함수로의 트랜스포트 호출의 결과로써 ClientPnPPowerChange 함수를 호출한다. 혹은 NDIS에 의한 호출의 결과로써 사용자 초기 네트웍 재구성을 위해서도 그러하다.

매개변수

DeviceName

특정 트랜스포트 혹은 트랜스포트와 NIC과의 바인딩을 통해 클라이언트의 네트웍 I/O에 대한 타겟을 구현하는 트랜스포트 생성 장치 객체를 일반적으로 확인하는 버퍼화된 유니코드 문자열을 가리킨다.

PowerEvent

다음중 하나의 타입이 될 수 있는 통보를 인디케이트하는 NET_PNP_EVENT 타입의 구조체를 가리킨다:

• 이 구조체의 NetEvent 멤버는 하부의 트랜스포트에 의해서 NetEventSetPower, NetEventQueryPower, NetEventQueryRemoveDevice, 혹은 NetEventCancelRemoveDevice로 설정된다. (NetEventQueryRemoveDevice의 실패에 이어서).
• 이 구조체의 NetEvent 멤버는 NDIS에 의해서 NetEventBindList나 NetEventReconfigure로 설정된다. 즉 TDI로부터 ClientPnPPowerChange 함수로의 런타임 호출은 연결폴더에서 마지막 사용자 초기 변화의 결과로써 발생할 수 있다.

Context1

하부의 트랜스포트가 TdiPnPPowerRequest 함수를 호출한다면 이 통보와 연관된 프로토콜 결정 컨텍스트를 가리킨다. 예를들어 TCP/IP는 이 통보의 컨텍스트와 연관된 주소 리스트에 대한 포인터를 전달한다.

그렇지 않으면 이것은 네트웍 구성에서 사용자 시작 변화의 결과로써 NDIS에 의해서 TDI로 제공된 컨텍스트를 가리킨다. 예를들어 사용자가 연결 폴더에서 네트웍을 재구성한다면 그래서 존재하는 네트웍 바인딩에서 변화가 리퀘스트된다면 NDIS는 그들의 ClientPnPXxx 핸들러를 등록하거나 등록해제하는 기회를 그들에게 주기 위해서 그러한 바인딩 변화에 영향을 받는 현재의 모든 등록된 TDI 클라이언트에게 알려야한다.

Context2

이 통보와 연관된 프로토콜 결정 컨텍스트를 가리킨다. 예를들어 TCP/IP는 발생된 이러한 통보상에서 물리 장치의 PDO에 대한 포인터를 리턴한다.

반면에 이것은 재구성되는 하부 NIC의 PDO에 대한 포인터와 같이 네트웍 구성에서 사용자 초기 변화의 결과로써 NDIS에 의해서 TDI로 제공된 컨텍스트를 가리킨다.

리턴값

클라이언트가 자신의 클라이언트에게 전원상태, 장치 제거 쿼리, 장치 제거 이벤트를 알려야한다면 ClientPnPPowerChange 함수는 STATUS_PENDING을 리턴할 수 있다. 그렇지 않으면 STATUS_SUCCESS를 리턴해야하고 자신의 클라이언트 중 하나가 질문에서 현재 하부의 NIC에 의존하고 있다면 NetEventSetPowerDevice 타입 혹은 NetEventQueryRemoveDevice 타입의 리퀘스트를 거절하기 위해서 STATUS_FILES_OPEN이나 STATUS_UNSUCCESSFUL과 같은 클라이언트 결정 실패 상태를 리턴해야한다.

ClientPnPPowerChange 함수는 NetEventBindList나 NetEventReconfigure 통보를 가지고 호출될 때 STATUS_SUCCESS를 리턴할 수 있다. 왜냐하면 원래 동기적인 연산이기 때문이다.

주석

PnP를 지원하는 트랜스포트 혹은 NDIS가 TdiPnPPowerRequest 함수를 호출할 때마다 클라이언트는 이 통보의 수신을 시작하기 위해서 TdiRegisterPnPHandlers 함수로의 호출을 가지고 ClientPnPPowerChange 루틴을 등록해야한다. 즉 ClientPnPPowerChange 함수는 바인딩이 되지않은 트랜스포트에 의해서 제공된 DeviceName 포인터를 가지고 호출될 수 있다. 결국 ClientPnPPowerChange 함수는 클라이언트가 DeviceName에서 확인된 트랜스포트를 인식하지 못한다면 즉시 통제를 리턴해야한다. 혹은 사용자 초기 네트웍 재구성에 대해서 통보됐을 때 클라이언트가 새롭게 성립할 이유가 없다거나 존재하는 트랜스포트와 NOC과의 바인딩을 해제한다고 결정한다면 즉시 통제를 리턴해야한다.

반면에 클라이언트가 NDIS로부터 NetEventBindingList나 NetEventReconfigure 통보의 결과로써 트랜스포트상에서 PnP 핸들러를 등록하거나 등록해제하기를 결정한다면 주어진 트랜스포트는 새로운 NIC과 자신을 바인딩하기 위해서 호출될 수 있고 현재 바인딩된 NIC으로부터 언바인딩을 위해서도 호출될 수 있다. 즉 NDIS는 이 클라이언트를 대신하여 트랜스포트 스택의 하부에서 ProtocolBindAdapter나 ProtocolUnbindAdapter 함수를 호출한다. TdiRegisterDeviceObject나 TdiDeregisterDeviceObject 함수로의 트랜스포트의 순차적인 호출은 교대로 클라이언트의 ClientPnPBindingChange 함수의 호출을 야기한다.

ClientPnPPowerChange 함수가 타입이 NetEventQueryRemoveDevice인 입력 PowerEvent를 가진 호출을 위해서 STATUS_SUCCESS를 리턴한다면 클라이언트는 똑같은 트랜스포트와 NIC 스택에 바인딩된 모든 다른 클라이언트가 이 통보를 성공할 때 PnPOpcode TDI_PNP_OP_DEL을 가지고 ClientPnPBindingChange 루틴으로의 순차적인 호출을 기대할 수 있다. 그렇지 않다면 클라이언트는 타입이 NetEventCancelRemoveDevice인 입력 PowerEvent를 가지고 ClientPnPPowerChange 함수로의 또다른 호출을 기대할 수 있다.

일반적으로 ClientPnPPowerChange 함수는 NetEventQueryPowerDevice와 NetEventSetPowerDevice 통보를 받았을 때 자신의 클라이언트에게 알렸는지를 결정해야한다. 예를들어 동작하지 않는 상태로 하부 NIC의 전원이 다운됐음을 인디케이트하는 전원설정 통보에서 ClientPnPPowerChange 함수는 주어진 바인딩 상에서 네트웍 I/O 연산을 반드시 수행하도록 기대되는 것과 관련해서 자신의 클라이언트와 함께 검사하기 위해서 STATUS_PENDING을 리턴한다. 그러나 특정 NIC에서 네트웍 I/O 요구가 없는 시스템 결정 기간후에 NetEventSetPowerDevice 타입의 통보가 발생한다. 그래서 클라이언트는 보통 자신의 클라이언트가 이 타입의 통보에 대해서 필요하지 않다고 가정한다.

ClientPnPPowerChange 함수가 STATUS_PENDING을 리턴한다면 클라이언트는 이 통보에서 시작된 연산을 완료하자마자 TdiPnPPowerComplete 함수를 호출해야한다.

TdiDeregisterPnPHandlers 함수로의 상반된 호출은 ClientPnPPowerChange 함수로의 순차적인 호출을 디스에이블한다.

TDI는 IRQL < DISPATCH_LEVEL에서 ClientPnPPowerChange 함수를 호출한다.