reactos/ntoskrnl/io/pnpmgr/plugplay.c

   1 /*
   2  * PROJECT:         ReactOS Kernel
   3  * COPYRIGHT:       GPL - See COPYING in the top level directory
   4  * FILE:            ntoskrnl/io/pnpmgr/plugplay.c
   5  * PURPOSE:         Plug-and-play interface routines
   6  * PROGRAMMERS:     Eric Kohl <eric.kohl@t-online.de>
   7  */
   8
   9 /* INCLUDES *****************************************************************/
  10
  11 #include <ntoskrnl.h>
  12 #define NDEBUG
  13 #include <debug.h>
  14
  15 #if defined (ALLOC_PRAGMA)
  16 #pragma alloc_text(INIT, IopInitPlugPlayEvents)
  17 #endif
  18
  19 typedef struct _PNP_EVENT_ENTRY
  20 {
  21     LIST_ENTRY ListEntry;
  22     PLUGPLAY_EVENT_BLOCK Event;
  23 } PNP_EVENT_ENTRY, *PPNP_EVENT_ENTRY;
  24
  25
  26 /* GLOBALS *******************************************************************/
  27
  28 static LIST_ENTRY IopPnpEventQueueHead;
  29 static KEVENT IopPnpNotifyEvent;
  30
  31 /* FUNCTIONS *****************************************************************/
  32
  33 NTSTATUS INIT_FUNCTION
  34 IopInitPlugPlayEvents(VOID)
  35 {
  36     InitializeListHead(&IopPnpEventQueueHead);
  37
  38     KeInitializeEvent(&IopPnpNotifyEvent,
  39                       SynchronizationEvent,
  40                       FALSE);
  41
  42     return STATUS_SUCCESS;
  43 }
  44
  45 NTSTATUS
  46 IopQueueTargetDeviceEvent(const GUID *Guid,
  47                           PUNICODE_STRING DeviceIds)
  48 {
  49     PPNP_EVENT_ENTRY EventEntry;
  50     UNICODE_STRING Copy;
  51     ULONG TotalSize;
  52     NTSTATUS Status;
  53
  54     ASSERT(DeviceIds);
  55
  56     /* Allocate a big enough buffer */
  57     Copy.Length = 0;
  58     Copy.MaximumLength = DeviceIds->Length + sizeof(UNICODE_NULL);
  59     TotalSize =
  60         FIELD_OFFSET(PLUGPLAY_EVENT_BLOCK, TargetDevice.DeviceIds) +
  61         Copy.MaximumLength;
  62
  63     EventEntry = ExAllocatePool(NonPagedPool,
  64                                 TotalSize + FIELD_OFFSET(PNP_EVENT_ENTRY, Event));
  65     if (!EventEntry)
  66         return STATUS_INSUFFICIENT_RESOURCES;
  67
  68     /* Fill the buffer with the event GUID */
  69     RtlCopyMemory(&EventEntry->Event.EventGuid,
  70                   Guid,
  71                   sizeof(GUID));
  72     EventEntry->Event.EventCategory = TargetDeviceChangeEvent;
  73     EventEntry->Event.TotalSize = TotalSize;
  74
  75     /* Fill the device id */
  76     Copy.Buffer = EventEntry->Event.TargetDevice.DeviceIds;
  77     Status = RtlAppendUnicodeStringToString(&Copy, DeviceIds);
  78     if (!NT_SUCCESS(Status))
  79         return Status;
  80
  81     InsertHeadList(&IopPnpEventQueueHead,
  82                    &EventEntry->ListEntry);
  83     KeSetEvent(&IopPnpNotifyEvent,
  84                0,
  85                FALSE);
  86
  87     return STATUS_SUCCESS;
  88 }
  89
  90
  91 /*
  92  * Remove the current PnP event from the tail of the event queue
  93  * and signal IopPnpNotifyEvent if there is yet another event in the queue.
  94  */
  95 static NTSTATUS
  96 IopRemovePlugPlayEvent(VOID)
  97 {
  98     /* Remove a pnp event entry from the tail of the queue */
  99     if (!IsListEmpty(&IopPnpEventQueueHead))
 100     {
 101         ExFreePool(CONTAINING_RECORD(RemoveTailList(&IopPnpEventQueueHead), PNP_EVENT_ENTRY, ListEntry));
 102     }
 103
 104     /* Signal the next pnp event in the queue */
 105     if (!IsListEmpty(&IopPnpEventQueueHead))
 106     {
 107         KeSetEvent(&IopPnpNotifyEvent,
 108                    0,
 109                    FALSE);
 110     }
 111
 112     return STATUS_SUCCESS;
 113 }
 114
 115 static PDEVICE_OBJECT
 116 IopTraverseDeviceNode(PDEVICE_NODE Node, PUNICODE_STRING DeviceInstance)
 117 {
 118     PDEVICE_OBJECT DeviceObject;
 119     PDEVICE_NODE ChildNode;
 120
 121     if (RtlEqualUnicodeString(&Node->InstancePath,
 122                               DeviceInstance, TRUE))
 123     {
 124         ObReferenceObject(Node->PhysicalDeviceObject);
 125         return Node->PhysicalDeviceObject;
 126     }
 127
 128     /* Traversal of all children nodes */
 129     for (ChildNode = Node->Child;
 130          ChildNode != NULL;
 131          ChildNode = ChildNode->Sibling)
 132     {
 133         DeviceObject = IopTraverseDeviceNode(ChildNode, DeviceInstance);
 134         if (DeviceObject != NULL)
 135         {
 136             return DeviceObject;
 137         }
 138     }
 139
 140     return NULL;
 141 }
 142
 143
 144 static PDEVICE_OBJECT
 145 IopGetDeviceObjectFromDeviceInstance(PUNICODE_STRING DeviceInstance)
 146 {
 147     if (IopRootDeviceNode == NULL)
 148         return NULL;
 149
 150     if (DeviceInstance == NULL ||
 151         DeviceInstance->Length == 0)
 152     {
 153         if (IopRootDeviceNode->PhysicalDeviceObject)
 154         {
 155             ObReferenceObject(IopRootDeviceNode->PhysicalDeviceObject);
 156             return IopRootDeviceNode->PhysicalDeviceObject;
 157         }
 158         else
 159             return NULL;
 160     }
 161
 162     return IopTraverseDeviceNode(IopRootDeviceNode, DeviceInstance);
 163
 164 }
 165
 166 static NTSTATUS
 167 IopCaptureUnicodeString(PUNICODE_STRING DstName, PUNICODE_STRING SrcName)
 168 {
 169     NTSTATUS Status = STATUS_SUCCESS;
 170     UNICODE_STRING Name;
 171
 172     Name.Buffer = NULL;
 173     _SEH2_TRY
 174     {
 175         Name.Length = SrcName->Length;
 176         Name.MaximumLength = SrcName->MaximumLength;
 177         if (Name.Length > Name.MaximumLength)
 178         {
 179             Status = STATUS_INVALID_PARAMETER;
 180             _SEH2_LEAVE;
 181         }
 182
 183         if (Name.MaximumLength)
 184         {
 185             ProbeForRead(SrcName->Buffer,
 186                          Name.MaximumLength,
 187                          sizeof(WCHAR));
 188             Name.Buffer = ExAllocatePool(NonPagedPool, Name.MaximumLength);
 189             if (Name.Buffer == NULL)
 190             {
 191                 Status = STATUS_INSUFFICIENT_RESOURCES;
 192                 _SEH2_LEAVE;
 193             }
 194
 195             memcpy(Name.Buffer, SrcName->Buffer, Name.MaximumLength);
 196         }
 197
 198         *DstName = Name;
 199     }
 200     _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 201     {
 202         if (Name.Buffer)
 203             ExFreePool(Name.Buffer);
 204         Status = _SEH2_GetExceptionCode();
 205     }
 206     _SEH2_END;
 207
 208     return Status;
 209 }
 210
 211 static NTSTATUS
 212 IopGetDeviceProperty(PPLUGPLAY_CONTROL_PROPERTY_DATA PropertyData)
 213 {
 214     PDEVICE_OBJECT DeviceObject = NULL;
 215     NTSTATUS Status;
 216     UNICODE_STRING DeviceInstance;
 217     ULONG BufferSize;
 218     ULONG Property = 0;
 219     PVOID Buffer;
 220
 221     DPRINT("IopGetDeviceProperty() called\n");
 222     DPRINT("Device name: %wZ\n", &PropertyData->DeviceInstance);
 223
 224     Status = IopCaptureUnicodeString(&DeviceInstance, &PropertyData->DeviceInstance);
 225     if (!NT_SUCCESS(Status))
 226     {
 227         return Status;
 228     }
 229
 230     _SEH2_TRY
 231     {
 232         Property = PropertyData->Property;
 233         BufferSize = PropertyData->BufferSize;
 234         ProbeForWrite(PropertyData->Buffer,
 235                       BufferSize,
 236                       sizeof(UCHAR));
 237     }
 238     _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 239     {
 240         ExFreePool(DeviceInstance.Buffer);
 241         _SEH2_YIELD(return _SEH2_GetExceptionCode());
 242     }
 243     _SEH2_END;
 244
 245     /* Get the device object */
 246     DeviceObject = IopGetDeviceObjectFromDeviceInstance(&DeviceInstance);
 247     ExFreePool(DeviceInstance.Buffer);
 248     if (DeviceObject == NULL)
 249     {
 250         return STATUS_NO_SUCH_DEVICE;
 251     }
 252
 253     Buffer = ExAllocatePool(NonPagedPool, BufferSize);
 254     if (Buffer == NULL)
 255     {
 256         return STATUS_INSUFFICIENT_RESOURCES;
 257     }
 258
 259     Status = IoGetDeviceProperty(DeviceObject,
 260                                  Property,
 261                                  BufferSize,
 262                                  Buffer,
 263                                  &BufferSize);
 264
 265     ObDereferenceObject(DeviceObject);
 266
 267     if (NT_SUCCESS(Status))
 268     {
 269         _SEH2_TRY
 270         {
 271             memcpy(PropertyData->Buffer, Buffer, BufferSize);
 272             PropertyData->BufferSize = BufferSize;
 273         }
 274         _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 275         {
 276             Status = _SEH2_GetExceptionCode();
 277         }
 278         _SEH2_END;
 279     }
 280
 281     ExFreePool(Buffer);
 282     return Status;
 283 }
 284
 285
 286 static NTSTATUS
 287 IopGetRelatedDevice(PPLUGPLAY_CONTROL_RELATED_DEVICE_DATA RelatedDeviceData)
 288 {
 289     UNICODE_STRING RootDeviceName;
 290     PDEVICE_OBJECT DeviceObject = NULL;
 291     PDEVICE_NODE DeviceNode = NULL;
 292     PDEVICE_NODE RelatedDeviceNode;
 293     UNICODE_STRING TargetDeviceInstance;
 294     NTSTATUS Status = STATUS_SUCCESS;
 295     ULONG Relation = 0;
 296     ULONG MaximumLength = 0;
 297
 298     DPRINT("IopGetRelatedDevice() called\n");
 299     DPRINT("Device name: %wZ\n", &RelatedDeviceData->TargetDeviceInstance);
 300
 301     Status = IopCaptureUnicodeString(&TargetDeviceInstance, &RelatedDeviceData->TargetDeviceInstance);
 302     if (!NT_SUCCESS(Status))
 303     {
 304         return Status;
 305     }
 306
 307     _SEH2_TRY
 308     {
 309         Relation = RelatedDeviceData->Relation;
 310         MaximumLength = RelatedDeviceData->RelatedDeviceInstanceLength;
 311         ProbeForWrite(RelatedDeviceData->RelatedDeviceInstance,
 312                       MaximumLength,
 313                       sizeof(WCHAR));
 314     }
 315     _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 316     {
 317         ExFreePool(TargetDeviceInstance.Buffer);
 318         _SEH2_YIELD(return _SEH2_GetExceptionCode());
 319     }
 320     _SEH2_END;
 321
 322     RtlInitUnicodeString(&RootDeviceName,
 323                          L"HTREE\\ROOT\\0");
 324     if (RtlEqualUnicodeString(&TargetDeviceInstance,
 325                               &RootDeviceName,
 326                               TRUE))
 327     {
 328         DeviceNode = IopRootDeviceNode;
 329         ExFreePool(TargetDeviceInstance.Buffer);
 330     }
 331     else
 332     {
 333         /* Get the device object */
 334         DeviceObject = IopGetDeviceObjectFromDeviceInstance(&TargetDeviceInstance);
 335         ExFreePool(TargetDeviceInstance.Buffer);
 336         if (DeviceObject == NULL)
 337             return STATUS_NO_SUCH_DEVICE;
 338
 339         DeviceNode = ((PEXTENDED_DEVOBJ_EXTENSION)DeviceObject->DeviceObjectExtension)->DeviceNode;
 340     }
 341
 342     switch (Relation)
 343     {
 344         case PNP_GET_PARENT_DEVICE:
 345             RelatedDeviceNode = DeviceNode->Parent;
 346             break;
 347
 348         case PNP_GET_CHILD_DEVICE:
 349             RelatedDeviceNode = DeviceNode->Child;
 350             break;
 351
 352         case PNP_GET_SIBLING_DEVICE:
 353             RelatedDeviceNode = DeviceNode->Sibling;
 354             break;
 355
 356         default:
 357             if (DeviceObject != NULL)
 358             {
 359                 ObDereferenceObject(DeviceObject);
 360             }
 361
 362             return STATUS_INVALID_PARAMETER;
 363     }
 364
 365     if (RelatedDeviceNode == NULL)
 366     {
 367         if (DeviceObject)
 368         {
 369             ObDereferenceObject(DeviceObject);
 370         }
 371
 372         return STATUS_NO_SUCH_DEVICE;
 373     }
 374
 375     if (RelatedDeviceNode->InstancePath.Length > MaximumLength)
 376     {
 377         if (DeviceObject)
 378         {
 379             ObDereferenceObject(DeviceObject);
 380         }
 381
 382         return STATUS_BUFFER_TOO_SMALL;
 383     }
 384
 385     /* Copy related device instance name */
 386     _SEH2_TRY
 387     {
 388         RtlCopyMemory(RelatedDeviceData->RelatedDeviceInstance,
 389                       RelatedDeviceNode->InstancePath.Buffer,
 390                       RelatedDeviceNode->InstancePath.Length);
 391         RelatedDeviceData->RelatedDeviceInstanceLength = RelatedDeviceNode->InstancePath.Length;
 392     }
 393     _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 394     {
 395         Status = _SEH2_GetExceptionCode();
 396     }
 397     _SEH2_END;
 398
 399     if (DeviceObject != NULL)
 400     {
 401         ObDereferenceObject(DeviceObject);
 402     }
 403
 404     DPRINT("IopGetRelatedDevice() done\n");
 405
 406     return Status;
 407 }
 408
 409 static ULONG
 410 IopGetDeviceNodeStatus(PDEVICE_NODE DeviceNode)
 411 {
 412     ULONG Output = 0;
 413
 414     if (DeviceNode->Parent == IopRootDeviceNode)
 415         Output |= DN_ROOT_ENUMERATED;
 416
 417     if (DeviceNode->Flags & DNF_ADDED)
 418         Output |= DN_DRIVER_LOADED;
 419
 420     /* FIXME: DN_ENUM_LOADED */
 421
 422     if (DeviceNode->Flags & DNF_STARTED)
 423         Output |= DN_STARTED;
 424
 425     /* FIXME: Manual */
 426
 427     if (!(DeviceNode->Flags & DNF_PROCESSED))
 428         Output |= DN_NEED_TO_ENUM;
 429
 430     /* DN_NOT_FIRST_TIME is 9x only */
 431
 432     /* FIXME: DN_HARDWARE_ENUM */
 433
 434     /* DN_LIAR and DN_HAS_MARK are 9x only */
 435
 436     if (DeviceNode->Problem != 0)
 437         Output |= DN_HAS_PROBLEM;
 438
 439     /* FIXME: DN_FILTERED */
 440
 441     if (DeviceNode->Flags & DNF_LEGACY_DRIVER)
 442         Output |= DN_LEGACY_DRIVER;
 443
 444     /* FIXME: Implement the rest */
 445
 446     Output |= DN_NT_ENUMERATOR | DN_NT_DRIVER;
 447
 448     return Output;
 449 }
 450
 451 static NTSTATUS
 452 IopDeviceStatus(PPLUGPLAY_CONTROL_STATUS_DATA StatusData)
 453 {
 454     PDEVICE_OBJECT DeviceObject;
 455     PDEVICE_NODE DeviceNode;
 456     ULONG Operation = 0;
 457     ULONG DeviceStatus = 0;
 458     ULONG DeviceProblem = 0;
 459     UNICODE_STRING DeviceInstance;
 460     NTSTATUS Status;
 461
 462     DPRINT("IopDeviceStatus() called\n");
 463
 464     Status = IopCaptureUnicodeString(&DeviceInstance, &StatusData->DeviceInstance);
 465     if (!NT_SUCCESS(Status))
 466         return Status;
 467     DPRINT("Device name: '%wZ'\n", &DeviceInstance);
 468
 469     _SEH2_TRY
 470     {
 471         Operation = StatusData->Operation;
 472         if (Operation == PNP_SET_DEVICE_STATUS)
 473         {
 474             DeviceStatus = StatusData->DeviceStatus;
 475             DeviceProblem = StatusData->DeviceProblem;
 476         }
 477     }
 478     _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 479     {
 480         if (DeviceInstance.Buffer) ExFreePool(DeviceInstance.Buffer);
 481         _SEH2_YIELD(return _SEH2_GetExceptionCode());
 482     }
 483     _SEH2_END;
 484
 485     /* Get the device object */
 486     DeviceObject = IopGetDeviceObjectFromDeviceInstance(&DeviceInstance);
 487     ExFreePool(DeviceInstance.Buffer);
 488     if (DeviceObject == NULL)
 489         return STATUS_NO_SUCH_DEVICE;
 490
 491     DeviceNode = IopGetDeviceNode(DeviceObject);
 492
 493     switch (Operation)
 494     {
 495         case PNP_GET_DEVICE_STATUS:
 496             DPRINT("Get status data\n");
 497             DeviceStatus = IopGetDeviceNodeStatus(DeviceNode);
 498             DeviceProblem = DeviceNode->Problem;
 499             break;
 500
 501         case PNP_SET_DEVICE_STATUS:
 502             DPRINT1("Set status data is NOT SUPPORTED\n");
 503             break;
 504
 505         case PNP_CLEAR_DEVICE_STATUS:
 506             DPRINT1("FIXME: Clear status data!\n");
 507             break;
 508     }
 509
 510     ObDereferenceObject(DeviceObject);
 511
 512     if (Operation == PNP_GET_DEVICE_STATUS)
 513     {
 514         _SEH2_TRY
 515         {
 516             StatusData->DeviceStatus = DeviceStatus;
 517             StatusData->DeviceProblem = DeviceProblem;
 518         }
 519         _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 520         {
 521             Status = _SEH2_GetExceptionCode();
 522         }
 523         _SEH2_END;
 524     }
 525
 526     return Status;
 527 }
 528
 529
 530 static NTSTATUS
 531 IopGetDeviceDepth(PPLUGPLAY_CONTROL_DEPTH_DATA DepthData)
 532 {
 533     PDEVICE_OBJECT DeviceObject;
 534     PDEVICE_NODE DeviceNode;
 535     UNICODE_STRING DeviceInstance;
 536     NTSTATUS Status = STATUS_SUCCESS;
 537
 538     DPRINT("IopGetDeviceDepth() called\n");
 539     DPRINT("Device name: %wZ\n", &DepthData->DeviceInstance);
 540
 541     Status = IopCaptureUnicodeString(&DeviceInstance, &DepthData->DeviceInstance);
 542     if (!NT_SUCCESS(Status))
 543     {
 544         return Status;
 545     }
 546
 547     /* Get the device object */
 548     DeviceObject = IopGetDeviceObjectFromDeviceInstance(&DeviceInstance);
 549     ExFreePool(DeviceInstance.Buffer);
 550     if (DeviceObject == NULL)
 551         return STATUS_NO_SUCH_DEVICE;
 552
 553     DeviceNode = IopGetDeviceNode(DeviceObject);
 554
 555     _SEH2_TRY
 556     {
 557         DepthData->Depth = DeviceNode->Level;
 558     }
 559     _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 560     {
 561         Status = _SEH2_GetExceptionCode();
 562     }
 563     _SEH2_END;
 564
 565     ObDereferenceObject(DeviceObject);
 566
 567     return Status;
 568 }
 569
 570
 571 static NTSTATUS
 572 IopResetDevice(PPLUGPLAY_CONTROL_RESET_DEVICE_DATA ResetDeviceData)
 573 {
 574     PDEVICE_OBJECT DeviceObject;
 575     PDEVICE_NODE DeviceNode;
 576     NTSTATUS Status = STATUS_SUCCESS;
 577     UNICODE_STRING DeviceInstance;
 578
 579     Status = IopCaptureUnicodeString(&DeviceInstance, &ResetDeviceData->DeviceInstance);
 580     if (!NT_SUCCESS(Status))
 581         return Status;
 582
 583     DPRINT("IopResetDevice(%wZ)\n", &DeviceInstance);
 584
 585     /* Get the device object */
 586     DeviceObject = IopGetDeviceObjectFromDeviceInstance(&DeviceInstance);
 587     ExFreePool(DeviceInstance.Buffer);
 588     if (DeviceObject == NULL)
 589         return STATUS_NO_SUCH_DEVICE;
 590
 591     /* Get the device node */
 592     DeviceNode = IopGetDeviceNode(DeviceObject);
 593
 594     ASSERT(DeviceNode->Flags & DNF_ENUMERATED);
 595     ASSERT(DeviceNode->Flags & DNF_PROCESSED);
 596
 597     /* Check if there's already a driver loaded for this device */
 598     if (DeviceNode->Flags & DNF_ADDED)
 599     {
 600         /* Remove the device node */
 601         Status = IopRemoveDevice(DeviceNode);
 602         if (NT_SUCCESS(Status))
 603         {
 604             /* Invalidate device relations for the parent to reenumerate the device */
 605             Status = IoSynchronousInvalidateDeviceRelations(DeviceNode->Parent->PhysicalDeviceObject, BusRelations);
 606             DPRINT1("A new driver has been loaded for '%wZ' (FDO above removed)\n", &DeviceNode->InstancePath);
 607         }
 608         else
 609         {
 610             /* A driver has already been loaded for this device */
 611             DPRINT1("A reboot is required for the current driver for '%wZ' to be replaced\n", &DeviceNode->InstancePath);
 612         }
 613     }
 614     else
 615     {
 616         /* FIXME: What if the device really is disabled? */
 617         DeviceNode->Flags &= ~DNF_DISABLED;
 618         DeviceNode->Problem = 0;
 619
 620         /* Load service data from the registry */
 621         Status = IopActionConfigureChildServices(DeviceNode, DeviceNode->Parent);
 622
 623         if (NT_SUCCESS(Status))
 624         {
 625             /* Start the service and begin PnP initialization of the device again */
 626             Status = IopActionInitChildServices(DeviceNode, DeviceNode->Parent);
 627             DPRINT1("A new driver will be loaded for '%wZ' (no FDO above)\n", &DeviceNode->InstancePath);
 628         }
 629     }
 630
 631     ObDereferenceObject(DeviceObject);
 632
 633     return Status;
 634 }
 635
 636 /* PUBLIC FUNCTIONS **********************************************************/
 637
 638 /*
 639  * Plug and Play event structure used by NtGetPlugPlayEvent.
 640  *
 641  * EventGuid
 642  *    Can be one of the following values:
 643  *       GUID_HWPROFILE_QUERY_CHANGE
 644  *       GUID_HWPROFILE_CHANGE_CANCELLED
 645  *       GUID_HWPROFILE_CHANGE_COMPLETE
 646  *       GUID_TARGET_DEVICE_QUERY_REMOVE
 647  *       GUID_TARGET_DEVICE_REMOVE_CANCELLED
 648  *       GUID_TARGET_DEVICE_REMOVE_COMPLETE
 649  *       GUID_PNP_CUSTOM_NOTIFICATION
 650  *       GUID_PNP_POWER_NOTIFICATION
 651  *       GUID_DEVICE_* (see above)
 652  *
 653  * EventCategory
 654  *    Type of the event that happened.
 655  *
 656  * Result
 657  *    ?
 658  *
 659  * Flags
 660  *    ?
 661  *
 662  * TotalSize
 663  *    Size of the event block including the device IDs and other
 664  *    per category specific fields.
 665  */
 666
 667 /*
 668  * NtGetPlugPlayEvent
 669  *
 670  * Returns one Plug & Play event from a global queue.
 671  *
 672  * Parameters
 673  *    Reserved1
 674  *    Reserved2
 675  *       Always set to zero.
 676  *
 677  *    Buffer
 678  *       The buffer that will be filled with the event information on
 679  *       successful return from the function.
 680  *
 681  *    BufferSize
 682  *       Size of the buffer pointed by the Buffer parameter. If the
 683  *       buffer size is not large enough to hold the whole event
 684  *       information, error STATUS_BUFFER_TOO_SMALL is returned and
 685  *       the buffer remains untouched.
 686  *
 687  * Return Values
 688  *    STATUS_PRIVILEGE_NOT_HELD
 689  *    STATUS_BUFFER_TOO_SMALL
 690  *    STATUS_SUCCESS
 691  *
 692  * Remarks
 693  *    This function isn't multi-thread safe!
 694  *
 695  * @implemented
 696  */
 697 NTSTATUS
 698 NTAPI
 699 NtGetPlugPlayEvent(IN ULONG Reserved1,
 700                    IN ULONG Reserved2,
 701                    OUT PPLUGPLAY_EVENT_BLOCK Buffer,
 702                    IN ULONG BufferSize)
 703 {
 704     PPNP_EVENT_ENTRY Entry;
 705     NTSTATUS Status;
 706
 707     DPRINT("NtGetPlugPlayEvent() called\n");
 708
 709     /* Function can only be called from user-mode */
 710     if (KeGetPreviousMode() == KernelMode)
 711     {
 712         DPRINT1("NtGetPlugPlayEvent cannot be called from kernel mode!\n");
 713         return STATUS_ACCESS_DENIED;
 714     }
 715
 716     /* Check for Tcb privilege */
 717     if (!SeSinglePrivilegeCheck(SeTcbPrivilege,
 718                                 UserMode))
 719     {
 720         DPRINT1("NtGetPlugPlayEvent: Caller does not hold the SeTcbPrivilege privilege!\n");
 721         return STATUS_PRIVILEGE_NOT_HELD;
 722     }
 723
 724     /* Wait for a PnP event */
 725     DPRINT("Waiting for pnp notification event\n");
 726     Status = KeWaitForSingleObject(&IopPnpNotifyEvent,
 727                                    UserRequest,
 728                                    KernelMode,
 729                                    FALSE,
 730                                    NULL);
 731     if (!NT_SUCCESS(Status))
 732     {
 733         DPRINT1("KeWaitForSingleObject() failed (Status %lx)\n", Status);
 734         return Status;
 735     }
 736
 737     /* Get entry from the tail of the queue */
 738     Entry = CONTAINING_RECORD(IopPnpEventQueueHead.Blink,
 739                               PNP_EVENT_ENTRY,
 740                               ListEntry);
 741
 742     /* Check the buffer size */
 743     if (BufferSize < Entry->Event.TotalSize)
 744     {
 745         DPRINT1("Buffer is too small for the pnp-event\n");
 746         return STATUS_BUFFER_TOO_SMALL;
 747     }
 748
 749     /* Copy event data to the user buffer */
 750     memcpy(Buffer,
 751            &Entry->Event,
 752            Entry->Event.TotalSize);
 753
 754     DPRINT("NtGetPlugPlayEvent() done\n");
 755
 756     return STATUS_SUCCESS;
 757 }
 758
 759 /*
 760  * NtPlugPlayControl
 761  *
 762  * A function for doing various Plug & Play operations from user mode.
 763  *
 764  * Parameters
 765  *    PlugPlayControlClass
 766  *       0x00   Reenumerate device tree
 767  *
 768  *              Buffer points to UNICODE_STRING decribing the instance
 769  *              path (like "HTREE\ROOT\0" or "Root\ACPI_HAL\0000"). For
 770  *              more information about instance paths see !devnode command
 771  *              in kernel debugger or look at "Inside Windows 2000" book,
 772  *              chapter "Driver Loading, Initialization, and Installation".
 773  *
 774  *       0x01   Register new device
 775  *       0x02   Deregister device
 776  *       0x03   Initialize device
 777  *       0x04   Start device
 778  *       0x06   Query and remove device
 779  *       0x07   User response
 780  *
 781  *              Called after processing the message from NtGetPlugPlayEvent.
 782  *
 783  *       0x08   Generate legacy device
 784  *       0x09   Get interface device list
 785  *       0x0A   Get property data
 786  *       0x0B   Device class association (Registration)
 787  *       0x0C   Get related device
 788  *       0x0D   Get device interface alias
 789  *       0x0E   Get/set/clear device status
 790  *       0x0F   Get device depth
 791  *       0x10   Query device relations
 792  *       0x11   Query target device relation
 793  *       0x12   Query conflict list
 794  *       0x13   Retrieve dock data
 795  *       0x14   Reset device
 796  *       0x15   Halt device
 797  *       0x16   Get blocked driver data
 798  *
 799  *    Buffer
 800  *       The buffer contains information that is specific to each control
 801  *       code. The buffer is read-only.
 802  *
 803  *    BufferSize
 804  *       Size of the buffer pointed by the Buffer parameter. If the
 805  *       buffer size specifies incorrect value for specified control
 806  *       code, error ??? is returned.
 807  *
 808  * Return Values
 809  *    STATUS_PRIVILEGE_NOT_HELD
 810  *    STATUS_SUCCESS
 811  *    ...
 812  *
 813  * @unimplemented
 814  */
 815 NTSTATUS
 816 NTAPI
 817 NtPlugPlayControl(IN PLUGPLAY_CONTROL_CLASS PlugPlayControlClass,
 818                   IN OUT PVOID Buffer,
 819                   IN ULONG BufferLength)
 820 {
 821     DPRINT("NtPlugPlayControl(%lu %p %lu) called\n",
 822            PlugPlayControlClass, Buffer, BufferLength);
 823
 824     /* Function can only be called from user-mode */
 825     if (KeGetPreviousMode() == KernelMode)
 826     {
 827         DPRINT1("NtGetPlugPlayEvent cannot be called from kernel mode!\n");
 828         return STATUS_ACCESS_DENIED;
 829     }
 830
 831     /* Check for Tcb privilege */
 832     if (!SeSinglePrivilegeCheck(SeTcbPrivilege,
 833                                 UserMode))
 834     {
 835         DPRINT1("NtGetPlugPlayEvent: Caller does not hold the SeTcbPrivilege privilege!\n");
 836         return STATUS_PRIVILEGE_NOT_HELD;
 837     }
 838
 839     /* Probe the buffer */
 840     _SEH2_TRY
 841     {
 842         ProbeForWrite(Buffer,
 843                       BufferLength,
 844                       sizeof(ULONG));
 845     }
 846     _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
 847     {
 848         _SEH2_YIELD(return _SEH2_GetExceptionCode());
 849     }
 850     _SEH2_END;
 851
 852     switch (PlugPlayControlClass)
 853     {
 854         case PlugPlayControlUserResponse:
 855             if (Buffer || BufferLength != 0)
 856                 return STATUS_INVALID_PARAMETER;
 857             return IopRemovePlugPlayEvent();
 858
 859         case PlugPlayControlProperty:
 860             if (!Buffer || BufferLength < sizeof(PLUGPLAY_CONTROL_PROPERTY_DATA))
 861                 return STATUS_INVALID_PARAMETER;
 862             return IopGetDeviceProperty((PPLUGPLAY_CONTROL_PROPERTY_DATA)Buffer);
 863
 864         case PlugPlayControlGetRelatedDevice:
 865             if (!Buffer || BufferLength < sizeof(PLUGPLAY_CONTROL_RELATED_DEVICE_DATA))
 866                 return STATUS_INVALID_PARAMETER;
 867             return IopGetRelatedDevice((PPLUGPLAY_CONTROL_RELATED_DEVICE_DATA)Buffer);
 868
 869         case PlugPlayControlDeviceStatus:
 870             if (!Buffer || BufferLength < sizeof(PLUGPLAY_CONTROL_STATUS_DATA))
 871                 return STATUS_INVALID_PARAMETER;
 872             return IopDeviceStatus((PPLUGPLAY_CONTROL_STATUS_DATA)Buffer);
 873
 874         case PlugPlayControlGetDeviceDepth:
 875             if (!Buffer || BufferLength < sizeof(PLUGPLAY_CONTROL_DEPTH_DATA))
 876                 return STATUS_INVALID_PARAMETER;
 877             return IopGetDeviceDepth((PPLUGPLAY_CONTROL_DEPTH_DATA)Buffer);
 878
 879         case PlugPlayControlResetDevice:
 880             if (!Buffer || BufferLength < sizeof(PLUGPLAY_CONTROL_RESET_DEVICE_DATA))
 881                 return STATUS_INVALID_PARAMETER;
 882             return IopResetDevice((PPLUGPLAY_CONTROL_RESET_DEVICE_DATA)Buffer);
 883
 884         default:
 885             return STATUS_NOT_IMPLEMENTED;
 886     }
 887
 888     return STATUS_NOT_IMPLEMENTED;
 889 }