ksproxy plugin design issues

I am considering design choices about controlling custom aspects of a USB2
camera. This camera driver is based on usbcamd2 and is currently proxied by
ksproxy. The intent is to create ksproxy plug-ins to result in the
following:

1) 1 or more property pages such that amcap, graphedit or the like can set
these custom properties and
2) A way to programmatically set these same properties from a dshow filter
via some method.

Regarding the programmatic control of the filter:
a) Is it better to create a custom interface so that from the client filter
I can QI the base capture filter or is it better to QI the base capture
filter for IKsPropertySet and set the properties directly? The first choice
would seem better as it would introduce a layer of indirection such that
there would not be such a tight coupling between the minidriver and its
usermode clients.

b) If I were to use the custom interface, would it be better to implement it
via IKsPropertySet or via KsGetObjectHandle and issue IOCTL_KS_PROPERTY?
They seem identical.

Regarding ksproxy plugins in general. What is the mechinism linking the
extension COM objects to ksproxy? The examples I have seen all seem to have
an exact correspondence between one propertyset GUID in the minidriver with
one custom interface and one property page. Is this always the case? Are
the following alternatives possible:

1) A custom interface but with no associated property set?
2) Multiple custom property pages associated with a single property set?
3) A single propertyset with any number of interfaces and property pages
hung off it?


These questions reflect uncertainty about my ability to implement my current
thinking which is:
1) Add a one or more propertyset GUIDs to the minidriver to implement the
custom aspects of the camera.
2) Have a single custom COM interface in usermode to permit programatic
access to those aspects.
3) Have one or more property pages to permit amcap etc to access to aspects.
These property sheets would be implemented by using the custom inteface.

Regards,

Tom Udale

Max
Tue Oct 21 15:16:28 CDT 2003

> a) Is it better to create a custom interface so that from the client
filter
> I can QI the base capture filter or is it better to QI the base capture
> filter for IKsPropertySet and set the properties directly? The first
choice
> would seem better as it would introduce a layer of indirection such that
> there would not be such a tight coupling between the minidriver and its
> usermode clients.

Better to create a custom interface so that you could change things
underneath without bothering your users.


> b) If I were to use the custom interface, would it be better to implement
it
> via IKsPropertySet or via KsGetObjectHandle and issue IOCTL_KS_PROPERTY?
> They seem identical.

They are identical.
IKsPropertySet uses KsGetObjectHandle and then KsSynchronousDeviceControl.
I always use IKsPropertySet as it is a bit simple. The only limitation of it
is that you can't query property "advanced" data such as property range,
min/max values, step and such. To query these you will have to use
KsSynchronousDeviceControl.


> 1) A custom interface but with no associated property set?

Sure.

> 2) Multiple custom property pages associated with a single property set?

Yes, you can.

> 3) A single propertyset with any number of interfaces and property pages
> hung off it?

No. One interface per property set. Why would you want to have multiple?
Creating multiple pages makes sense as you might want to localize the
interface or simply you don't like how original (or generic) page looks
like.
But multiple interface...


> These questions reflect uncertainty about my ability to implement my
current
> thinking which is:
> 1) Add a one or more propertyset GUIDs to the minidriver to implement the
> custom aspects of the camera.
> 2) Have a single custom COM interface in usermode to permit programatic
> access to those aspects.
> 3) Have one or more property pages to permit amcap etc to access to
aspects.
> These property sheets would be implemented by using the custom inteface.

Just like any other interface.

If the things like these are related, create on GUID for a single property
set, implement one interface and one or more pages (if the information is
extensive it may very well NOT fit on the page).

If your properties can logically be split in groups, split them and have
multiple property sets, multiple interfaces and such.

-- Max.

Tom
Tue Oct 21 15:38:07 CDT 2003

Having discovered the key single page of documentation on making ksproxy
aggregates work
(http://msdn.microsoft.com/library/default.asp?url=/library/en-us/stream/hh/
stream/ksproxy_4ylv.asp) I think I see how I can do what I want.

1) Create at least one property set in the minidriver with its own GUID,
PSETID_1.

2) Create a custom interface with its own GUID, IID_1.

3) Create a usermode COM filter in mydll.dll with the same GUID as the
minidriver property set, PSETID_1, which also derives from the custom
interface.

