IEEE 1394 Unit Filter Driver Plug Allocation (Windows CE 5.0)
A virtual subunit may need to permanently allocate serial bus plugs and have those plugs associated with a particular subunit plug. Many clients do not dynamically query for plugs; they query once when they identify the subunit, or they use hard-coded plug numbers, or depend on broadcast. To accommodate these older clients, newer clients should use an AV/C plug management API dynamically; a virtual subunit must have default plugs allocated and externally visible before or while receiving an IRP_MN_START_DEVICE request.
To facilitate allocating default plugs for virtual subunits, the unit filter driver provides the IOCTL_UNIT_PROCESS_REGISTRY_PLUGS command, which accepts a registry handle as an argument, and processes the values and keys underneath in a known format. The unit filter driver uses this information to allocate the local plugs by issuing callbacks into the subunit's registration callbacks. The unit filter driver uses UNIT_AllocateLocalPlugCB to issue the callbacks.
The registry key passed is an HKEY to a known location. This location is preferably the virtual subunit driver's registry key that you can obtain from IoOpenDeviceRegistryKey with PLUGPLAY_REGKEY_DRIVER.
The following example shows the defined registry format.
Plugs\<Incremental plug definition index>\<Values>
Incremental plug definition index refers to an incrementing, unique number for each plug to be defined. For example, 0 for the first plug, 1 for the next, and so on.
The following table shows the registry type Values.
| Name | Type | Purpose |
|---|---|---|
| MediaType | DWORD | This must be one of the values defined by the Avc_stream.h STREAM_MediaType enumeration. This is the media type that this plug expects to stream. |
| Direction | DWORD | Set to 1 to represent an input plug, which receives streams, or set to 2 to represent an output plug, which transmits streams. |
| SubunitPlugID | DWORD | This identifies which subunit plug is represented by the serial bus plug that these registry entries define.
The subunit plug identifier is entirely relative to the subunit, and is defined at the discretion of the developer. |
| MaximumThroughput | DWORD | This is a requirement only for output plugs, and represents the maximum number of bits per second that this plug will ever stream. |
The definitions for type DWORD in the registry are in hexadecimal. The numerical values in the table above are in decimal. An example of the following registry definition can be found in Common.reg.
; Define the default plugs that the Virtual VCR subunit should create on startup:
[HKEY_LOCAL_MACHINE\WDMDrivers\{A7F514FB-8FF1-442f-9547-5CCDA55EAE0}\0000\Plugs\0]
; MPEG, Output Plug, 26Mpbs peak
"MediaType"=dword:0
"Direction"=dword:2
"SubunitPlugID"=dword:0
"MaximumThroughput"=dword:18cba80
[HKEY_LOCAL_MACHINE\WDMDrivers\{A7F514FB-8FF1-442f-9547-5CCDA55EAE0}\0000\Plugs\1]
; MPEG, Input Plug
"MediaType"=dword:0
"SubunitPlugID"=dword:0
"Direction"=dword:1
Having plugs automatically allocated only indirectly makes the plugs known to the virtual subunit driver. This is indirect because the UNIT_AllocateLocalPlugCB function exposes the plugs to the virtual subunit driver.
At any time, the virtual subunit driver can issue an IOCTL_UNIT_QUERY_LOCAL_PLUGS command to the unit driver. This command permits the virtual subunit to receive updates on whether the state of any plug has changed. For example, if an external node connects to a local plug associated with the subunit, an IOCTL_UNIT_QUERY_LOCAL_PLUGS command that is pending at the time will receive a response describing the new connection state.
A virtual subunit may need to be notified when at least one connection to a plug is made or when all connections to a plug are broken. This information may need to be used as an indicator on whether the virtual subunit should start or stop streaming data at that time. Usually, streaming is started or stopped due to other indicators, such as the pressing of a Play or Stop button on a VCR.
Send Feedback on this topic to the authors