locked
Doc question about missing interfaces RRS feed

  • Question

  • I was looking thru the W8 sdk, and I noticed that some of the new MF interfaces are undocumented.

    I realized that W8 is still in beta mode, so I'm not sure whether the reason they are undocumented is that the docs still a work in progress, or that the interfaces are intended to be internal and are not for public use, or if it's simply an oversight.

    The interfaces in question are:

    • IMFAsyncCallbackLogging
    • IMFPMPClientApp
    • IMFPMPHostApp
    • IMFWorkQueueServicesEx

    Any insight would be appreciated.

    Tuesday, March 6, 2012 3:10 AM

Answers

  • (2) Yes, the differentiation between VS11 for Metro apps and the full Windows 8 SDK is not very good.  Unfortunately, this is well out of the realm of multimedia so I do not have much influence over what happens.

    (5) This is a small enum so it is not really on the disaster scale yet.  It might get fixed if time permits, but it is not a priority for us right now.

    (7) I must have missed this.  The current use of the API by the media engine does not require anything more than a DWORD, but I can see the problem of consistency and flexibility.  I am not sure if we will be willing to take unnecessary API changes at this point, but I will bring it up.

    • Marked as answer by LGS Tuesday, April 17, 2012 8:22 PM
    Tuesday, April 17, 2012 7:47 PM