4) Register the filter via the inf file:
HKCR,CLSID\{PSETID_1},,,%Happy_name%
HKCR,CLSID\{PSETID_1}\InprocServer32,,,kswdmcap.ax
HKCR,CLSID\{PSETID_1}\InprocServer32,ThreadingModel,,Both

5) Aggregate the filter:
HKLM,System\CurrentControlSet\Control\MediaInterfaces\{PSETID_1},,,%Happy_Na
me%
Without a IID entry, my filter should get a NonDelegatingQueryInterface for
every unknown interface that is QI'ed, for example IID_1.

6) Create as many property pages as needed (GUIDs PPID_1, PPID_2, etc) and
connect them also to the PSETID_1:
HKLM,System\CurrentControlSet\Control\MediaSets\{PSETID_1}\PropertyPages\{PP
ID_1},,,%PropPage1_Happy_Name%
HKLM,System\CurrentControlSet\Control\MediaSets\{PSETID_1}\PropertyPages\{PP
ID_2},,,%PropPage2_Happy_Name%
.. etc...
of course not forgetting to register them as COM objects in HKCR,CLSID.

7) If I want to add any differrent property sets to the minidriver (for what
ever reason) but proxy them with my original filter via the IID_1 interface,
I simply add the new GUIDs to the minidriver but do not make the
corresponding entry in
HKLM,System\CurrentControlSet\Control\MediaInterfaces. The orginal filter
will be able issue IKsPropertySet for either property set.

Does that all sound right?

Regards,
Tom

Tom
Tue Oct 21 16:14:15 CDT 2003

Max,

> Better to create a custom interface so that you could change things
> underneath without bothering your users.
My thinking also.

> They are identical.
> IKsPropertySet uses KsGetObjectHandle and then KsSynchronousDeviceControl.
> I always use IKsPropertySet as it is a bit simple. The only limitation of
it
> is that you can't query property "advanced" data such as property range,
> min/max values, step and such. To query these you will have to use
> KsSynchronousDeviceControl.
Ok.

> No. One interface per property set. Why would you want to have multiple?
> Creating multiple pages makes sense as you might want to localize the
> interface or simply you don't like how original (or generic) page looks
> like.
> But multiple interface...
Who knows? I was just trying get a feel for that is possible not why I
would do it :) To answer, maybe to support multiple incompatible versions
of an interface?

But when you say "No" do you mean no it cannot be done, or no one would not
want to do it? It seems like you could easily do it by not specifying an
IID binary entry in HKLM,System\CurrentControlSet\Control\MediaInterfaces
(see #5 below) and responding to several different IIDs in
NonDelegatingQueryInterface. At least that is what I gather from the magic
page of documentation I reference below.

Lastly, when you say "simply you don't like how original (or generic) page
looks" does that imply that I can prevent the default pages for things like
AMVideoProcAmp from showing up if I want to override them with something
else?



I replied to myself earlier but it got lost somehow - maybe it crashed with
your reply. I am sure it will show up now that I am going to include it
here:

-------------------------------------
Having discovered the key single page of documentation on making ksproxy
aggregates work
(http://msdn.microsoft.com/library/default.asp?url=/library/en-us/stream/hh/
stream/ksproxy_4ylv.asp) I think I see how I can do what I want.

1) Create at least one property set in the minidriver with its own GUID,
PSETID_1.

2) Create a custom interface with its own GUID, IID_1.

3) Create a usermode COM filter in mydll.dll with the same GUID as the
minidriver property set, PSETID_1, which also derives from the custom
interface.

4) Register the filter via the inf file:
HKCR,CLSID\{PSETID_1},,,%Happy_name%
HKCR,CLSID\{PSETID_1}\InprocServer32,,,kswdmcap.ax
HKCR,CLSID\{PSETID_1}\InprocServer32,ThreadingModel,,Both

5) Aggregate the filter:
HKLM,System\CurrentControlSet\Control\MediaInterfaces\{PSETID_1},,,%Happy_Na
me%
Without a IID binary entry, my filter should get a
NonDelegatingQueryInterface for
every unknown interface that is QI'ed, for example IID_1.

6) Create as many property pages as needed (GUIDs PPID_1, PPID_2, etc) and
connect them also to the PSETID_1:
HKLM,System\CurrentControlSet\Control\MediaSets\{PSETID_1}\PropertyPages\{PP
ID_1},,,%PropPage1_Happy_Name%
HKLM,System\CurrentControlSet\Control\MediaSets\{PSETID_1}\PropertyPages\{PP
ID_2},,,%PropPage2_Happy_Name%
.. etc...
of course not forgetting to register them as COM objects in HKCR,CLSID.

7) If I want to add any differrent property sets to the minidriver (for what
ever reason) but proxy them with my original filter via the IID_1 interface,
I simply add the new GUIDs to the minidriver but do not make the
corresponding entry in
HKLM,System\CurrentControlSet\Control\MediaInterfaces. The orginal filter
will be able issue IKsPropertySet for either property set.

Does that all sound right?

Regards,
Tom

Max
Tue Oct 21 16:46:01 CDT 2003

> But when you say "No" do you mean no it cannot be done, or no one would
not
> want to do it? It seems like you could easily do it by not specifying an
> IID binary entry in HKLM,System\CurrentControlSet\Control\MediaInterfaces
> (see #5 below) and responding to several different IIDs in
> NonDelegatingQueryInterface. At least that is what I gather from the
magic
> page of documentation I reference below.

I've never seen anybody do this.
Multiple property pages for a single set I have seen (and implemented myself
too), but not multiple interface handlers.
Maybe it can be done, but I don't see how.
Under MediaInterfaces key there are a bunch of GUID subkeys that represent
property sets. Each property set has default entry, which is the string
describing what it is and optionally "IID" entry describing the GUID of the
interface to map that property set to. I don't see how you can specify
another interface IID. IID2? IID_2?

I seem to remember hearing long time ago somebody from KS team saying that
only one interface handler per property set is supported. I am not sure, but
this is something that I believe I heard.


> Lastly, when you say "simply you don't like how original (or generic) page
> looks" does that imply that I can prevent the default pages for things
like
> AMVideoProcAmp from showing up if I want to override them with something
> else?

In your application yes. Just to QI ksproxy for ISpecifyPropertyPages and
through away those that you don't need and then do OleCreatePropertyFrame
for the rest.
For 3rd party app you could, of course, delete the property page that you
don't like, but it's kinda nasty. Besides, it could always come back without
you knowing it.


> 2) Create a custom interface with its own GUID, IID_1.

Usually by convension interface IID = Property Set GUID.
It made me wonder the first time I heard about it. The same GUID was used as
the property set GUID, COM object GUID and IID. After some thinking I came
to realize that there does not seem to be any conflict in doing it that way.


> Does that all sound right?

Yes, it does.

-- Max.

Tom
Tue Oct 21 17:42:09 CDT 2003

Max,

> I've never seen anybody do this.
> Multiple property pages for a single set I have seen (and implemented
myself
> too), but not multiple interface handlers.
> Maybe it can be done, but I don't see how.
> Under MediaInterfaces key there are a bunch of GUID subkeys that represent
> property sets. Each property set has default entry, which is the string
> describing what it is and optionally "IID" entry describing the GUID of
the
> interface to map that property set to. I don't see how you can specify
> another interface IID. IID2? IID_2?
Right, but in the magic doc page (the link I gave before does not seem to be
quite right; google for IKsAggregateControl
btw, this is the one and only page I have seen from MS about aggregation)
they say that filling the optional IID entry causes your extension filter to
receive NonDelegatingQueryInterface only for QIs on ksprox for the GUID
given by the optional IID entry. This is the behaviour you are describing
above.

However, if you do *not* include the optional IID entry, it says that your
filter will then receive NonDelegatingQueryInterface for *every* unknown QI
that ksproxy sees. To me, this means that you can basically add an
arbitrarily large number of interfaces off a single property set GUID.
Furthermore, given the functionality of IKsAggregateControl I am pretty sure
you can actually bind other completely separate COM servers to ksproxy, even
those not listed under MediaInterfaces at all. By my read,
IKsAggregateControl and an empty IID entry basically permit you to do
anything you want once the initial aggregation link between ksproxy and your
custom filter is established.

Lastly, there is one more very interesting tid-bit in the
IKsAggregateControl. They mention very briefly SetAliases which lets you
alias a property set server already registered under MediaInterfaces and
redirect to a new server. They do not mention much about it at all but it
immediately reminded me of the mysterious PageAliases entry in the
intelusb.inf file I was asking about in my "ksproxy inf file basic question"
thread. Do you think PageAliases is some even more hidden analog to
SetAliases but instead of aliasing property sets, it aliases property pages?
Perhaps in this way you can selectively override the built in property pages
(as discussed below)?