All replies

  • Another doc question:

    This page (http://technet.microsoft.com/en-us/query/hh447846)talks about mfcaptureengine.h.  However, that file is not included in the current W8 SDK.  Is this interface intended to be hidden?  Or has the file been accidentally omitted from the SDK?

    Wednesday, March 14, 2012 7:25 PM
  • And while we are on the subject of missing files, what's the story with these files:

    dxva2api.idl
    dxvahd.idl
    evr.idl
    evr9.h
    mfmp2dlna.idl
    mfplay.idl
    opmapi.idl
    Wmcontainer.idl

    These were all in the W7 PSDK, but are (currently) missing from W8.  I didn't do a thorough check, but it doesn't appear that the interfaces from these files have been moved elsewhere.  Are all these interfaces deleted from W8?  Or are you just still marking everything with all the new WINAPI_FAMILY stuff and these files will be available in the next SDK drop?

    Yes, I *know* W8 is still in beta.  But what's the alternative?  I can point these things out now and get yelled at for raising issues on a beta, or I can wait for RTM and get told that it's too late to fix anything.

    Wednesday, March 14, 2012 7:54 PM
  • Well, given the encouragement I've received so far on this thread (well, nobody has yelled at me, that's encouraging),  I'm going to keep posting comments:

    Looking at the new interfaces, IMFMediaEngineNotify has a definition that just doesn't look right:

    HRESULT EventNotify(
      [in]  DWORD event,
      [in]  DWORD_PTR param1,
      [in]  DWORD param2
    );
    Most every other event interface I've seen:


    IMediaEventSink
    IMediaEvent
    IVMRSurfaceAllocatorNotify9
    PostMessage
    waveInMessage
    mixerMessage

    uses 2 DWORD_PTRs (for param1 and param2).  

    While there is no reason that this interface *must* use the same parameter list as every other known notify method, but it also seems possible that this is some type of mistake.  There's also some concern about what might happen if -this- event method is used in combination with one of the other "standard" methods.  It will work on x86, and MIGHT work on x64 (sometimes, if you are lucky) making for a difficult-to-track-down type of bug.

    Upgrading param2 to DWORD_PTR increases the flexibility of the method as well as increasing it's compatibility for use with other eventing methods.

    So now the question is, are we at the "too early for beta feedback" stage or at the "too late to change it" stage?

    I've got more comments/questions, but they'll have to wait.  In the meantime, it would be nice to know if anyone is listening.

    Hello?

    Friday, March 16, 2012 1:18 AM
  • Next observation:

    The docs for IMFMediaEngineEx::GetStreamSelection (http://msdn.microsoft.com/en-us/library/windows/desktop/hh447944%28v=vs.85%29.aspx) say that the second parameter is an out parameter.  That makes sense to me.  However, mfmediaengine.idl says:

        HRESULT GetStreamSelection(  
            [in, annotation("_In_")] DWORD dwStreamIndex,
            [in, annotation("_In_")] BOOL* pEnabled
            );
    

    That seems wrong.

    Saturday, March 17, 2012 7:22 AM
  • Ok, how's this one for subtle.  Nearly all the parameters in header files these days have decorations.  But not all.  What's up with the pStream in:

    cpp_quote( "STDAPI MFCreateMFByteStreamOnStream(" )
    cpp_quote( "    IStream*        pStream," )
    cpp_quote( "    _Outptr_ IMFByteStream** ppByteStream);" )
    

    I would kinda expect it to look like this one:

    cpp_quote( "STDAPI MFCreateStreamOnMFByteStream(" ) 
    cpp_quote( "    _In_ IMFByteStream* pByteStream," ) 
    cpp_quote( "    _Outptr_ IStream** ppStream);" )
    

    And while we're doing subtle, back in the Vista days, the MediaEventType enum used to be in the form:

             MESessionTopologiesCleared = (MESessionTopologySet + 1),
             MESessionStarted = (MESessionTopologiesCleared + 1),

    Then in W7, these all got changed to be their numeric values:

            MESessionTopologiesCleared    = 102,
            MESessionStarted    = 103,

    Since these are functionally identical, I don't know why this was changed, but I'm sure there was a good reason.  However in W8, the new entries in the header use the old format:

            METransformNeedInput    = ( METransformUnknown + 1 ) ,
            METransformHaveOutput    = ( METransformNeedInput + 1 ) ,
            METransformDrainComplete    = ( METransformHaveOutput + 1 ) ,
            METransformMarker    = ( METransformDrainComplete + 1 ) ,

    Monday, March 19, 2012 12:47 AM
  • So, today's issue starts with an interesting philosophical question:

    How does one "release" a void pointer?

    On its face the question is unanswerable.  Void pointers, by definition, are an unknown type, so you cannot know how to do anything with them.  By way of contrast, IUnknown pointers have a well-known mechanism for releasing.

    With that thought in mind, consider this (from the docs for IMFPMPHost::CreateObjectByCLSID):

    HRESULT CreateObjectByCLSID( [in] REFCLSID clsid, [in] IStream *pStream, [in] REFIID riid, [out] void **ppv );

    ppv [out] Receives a pointer to the requested interface. The caller must release the interface.

    To me, this means that ppv is wrongly defined as a void **.  This should be an IUnknown **.  Either that, or this method needs to clarify mightily what it means by "caller must release."  How do you even know the interface must be released if you don't know what it is?

    Is it "correct" to call the returned value an IUnknown, even if it is an IID_ISomethingElse?  Well, if (as I suspect) the supported interfaces all derive from IUnknown (or we won't know how to "release" them anyway), I believe it is accurate to call it an IUnknown.

    For support, I give you:

    Both of which seem to have no problem using IUnknown for similar uses.

    Note that IMFPMPHost is NOT the only W8 addition to have this problem.  In fact, some of the W7s are like this as well.

    How likely is it that this (and some of the other issues above) will get changed?  Well...

    A number of years ago, I suggested that IDL files be made available sooner in the development cycle.  Let's face it, if I had raised these issues back when the interface was first being designed, it would have been a no-brainer to do it "right."  Today, it may be more challenging.

    Just saying...

    Wednesday, March 21, 2012 5:33 AM
  • Thanks for all the feedback.

    (1) Undocumented interfaces - I reported this to our documenation team and they will be fixing this.  The focus has been on documenting Metro APIs, so they have yet to catch up on some of the desktop documentation.

    (2) Missing files - I see these in my install of the Win8 SDK -- for example, I see C:\Program Files (x86)\Windows Kits\8.0\include\um\evr.idl.  Did you just install the VS11 express beta for building Metro apps, or the full Windows 8 SDK?

    (3) GetStreamSelection annotation -- yep, this is wrong.  I will see about fixing this.

    (4) MFCreateByteStreamOnStream annotation -- same here

    (5) Enumeration values -- having implicit values for large enums is a disaster waiting to happen, as it is easy to insert a value in the middle and suddenly change the value of what should be a constant.  That's why we moved to explicit values for the session event enums.  I actually prefer this for all external-facing enums, but sometimes like in the transform event case someone uses the '+ 1' style.

    (6) void** outputs -- This is just the convention for obtaining an interface in COM, the same way that IUnknown::QueryInterface or CoCreateInstance is implemented.  Being consistent with COM convention has more value than the comprehension improvements of using IUnknown.  I would recommend using the IID_PPV_ARGS macro for all of these types of functions, as it applies some checking to make sure that the right arguments are getting passed.

    The CreateObjectFromURL API is quite inconvenient because it does not have an IID parameter.  Casting the result to ISomethingElse breaks if there is a COM proxy involved, so a QI is always necessary even if the application knows what kind of object it is getting back.

    Friday, March 23, 2012 11:57 PM
  • Hey Matt, thanks for the response.

    2) Ahh, sure enough.  I was apparently mislead by the VS11 docs when it stated "It includes the Windows 8 SDK, templates and enables access to Windows 8 APIs."  Silly me, I assumed this meant it included the Windows 8 SDK.  If I download from http://msdn.microsoft.com/en-us/windows/desktop/hh852363 all the files I mentioned are present.  Perhaps the Windows SDK folks could start talking about the difference between these 2 SDKs?  Maybe one should be called the "Metro SDK?"

    5) So do you plan to change this like you changed all the others?  Or leave this "disaster" and wait?

    7) No comments on the EventNotify?

    Wednesday, April 4, 2012 1:32 AM
  • (2) Yes, the differentiation between VS11 for Metro apps and the full Windows 8 SDK is not very good.  Unfortunately, this is well out of the realm of multimedia so I do not have much influence over what happens.

    (5) This is a small enum so it is not really on the disaster scale yet.  It might get fixed if time permits, but it is not a priority for us right now.

    (7) I must have missed this.  The current use of the API by the media engine does not require anything more than a DWORD, but I can see the problem of consistency and flexibility.  I am not sure if we will be willing to take unnecessary API changes at this point, but I will bring it up.

    • Marked as answer by LGS Tuesday, April 17, 2012 8:22 PM
    Tuesday, April 17, 2012 7:47 PM
  • Thank you.  That's all I was hoping for.

    It's in my nature that when I see problems I mention them to those in charge.  Sometimes people are receptive, sometimes they aren't.  Sometimes things get changed, and sometimes they don't.  But in the end, I can say that I've done what I can to make things better.

    I realize that none of these items were world-changing, OS-crashing, gaping-security-hole issues.  But I reported what I saw.  Thanks for taking the time to listen.

    Tuesday, April 17, 2012 8:22 PM