> For 3rd party app you could, of course, delete the property page that you
> don't like, but it's kinda nasty. Besides, it could always come back
without
> you knowing it.
I see. So there is no way to kind of "override" (in the c++ sense)
ksproxy's ISpecifyPropertyPages from within your filter (with the possible
exception of my wild-assed guess above :)

> Usually by convension interface IID = Property Set GUID.
> It made me wonder the first time I heard about it. The same GUID was used
as
> the property set GUID, COM object GUID and IID. After some thinking I came
> to realize that there does not seem to be any conflict in doing it that
way.
This is odd. But to be clear: the only true requirement is that the filter
GUID matches the propertyset GUID such that the MediaInterfaces link works
correctly.


> Yes, it does.
Exxxxxcccelent!

Thanks again for your (as always) generous help.

Regards,
Tom

Tom
Tue Oct 21 17:47:15 CDT 2003

Sorry, for anyone who is interested, the link I gave before is wrong. The
correct link is:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/stream/hh/s
tream/ksproxy_9e7n.asp?frame=true

This should take you to the docs for IKsAggregateControl.

> Having discovered the key single page of documentation on making ksproxy
> aggregates work
>
(http://msdn.microsoft.com/library/default.asp?url=/library/en-us/stream/hh/
> stream/ksproxy_4ylv.asp) I think I see how I can do what I want.
> .....etc....

Tom
Wed Oct 22 08:25:21 CDT 2003

> Lastly, there is one more very interesting tid-bit in the
> IKsAggregateControl. They mention very briefly SetAliases which lets you
> alias a property set server already registered under MediaInterfaces and
> redirect to a new server. They do not mention much about it at all but it
> immediately reminded me of the mysterious PageAliases entry in the
> intelusb.inf file I was asking about in my "ksproxy inf file basic
question"
> thread. Do you think PageAliases is some even more hidden analog to
> SetAliases but instead of aliasing property sets, it aliases property
pages?
> Perhaps in this way you can selectively override the built in property
pages

Ha! I may be right. The docs for SetAliases (which I take to mean Property
Set Aliases) are only two paragraphs:

-------------
"The proxy also allows a filter to override the COM server for a set
registered under MediaInterfaces. To override, create a SetAliases key under
the Plug and Play interface registry key. CLSID and FriendlyName are located
in the path HKLM\\SetAliases.

Also, enter the named value {set guid}, which is the string format of the
set GUID, as the binary value of the GUID for the replacement
MediaInterfaces subkey. Thus, for this filter or any object under this
filter, all sets with this GUID will use this alternate GUID to look for a
MediaInterfaces entry rather than the GUID of the set itself. The new
MediaInterfaces entry would be registered as usual."
-------------

Thus, add to the "Plug and Play interface registry key" (i.e. AddInterface)
a SetAliases key. Under that, you create a subkey of the GUID of the set
you want to replace. The value of that subkey is the GUID of the
replacement MediaInterfaces subkey.

Now, returning to my speculation that the mysterious PageAliases entry in
the intelusb inf file was an exact analog except for property pages; the
entry in question is:

[Intel.USBDCam.Intf.AddReg]
...regular stuff...
HKR,PageAliases,"{71F96464-78F3-11d0-A18C-00A0C9118956}",1,21,E8,C2,3D,
13,47, d2,11, 0xba, 0x41, 0x0, 0xa0, 0xc9, 0xd, 0x2b, 0x5

What is {71F96464-78F3-11d0-A18C-00A0C9118956}? That is the GUID for
"VideoProcAmp Property Page".

And what is this convoluted binary key
{3DC2E821-4713-11d2-BA41-00A0C90D2B05}? That turns out to be "Custom
VideoProcAmp Property Page". Both these keys are part of my standard XP
setup (it kind of had to be since the GUID was not in the INF file).
{3DC2E821-4713-11d2-BA41-00A0C90D2B05} is present only in HKCR/CLSID to
register the server.

So it looks like they (MS who wrote this intelusb.inf) are aliasing (i.e.
overriding) the standard VideoProcAmp property page with another MS supplied
custom page that serves the same purpose. Furthermore, if the second
paragraph of the SetAliases doc applies also to PageAliases, then this
override applies only "for this filter or any object under this filter"
rather than system wide.

Pretty cool huh?

Tom

Max
Wed Oct 22 13:24:40 CDT 2003

> Lastly, there is one more very interesting tid-bit in the
> IKsAggregateControl. They mention very briefly SetAliases which lets you
> alias a property set server already registered under MediaInterfaces and
> redirect to a new server. They do not mention much about it at all but it
> immediately reminded me of the mysterious PageAliases entry in the
> intelusb.inf file I was asking about in my "ksproxy inf file basic
question"
> thread. Do you think PageAliases is some even more hidden analog to
> SetAliases but instead of aliasing property sets, it aliases property
pages?
> Perhaps in this way you can selectively override the built in property
pages
> (as discussed below)?

Pretty neat.
Thanks for the information.


> > For 3rd party app you could, of course, delete the property page that
you
> > don't like, but it's kinda nasty. Besides, it could always come back
> without
> > you knowing it.
> I see. So there is no way to kind of "override" (in the c++ sense)
> ksproxy's ISpecifyPropertyPages from within your filter (with the possible
> exception of my wild-assed guess above :)

Well... contrary to GUID for your interface that no one knows about, this
GUID for generic property page is well known. What if you override it? It's
probably OK. But what if your end user then installs another software
package that does its own override and puts itself on top of your override?

This is a dangerous game to play and the results are absolutely
undetermined.


> > the property set GUID, COM object GUID and IID. After some thinking I
came
> > to realize that there does not seem to be any conflict in doing it that
> way.
> This is odd. But to be clear: the only true requirement is that the
filter
> GUID matches the propertyset GUID such that the MediaInterfaces link works
> correctly.

I thouthgt so.
On the other hand that's what MS uses all the time. The rules of COM don't
say that CLSID must be different from IID. It just says that for two
different objects CLSID must be unique and for two interfaces IIDs must be
different too.

Max
Wed Oct 22 13:26:59 CDT 2003

> So it looks like they (MS who wrote this intelusb.inf) are aliasing (i.e.
> overriding) the standard VideoProcAmp property page with another MS
supplied
> custom page that serves the same purpose. Furthermore, if the second
> paragraph of the SetAliases doc applies also to PageAliases, then this
> override applies only "for this filter or any object under this filter"
> rather than system wide.
>
> Pretty cool huh?

Are you saying that this remapping will only apply for the instance of the
device that registered the interface?
If that's true then everything is cool indeed.

Tom
Wed Oct 22 15:16:39 CDT 2003

Max,

> > So it looks like they (MS who wrote this intelusb.inf) are aliasing
(i.e.
> > overriding) the standard VideoProcAmp property page with another MS
> supplied
> > custom page that serves the same purpose. Furthermore, if the
second
> > paragraph of the SetAliases doc applies also to PageAliases, then
this
> > override applies only "for this filter or any object under this
filter"
> > rather than system wide.
> >
> > Pretty cool huh?
>
> Are you saying that this remapping will only apply for the instance of
the
> device that registered the interface?
> If that's true then everything is cool indeed.
That is how I read the docs. I mean this is pretty extended guessing:
PageAliases is not documented at all and SetAliases is barely
documented. But, from what MS did in the intelusb.inf file, it sure
looks like PageAliases does for property pages what SetAliases does for
property sets. And if that is the case, then orthoganality would
indicate the rest of the SetAliases probably applies also and the
aliasing would occur on a filter by filter basis. Needless to say, I
have not tried this but I intend to try it when I get a minidriver that
works.

Tom

Max
Wed Oct 22 16:46:09 CDT 2003

> > Are you saying that this remapping will only apply for the instance of
the
> > device that registered the interface?
> > If that's true then everything is cool indeed.
> That is how I read the docs. I mean this is pretty extended guessing:
> PageAliases is not documented at all and SetAliases is barely
> documented. But, from what MS did in the intelusb.inf file, it sure
> looks like PageAliases does for property pages what SetAliases does for
> property sets. And if that is the case, then orthoganality would
> indicate the rest of the SetAliases probably applies also and the
> aliasing would occur on a filter by filter basis. Needless to say, I
> have not tried this but I intend to try it when I get a minidriver that
> works.

Please let us know what you find out.
Thanks!

-- Max.