home *** CD-ROM | disk | FTP | other *** search
/ The Net: Ultimate Internet Guide / WWLCD1.ISO / mac / SiteBldr / AMOVIE / SDK / _SETUP / COMMON.Z / axextend.idl < prev    next >
Encoding:
Text File  |  1996-06-22  |  39.4 KB  |  1,055 lines
  1. //==========================================================================;
  2. //
  3. //  THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  4. //  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  5. //  IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR
  6. //  PURPOSE.
  7. //
  8. //  Copyright (c) 1992 - 1996  Microsoft Corporation.  All Rights Reserved.
  9. //
  10. //--------------------------------------------------------------------------;
  11.  
  12. // This file contains interface definitions for the ActiveX streaming and
  13. // synchronisation architecture. Core interfaces shared with the Clockwork
  14. // implementation are in AXCore.idl, and control interfaces for the type
  15. // library are in Control.odl
  16.  
  17. // include after unknwn.idl, objidl.idl and axcore.idl
  18.  
  19.  
  20. // forward declarations - these are the interfaces declared in this file
  21.  
  22. interface IEnumRegFilters;
  23. interface IFileSourceFilter;
  24. interface IFileSinkFilter;
  25. interface IGraphBuilder;
  26. interface IFilterMapper;
  27. interface IMediaEventSink;
  28. interface IOverlay;
  29. interface IOverlayNotify;
  30. interface IQualityControl;
  31.  
  32.  
  33. //==========================================================================
  34. //==========================================================================
  35. // IEnumRegFilters interface -- enumerates registered filters.
  36. // enumerator interface returned from IFilterMapper::EnumMatchingFilters().
  37. // based on IEnum pseudo-template
  38. //==========================================================================
  39. //==========================================================================
  40.  
  41. typedef struct {
  42.     CLSID Clsid;             // class id of the filter
  43.     LPWSTR Name;             // name of filter
  44. } REGFILTER;
  45.  
  46. [
  47. object,
  48. uuid(56a868a4-0ad4-11ce-b03a-0020af0ba770),
  49. pointer_default(unique)
  50. ]
  51.  
  52. // The point of the mapper is to avoid loading filters.  By looking in the
  53. // registry we can reduce the number of filters which must be loaded and tried.
  54. // This enumerator returns descriptors of filters (including the GUIDs that
  55. // CoCreateInstance can instantiate).  The filters themselves are not loaded.
  56.  
  57. interface IEnumRegFilters : IUnknown {
  58.     import "unknwn.idl";
  59.  
  60.     // The caller must use CoTaskMemFree to free each REGFILTER* returned
  61.     // in the array.
  62.     HRESULT Next
  63.         ( [in]  ULONG cFilters,           // place this many filters...
  64.           [out] REGFILTER ** apRegFilter, // ...in this array of REGFILTER*
  65.           [out] ULONG * pcFetched         // actual count passed returned here
  66.         );
  67.  
  68.     // I can't think why anyone would want to skip, so it's not implemented.
  69.     // (anyone who thinks they know what they would be skipping over is probably
  70.     // missing some piece of the jigsaw). This ALWAYS returns E_NOTIMPL.
  71.  
  72.     HRESULT Skip(
  73.         [in] ULONG cFilters
  74.     );
  75.  
  76.     HRESULT Reset(void);
  77.  
  78.     // No cloning either - also ALWAYS returns E_NOTIMPL.
  79.  
  80.     HRESULT Clone(
  81.         [out] IEnumRegFilters **ppEnum
  82.     );
  83. }
  84.  
  85.  
  86. typedef IEnumRegFilters *PENUMREGFILTERS;
  87.  
  88.  
  89.  
  90.  
  91. //========================================================================
  92. //========================================================================
  93. // abstraction representing the registered information about filters.
  94. // This allows properties of filters to be looked up without loading them.
  95. //========================================================================
  96. //========================================================================
  97.  
  98. [
  99. object,
  100. uuid(56a868a3-0ad4-11ce-b03a-0020af0ba770),
  101. pointer_default(unique)
  102. ]
  103. interface IFilterMapper : IUnknown {
  104.     import "unknwn.idl";
  105.  
  106.     //==========================================================================
  107.     // Registration functions.
  108.     // A filter should be registered before any other use.
  109.     // The registration can be NON_VOLATILE (i.e. permanent, do once ever)
  110.     // or VOLATILE (once per boot of the system).
  111.     // UnregisterFilter (obviously) removes the registration.
  112.     // The action of any of the other calls on unregistered filters is undefined.
  113.     // it will either work or you'll get an error, but I'm not saying which.
  114.     //==========================================================================
  115.  
  116.     // Four predefined values controling the oreder in which filters are tried
  117.     // for intelligent graph building.  Intermediate values are legal.
  118.     // Any value <=MERIT_DO_NOT_USE will mean that the filter will never
  119.     // be tried by the filtergrah to automatically complete a connection.
  120.  
  121.     enum { MERIT_PREFERRED = 0x800000,
  122.            MERIT_NORMAL    = 0x600000,
  123.            MERIT_UNLIKELY  = 0x400000,
  124.            MERIT_DO_NOT_USE= 0x200000
  125.          };
  126.  
  127.     // Register a filter
  128.  
  129.     HRESULT RegisterFilter
  130.         ( [in] CLSID   clsid,    // GUID of the filter
  131.           [in] LPCWSTR Name,     // Descriptive name for the filter
  132.           [in] DWORD   dwMerit   // DO_NOT_USE, UNLIKELY, NORMAL or PREFERRED.
  133.         );
  134.  
  135.  
  136.     // Register an identifiable instance of a filter.  This deals with cases
  137.     // such as two similar sound cards which are driven by the same driver,
  138.     // but we want to choose which oif these cards the sound will come out of.
  139.     // This is not needed if there is only one instance of the filter
  140.     // (e.g. there is only one sound card in the machine) or if all instances
  141.     // of the filter are equivalent.
  142.  
  143.     // The filter itself must have already been registered   // ??? Is that true?
  144.     HRESULT RegisterFilterInstance
  145.         ( [in]  CLSID  clsid,      // GUID of the filter
  146.           [in]  LPCWSTR Name,      // Descriptive name of instance.
  147.           [out] CLSID *MRId        // Returned Media Resource Id.  A
  148.                                    // locally unique id for this instance
  149.                                    // of this filter
  150.         );
  151.  
  152.  
  153.     HRESULT RegisterPin
  154.         ( [in] CLSID   Filter,           // GUID of filter
  155.           [in] LPCWSTR Name,             // Name of the pin
  156.           [in] BOOL    bRendered,        // The filter renders this input
  157.           [in] BOOL    bOutput,          // TRUE if this is an Output pin
  158.           [in] BOOL    bZero,            // TRUE if OK for zero instances of pin
  159.                                          // In this case you will have to Create
  160.                                          // a pin to have even one instance
  161.           [in] BOOL    bMany,            // TRUE if OK for many instances of pin
  162.           [in] CLSID   ConnectsToFilter, // Filter it connects to if it has
  163.                                          // subterranean connection, else NULL
  164.           [in] LPCWSTR ConnectsToPin     // Name of pin it connects to
  165.                                          // NULL for output pins
  166.         );
  167.  
  168.     HRESULT RegisterPinType
  169.         ( [in] CLSID   clsFilter,        // GUID of filter
  170.           [in] LPCWSTR strName,          // Descriptive name of the pin
  171.           [in] CLSID   clsMajorType,     // Major type of the data stream
  172.           [in] CLSID   clsSubType        // Sub type of the data stream
  173.         );
  174.  
  175.  
  176.     HRESULT UnregisterFilter
  177.         ( [in] CLSID  Filter             // GUID of filter
  178.         );
  179.  
  180.  
  181.     HRESULT UnregisterFilterInstance
  182.         ( [in] CLSID  MRId               // Media Resource Id of this instance
  183.         );
  184.  
  185.  
  186.     HRESULT UnregisterPin
  187.         ( [in] CLSID   Filter,           // GUID of filter
  188.           [in] LPCWSTR Name              // Name of the pin
  189.         );
  190.  
  191.  
  192.     // Set *ppEnum to be an enumerator for filters matching the requirements.
  193.  
  194.     HRESULT EnumMatchingFilters
  195.        ( [out] IEnumRegFilters **ppEnum  // enumerator returned
  196.        , [in]  DWORD dwMerit             // at least this merit needed
  197.        , [in]  BOOL  bInputNeeded        // need at least one input pin
  198.        , [in]  CLSID clsInMaj            // input major type
  199.        , [in]  CLSID clsInSub            // input sub type
  200.        , [in]  BOOL  bRender             // must the input be rendered?
  201.        , [in]  BOOL  bOututNeeded        // need at least one output pin
  202.        , [in]  CLSID clsOutMaj           // output major type
  203.        , [in]  CLSID clsOutSub           // output sub type
  204.        );
  205.  
  206. }
  207.  
  208. //========================================================================
  209. //========================================================================
  210. // Defines IQualityControl interface
  211. //
  212. // Defines quality messages and allows a quality manager to install itself
  213. // as the sink for quality messages.
  214. //========================================================================
  215. //========================================================================
  216.  
  217. typedef enum {
  218.     Famine,
  219.     Flood
  220. } QualityMessageType;
  221.  
  222. typedef struct{
  223.     QualityMessageType Type;
  224.     long                Proportion;   // milli-units.  1000 = no change
  225.                             // for Flood:
  226.                             // What proportion of the media samples currently
  227.                             // coming through are required in the future.
  228.                             // 800 means please drop another 20%
  229.                             // For Famine:
  230.                             // How much to "keep in" e.g. 800 means send me
  231.                             // 20% less e.g. by dropping 20% of the samples.
  232.                             // 1100 would mean "I'm coping, send me more".
  233.     REFERENCE_TIME       Late;
  234.                             // How much you need to catch up by
  235.     REFERENCE_TIME       TimeStamp;
  236.                             // The stream time when this was generated (probably
  237.                             // corresponds to the start time on some sample).
  238. } Quality;
  239.  
  240. typedef IQualityControl *PQUALITYCONTROL;
  241.  
  242.  
  243. [
  244. object,
  245. uuid(56a868a5-0ad4-11ce-b03a-0020af0ba770),
  246. pointer_default(unique)
  247. ]
  248. interface IQualityControl : IUnknown {
  249.  
  250.     // Notify the recipient that a quality change is requested.
  251.     // pSelf is the IFilter* of the sender.
  252.     // this is sent from a filter
  253.     // to (the quality manager or) an upstream peer.
  254.     HRESULT Notify
  255.         ( [in] IFilter * pSelf,
  256.           [in] Quality q
  257.         );
  258.  
  259.     // Notify the recipient that future quality messages are to be sent
  260.     // to iqc.  If piqc is NULL then quality messages are to default back to
  261.     // the upstream peer.
  262.     // This is sent from the quality manager to a filter.
  263.     // The recipient should hold piqc as a WEAK reference,
  264.     // i.e. do not AddRef it, do not Release it.
  265.     HRESULT SetSink
  266.         ( [in] IQualityControl * piqc
  267.         );
  268. }
  269.  
  270. //=====================================================================
  271. //=====================================================================
  272. // Definitions required for overlay transport
  273. //=====================================================================
  274. //=====================================================================
  275.  
  276.  
  277. // Used to communicate the colour that the IOverlay client wants the window
  278. // painted in so that it can draw directly to the correct clipping region
  279. // A colour key can be described in two alternate ways, the first is by a
  280. // range of one or more (system) palette indices. The second is by defining
  281. // a colour cube with two RGB values, any of which would be acceptable.
  282. //
  283. // The CK values are consistent with GDI PALETTEINDEX and PALETTERGB macros
  284.  
  285.  
  286. enum { CK_NOCOLORKEY = 0x0,     // No color key is required
  287.        CK_INDEX       = 0x1,    // Index into the current system palette
  288.        CK_RGB         = 0x2 };  // Color key is an RGB value (or range)
  289.  
  290. typedef struct tagCOLORKEY {
  291.  
  292.     DWORD    KeyType;           // Explains meaning of the structure
  293.     DWORD    PaletteIndex;      // Palette index if available
  294.     COLORREF LowColorValue;     // Low colour space RGB value
  295.     COLORREF HighColorValue;    // Defines the high RGB value
  296.  
  297. } COLORKEY;
  298.  
  299. // When a filter sets up an advise link it can ask that only certain types
  300. // of notifications be sent, for example just palette changes. While this
  301. // doesn't mean that the other notification call backs won't ever be called
  302. // the IOverlay implementation may use this as an efficiency optimisation
  303.  
  304. enum { ADVISE_NONE = 0x0,               // No notifications required
  305.        ADVISE_CLIPPING = 0x1,           // Synchronous clip information
  306.        ADVISE_PALETTE = 0x2,            // Palette change notifications
  307.        ADVISE_COLORKEY = 0x4,           // Called when colour key changes
  308.        ADVISE_POSITION = 0x8 };         // Likewise when window moves etc
  309.  
  310. const DWORD ADVISE_ALL = ADVISE_CLIPPING |
  311.                          ADVISE_PALETTE |
  312.                          ADVISE_COLORKEY |
  313.                          ADVISE_POSITION;
  314.  
  315. // This isn't defined when you run IDL
  316.  
  317. cpp_quote("#ifndef _WINGDI_")
  318.  
  319. typedef struct _RGNDATAHEADER {
  320.     DWORD dwSize;
  321.     DWORD iType;
  322.     DWORD nCount;
  323.     DWORD nRgnSize;
  324.     RECT  rcBound;
  325. } RGNDATAHEADER;
  326.  
  327. typedef struct _RGNDATA {
  328.     RGNDATAHEADER rdh;
  329.     char Buffer[1];
  330. } RGNDATA;
  331.  
  332. cpp_quote("#endif")
  333.  
  334.  
  335. //=====================================================================
  336. //=====================================================================
  337. // Defines IOverlayNotify interface
  338. //
  339. // This interface gives asynchronous notifications of changes to the
  340. // rendering window - such as changes to the exposed window area
  341. //=====================================================================
  342. //=====================================================================
  343.  
  344. [
  345. object,
  346. local,
  347. uuid(56a868a0-0ad4-11ce-b03a-0020af0ba770),
  348. pointer_default(unique)
  349. ]
  350. interface IOverlayNotify : IUnknown {
  351.  
  352.     // IOverlayNotify methods
  353.  
  354.     // This notifies the filter of palette changes, the filter should copy
  355.     // the array of RGBQUADs if it needs to use them after returning. This
  356.     // is not called when the palette is actually changed in the display
  357.     // but at a short time after (in sync with WM_PALETTECHANGED messages)
  358.  
  359.     HRESULT OnPaletteChange(
  360.         [in] DWORD dwColors,                // Number of colours present
  361.         [in] const PALETTEENTRY *pPalette); // Array of palette colours
  362.  
  363.     // This provides synchronous clip changes so that the client is called
  364.     // before the window is moved to freeze the video, and then when the
  365.     // window has stabilised it is called again to start playback again.
  366.     // If the window rect is all zero then the window is invisible, the
  367.     // filter must take a copy of the information if it wants to keep it
  368.  
  369.     HRESULT OnClipChange(
  370.         [in] const RECT *pSourceRect,       // Region of video to use
  371.         [in] const RECT *pDestinationRect,  // Where video goes
  372.         [in] const RGNDATA *pRgnData);      // Defines clipping information
  373.  
  374.     HRESULT OnColorKeyChange([in] const COLORKEY *pColorKey);
  375.  
  376.     // The calls to OnClipChange happen in sync with the window. So it is
  377.     // called with an empty clip list before the window moves to freeze
  378.     // the video, and then when the window has stabilised it is called
  379.     // again with the new clip list. The OnPositionChange callback is for
  380.     // overlay cards that don't want the expense of synchronous clipping
  381.     // updates and just want to know when the source or destination video
  382.     // positions change. They will NOT be called in sync with the window
  383.     // but at some point after the window has changed (basicly in time
  384.     // with WM_SIZE etc messages received). This is therefore suitable
  385.     // for overlay cards that don't inlay their data to the frame buffer
  386.     // NOTE the destination is NOT clipped to the visible display area
  387.  
  388.     HRESULT OnPositionChange([in] const RECT *pSourceRect,
  389.                              [in] const RECT *pDestinationRect);
  390. }
  391.  
  392. typedef IOverlayNotify *POVERLAYNOTIFY;
  393.  
  394.  
  395. //=====================================================================
  396. //=====================================================================
  397. // Defines IOverlay interface
  398. //
  399. // This interface provides information so that a filter can write direct to
  400. // the frame buffer while placing the video in the correct window position
  401. //=====================================================================
  402. //=====================================================================
  403.  
  404. [
  405. object,
  406. local,
  407. uuid(56a868a1-0ad4-11ce-b03a-0020af0ba770),
  408. pointer_default(unique)
  409. ]
  410. interface IOverlay : IUnknown {
  411.  
  412.     // IOverlay methods
  413.  
  414.     HRESULT GetPalette(
  415.         [out] DWORD *pdwColors,              // Number of colours present
  416.         [out] PALETTEENTRY **ppPalette);     // Where to put palette data
  417.  
  418.     HRESULT SetPalette(
  419.         [in] DWORD dwColors,                 // Number of colours present
  420.         [in] PALETTEENTRY *pPalette);        // Colours to use for palette
  421.  
  422.     // If you change the colour key through SetColorKey then all the advise
  423.     // links will receive an OnColorKeyChange callback with the new colour
  424.  
  425.     HRESULT GetDefaultColorKey([out] COLORKEY *pColorKey);
  426.     HRESULT GetColorKey([out] COLORKEY *pColorKey);
  427.     HRESULT SetColorKey([in,out] COLORKEY *pColorKey);
  428.     HRESULT GetWindowHandle([out] HWND *pHwnd);
  429.  
  430.     // The IOverlay implementation allocates the memory for the clipping
  431.     // rectangles as it can be variable in length. The filter calling
  432.     // this method should free the memory when it is finished with it
  433.  
  434.     HRESULT GetClipList([out] RECT *pSourceRect,
  435.                         [out] RECT *pDestinationRect,
  436.                         [out] RGNDATA **ppRgnData);
  437.  
  438.     // Returns the current video source and destination
  439.  
  440.     HRESULT GetVideoPosition([out] RECT *pSourceRect,
  441.                              [out] RECT *pDestinationRect);
  442.  
  443.     HRESULT Advise(
  444.         [in] IOverlayNotify *pOverlayNotify, // Notification interface
  445.         [in] DWORD dwInterests);             // Callbacks interested in
  446.  
  447.     HRESULT Unadvise();                      // Stop the callbacks now
  448. }
  449.  
  450. typedef IOverlay *POVERLAY;
  451.  
  452.  
  453. //=====================================================================
  454. //=====================================================================
  455. // control related interfaces (others are defined in control.odl)
  456. //=====================================================================
  457. //=====================================================================
  458.  
  459.  
  460. //=====================================================================
  461. //=====================================================================
  462. // Defines IMediaEventSink interface
  463. //
  464. // Exposed by filtergraph. Called by filters to notify events. Will be
  465. // passed on to application by the IMediaControl event methods.
  466. //=====================================================================
  467. //=====================================================================
  468.  
  469. [
  470.         object,
  471.         uuid(56a868a2-0ad4-11ce-b03a-0020af0ba770),
  472.         pointer_default(unique)
  473. ]
  474. interface IMediaEventSink : IUnknown {
  475.  
  476.     // notify an event. will be queued, but not delivered to
  477.     // the application on this thread.
  478.     HRESULT Notify(
  479.         [in] long EventCode,
  480.         [in] long EventParam1,
  481.         [in] long EventParam2
  482.     );
  483. }
  484.  
  485. typedef IMediaEventSink *PMEDIAEVENTSINK;
  486.  
  487. //=====================================================================
  488. //=====================================================================
  489. // Defines IFileSourceFilter interface
  490. //
  491. // Exposed by source filters to set the file name and media type.
  492. //=====================================================================
  493. //=====================================================================
  494.  
  495. [
  496.         object,
  497.         uuid(56a868a6-0ad4-11ce-b03a-0020af0ba770),
  498.         pointer_default(unique)
  499. ]
  500. interface IFileSourceFilter : IUnknown {
  501.  
  502.     // Load a file and assign it the given media type
  503.     HRESULT Load(
  504.         [in] LPCOLESTR pszFileName,     // Pointer to absolute path of file to open
  505.         [in] const AM_MEDIA_TYPE *pmt   // Media type of file - can be NULL
  506.     );
  507.     // Get the currently loaded file name
  508.     HRESULT GetCurFile(
  509.         [out] LPOLESTR *ppszFileName,   // Pointer to the path for the current file
  510.         [out] AM_MEDIA_TYPE *pmt        // Pointer to the media type
  511.     );
  512. }
  513.  
  514. typedef IFileSourceFilter *PFILTERFILESOURCE;
  515.  
  516. //=====================================================================
  517. //=====================================================================
  518. // Defines IFileSinkFilter interface
  519. //
  520. // Exposed by renderers to set the output file name.
  521. //=====================================================================
  522. //=====================================================================
  523.  
  524. [
  525.         object,
  526.         uuid(a2104830-7c70-11cf-8bce-00aa00a3f1a6),
  527.         pointer_default(unique)
  528. ]
  529. interface IFileSinkFilter : IUnknown {
  530.  
  531.     // Output to this file
  532.     HRESULT SetFileName(
  533.         [in] LPCOLESTR pszFileName,     // Pointer to absolute path of output file
  534.         [in] const AM_MEDIA_TYPE *pmt   // Media type of file - can be NULL
  535.     );
  536.     // Get the current file name
  537.     HRESULT GetCurFile(
  538.         [out] LPOLESTR *ppszFileName,   // Pointer to the path for the current file
  539.         [out] AM_MEDIA_TYPE *pmt        // Pointer to the media type
  540.     );
  541. }
  542.  
  543. typedef IFileSinkFilter *PFILTERFILESINK;
  544.  
  545. //=====================================================================
  546. //=====================================================================
  547. // Defines IFileAsyncIO interface
  548. //
  549. // Exposed by high performance file readers
  550. //=====================================================================
  551. //=====================================================================
  552.  
  553. typedef struct _AsyncIOReq {
  554.    DWORD         engine[4];  // used by IO engine
  555.    [size_is(cb)] BYTE * lpv; // points to buffer of data to be transferred
  556.    DWORD         cb;         // size of data to be transferred
  557.  
  558.    // the following 4 fields intentionally mimic an OVERLAPPED structure
  559.    //
  560.    DWORD         dwError;    // on return, contains error/success code
  561.    DWORD         cbDone;     // number of bytes actually transferred
  562.    LARGE_INTEGER liPos;      // 64 bit seek location. on return contains read/write location
  563.    DWORD         hEvent;     // handle (used to mimic OVERLAPPED structure)
  564.  
  565.    DWORD         dwUser;     // preserved, for user data
  566.    } AsyncIOReq;
  567.  
  568. [
  569.         object,
  570.         uuid(56a868a7-0ad4-11ce-b03a-0020af0ba770),
  571.         pointer_default(unique)
  572. ]
  573. interface IFileAsyncIO : IUnknown {
  574.  
  575.     // query the required alignment for io buffers & sizes
  576.     //
  577.     HRESULT QueryAlignment (
  578.         [out] LPDWORD  pdwAlign
  579.     );
  580.  
  581.     // do async, aligned read from a specific location in the file
  582.     //
  583.     HRESULT Read (
  584.         [in] AsyncIOReq * pReq
  585.     );
  586.  
  587.     // do async, aligned write to a specific location in the file
  588.     // the file may be extended as a result.
  589.     //
  590.     HRESULT Write (
  591.         [in] AsyncIOReq * pReq
  592.     );
  593.  
  594.     // wait for the next available read to complete, on success
  595.     // returns the buffer pointer and
  596.     //
  597.     HRESULT WaitForNext (
  598.         [out] AsyncIOReq **  ppReq,    // returns pointer to next request to complete
  599.         [in]  DWORD          dwTimeout // how long to wait, 0 does not wait
  600.     );
  601.  
  602.     // wait for a specific io request to complete
  603.     //
  604.     HRESULT WaitForSpecific (
  605.         [out] AsyncIOReq * pReq,    // wait for this request to complete
  606.         [in]  DWORD        dwTimeout
  607.     );
  608.  
  609.     // discard all pending io and place all requests on the 'done' queue
  610.     //
  611.     HRESULT DiscardPending (void);
  612.  
  613.     // wait for all pending io's to be complete
  614.     //
  615.     HRESULT Flush (void);
  616. }
  617.  
  618. typedef IFileAsyncIO * PFILEASYNCIO;
  619.  
  620.  
  621. //
  622. // Intelligent connectivity for filters - an interface supported by
  623. // filter graphs (since it is an extension to IFilterGraph) that supports
  624. // building of graphs by automatic selection and connection of appropriate
  625. // filters
  626.  
  627. [
  628.     object,
  629.     local,
  630.     uuid(56a868a9-0ad4-11ce-b03a-0020af0ba770),
  631.     pointer_default(unique)
  632. ]
  633. interface IGraphBuilder : IFilterGraph {
  634.     // Connect these two pins directly or indirectly, using transform filters
  635.     // if necessary.
  636.  
  637.     HRESULT Connect
  638.         ( [in] IPin * ppinOut,    // the output pin
  639.           [in] IPin * ppinIn      // the input pin
  640.         );
  641.  
  642.  
  643.     // Connect this output pin directly or indirectly, using transform filters
  644.     // if necessary to something that will render it.
  645.  
  646.     HRESULT Render
  647.         ( [in] IPin * ppinOut     // the output pin
  648.         );
  649.  
  650.  
  651.     // Build a filter graph that will render this file using this play list.
  652.     // If lpwstrPlayList is NULL then it will use the default play list
  653.     // which will typically render the whole file.
  654.  
  655.     HRESULT RenderFile
  656.         ( [in] LPCWSTR lpcwstrFile,
  657.           [in] LPCWSTR lpcwstrPlayList
  658.         );
  659.  
  660.  
  661.     // Add to the filter graph a source filter for this file.  This would
  662.     // be the same source filter that would be added by calling Render.
  663.     // This call gives you more control over building
  664.     // the rest of the graph, e.g. AddFilter(<a renderer of your choice>)
  665.     // and then Connect the two.
  666.     // The IFilter* interface exposed by the source filter is returned
  667.     // in ppFilter, addrefed already for you
  668.     // The filter will be known by the name lpcwstrFIlterName
  669.     // nn this filter graph,
  670.     HRESULT AddSourceFilter
  671.         ( [in]      LPCWSTR lpcwstrFileName,
  672.           [in]      LPCWSTR lpcwstrFilterName,
  673.           [out]     IFilter* *ppFilter
  674.         );
  675.  
  676.  
  677.     // If this call is made then trace information will be written to the
  678.     // file showing the actions taken in attempting to perform an operation.
  679.     HRESULT SetLogFile
  680.         ( [in]      HANDLE hFile  // open file handle e.g. from CreateFile
  681.         );
  682.  
  683.  
  684.     // Request that the graph builder should return as soon as possible from
  685.     // its current task.
  686.     // Note that it is possible fot the following to occur in the following
  687.     // sequence:
  688.     //     Operation begins; Abort is requested; Operation completes normally.
  689.     // This would be normal whenever the quickest way to finish an operation
  690.     // was to simply continue to the end.
  691.     HRESULT Abort();
  692.  
  693.     // Return S_OK if the curent operation is to continue,
  694.     // return S_FALSE if the current operation is to be aborted.
  695.     // This method can be called as a callback from a filter which is doing
  696.     // some operation at the request of the graph.
  697.     HRESULT ShouldOperationContinue();
  698.  
  699. }
  700.  
  701.  
  702. //
  703. // StreamBuilder
  704. // aka Graph building with constraints
  705. // aka convergent graphs
  706. // aka Closed captioning
  707.  
  708. [
  709.     object,
  710.     local,
  711.     uuid(56a868bf-0ad4-11ce-b03a-0020af0ba770),
  712.     pointer_default(unique)
  713. ]
  714. interface IStreamBuilder : IUnknown {
  715.  
  716.     // Connect this output pin directly or indirectly, using transform filters
  717.     // if necessary to thing(s) that will render it, within this graph
  718.     // Move from Initial state to Rendered state.
  719.  
  720.     HRESULT Render
  721.         ( [in] IPin * ppinOut,         // the output pin
  722.           [in] IGraphBuilder * pGraph  // the graph
  723.         );
  724.  
  725.     // Undo what you did in Render.  Return to Initial state.
  726.     HRESULT Backout
  727.         ( [in] IPin * ppinOut,         // the output pin
  728.           [in] IGraphBuilder * pGraph  // the graph
  729.         );
  730. }
  731.  
  732.  
  733. // async reader interface - supported by file source filters. Allows
  734. // multiple overlapped reads from different positions
  735.  
  736.  
  737. [
  738.         object,
  739.         uuid(56a868aa-0ad4-11ce-b03a-0020af0ba770),
  740.         pointer_default(unique)
  741. ]
  742. interface IAsyncReader : IUnknown
  743. {
  744.     // pass in your preferred allocator and your preferred properties.
  745.     // method returns the actual allocator to be used. Call GetProperties
  746.     // on returned allocator to learn alignment and prefix etc chosen.
  747.     // this allocator will be not be committed and decommitted by
  748.     // the async reader, only by the consumer.
  749.     // Must call this before calling Request.
  750.     HRESULT RequestAllocator(
  751.                 [in]  IMemAllocator* pPreferred,
  752.                 [in]  ALLOCATOR_PROPERTIES* pProps,
  753.                 [out] IMemAllocator ** ppActual);
  754.  
  755.     // queue a request for data.
  756.     // media sample start and stop times contain the requested absolute
  757.     // byte position (start inclusive, stop exclusive).
  758.     // may fail if sample not obtained from agreed allocator.
  759.     // may fail if start/stop position does not match agreed alignment.
  760.     // samples allocated from source pin's allocator may fail
  761.     // GetPointer until after returning from WaitForNext.
  762.     // Stop position must be aligned - this means it may exceed duration.
  763.     // on completion, stop position will be corrected to unaligned
  764.     // actual data.
  765.     HRESULT Request(
  766.                 [in] IMediaSample* pSample,
  767.                 [in] DWORD dwUser);            // user context
  768.  
  769.     // block until the next sample is completed or the timeout occurs.
  770.     // timeout (millisecs) may be 0 or INFINITE. Samples may not
  771.     // be delivered in order. If there is a read error of any sort, a
  772.     // notification will already have been sent by the source filter,
  773.     // and HRESULT will be an error.
  774.     // If ppSample is not null, then a Request completed with the result
  775.     // code returned.
  776.     HRESULT WaitForNext(
  777.                 [in]  DWORD dwTimeout,
  778.                 [out] IMediaSample** ppSample,  // completed sample
  779.                 [out] DWORD * pdwUser);        // user context
  780.  
  781.     // sync read of data. Sample passed in must have been acquired from
  782.     // the agreed allocator. Start and stop position must be aligned.
  783.     // equivalent to a Request/WaitForNext pair, but may avoid the
  784.     // need for a thread on the source filter.
  785.     HRESULT SyncReadAligned(
  786.                 [in] IMediaSample* pSample);
  787.  
  788.  
  789.     // sync read. works in stopped state as well as run state.
  790.     // need not be aligned. Will fail if read is beyond actual total
  791.     // length.
  792.     HRESULT SyncRead(
  793.                 [in]  LONGLONG llPosition,    // absolute file position
  794.                 [in]  LONG lLength,        // nr bytes required
  795.                 [out, size_is(lLength)]
  796.               BYTE* pBuffer);        // write data here
  797.  
  798.     // return total length of stream, and currently available length.
  799.     // reads for beyond the available length but within the total length will
  800.     // normally succeed but may block for a long period.
  801.     HRESULT Length(
  802.                 [out] LONGLONG* pTotal,
  803.                 [out] LONGLONG* pAvailable);
  804.  
  805.     // cause all outstanding reads to return, possibly with a failure code
  806.     //(VFW_E_TIMEOUT) indicating they were cancelled.
  807.     // Between BeginFlush and EndFlush calls, Request calls will fail and
  808.     // WaitForNext calls will always complete immediately.
  809.     HRESULT BeginFlush(void);
  810.     HRESULT EndFlush(void);
  811. }
  812.  
  813.  
  814. // interface provided by the filtergraph itself to let other objects
  815. // (especially plug-in distributors, but also apps like graphedt) know
  816. // when the graph has changed.
  817. [
  818.     object,
  819.     uuid(56a868ab-0ad4-11ce-b03a-0020af0ba770),
  820.     pointer_default(unique)
  821. ]
  822. interface IGraphVersion : IUnknown
  823. {
  824.     // returns the current graph version number
  825.     // this is incremented every time there is a change in the
  826.     // set of filters in the graph or in their connections
  827.     //
  828.     // if this is changed since your last enumeration, then re-enumerate
  829.     // the graph
  830.     HRESULT QueryVersion(LONG* pVersion);
  831. }
  832.  
  833.  
  834.  
  835.  
  836. //
  837. // interface describing an object that uses resources.
  838. //
  839. // implement if: you request resources using IResourceManager. You will
  840. // need to pass your implementation of this pointer as an in param.
  841. //
  842. // use if: you are a resource manager who implements IResourceManager
  843. [
  844.     object,
  845.     uuid(56a868ad-0ad4-11ce-b03a-0020af0ba770),
  846.     pointer_default(unique)
  847. ]
  848. interface IResourceConsumer : IUnknown
  849. {
  850.     // you may acquire the resource specified.
  851.     // return values:
  852.     //      S_OK    -- I have successfully acquired it
  853.     //      S_FALSE -- I will acquire it and call NotifyAcquire afterwards
  854.     //      VFW_S_NOT_NEEDED: I no longer need the resource
  855.     //      FAILED(hr)-I tried to acquire it and failed.
  856.  
  857.     HRESULT
  858.     AcquireResource(
  859.         [in] LONG idResource);
  860.  
  861.  
  862.  
  863.     // Please release the resource.
  864.     // return values:
  865.     //      S_OK    -- I have released it (and want it again when available)
  866.     //      S_FALSE -- I will call NotifyRelease when I have released it
  867.     //      other   something went wrong.
  868.     HRESULT
  869.     ReleaseResource(
  870.         [in] LONG idResource);
  871. }
  872.  
  873.  
  874.  
  875. // interface describing a resource manager that will resolve contention for
  876. // named resources.
  877. //
  878. // implement if: you are a resource manager. The filtergraph will be a resource
  879. // manager, internally delegating to the system wide resource manager
  880. // (when there is one)
  881. //
  882. // use if: you need resources that are limited. Use the resource manager to
  883. // resolve contention by registering the resource with this interface,
  884. // and requesting it from this interface whenever needed.
  885. //
  886. // or use if: you detect focus changes which should affect resource usage.
  887. // Notifying change of focus to the resource manager will cause the resource
  888. // manager to switch contended resources to the objects that have the user's
  889. // focus
  890. [
  891.     object,
  892.     uuid(56a868ac-0ad4-11ce-b03a-0020af0ba770),
  893.     pointer_default(unique)
  894. ]
  895. interface IResourceManager : IUnknown
  896. {
  897.     // tell the manager how many there are of a resource.
  898.     // ok if already registered. will take new count. if new count
  899.     // is lower, will de-allocate resources to new count.
  900.     //
  901.     // You get back a token that will be used in further calls.
  902.     //
  903.     // Passing a count of 0 will eliminate this resource. There is currently
  904.     // no defined way to find the id without knowing the count.
  905.     //
  906.     HRESULT
  907.     Register(
  908.         [in] LPCWSTR pName,         // this named resource
  909.         [in] LONG   cResource,      // has this many instances
  910.         [out] LONG* plToken         // token placed here on return
  911.         );
  912.  
  913.     HRESULT
  914.     RegisterGroup(
  915.         [in] LPCWSTR pName,         // this named resource group
  916.         [in] LONG cResource,        // has this many resources
  917.         [in, size_is(cResource)]
  918.              LONG* palTokens,      // these are the contained resources
  919.         [out] LONG* plToken        // group resource id put here on return
  920.         );
  921.  
  922.     // request the use of a given, registered resource.
  923.     // possible return values:
  924.     //      S_OK == yes you can use it now
  925.     //      S_FALSE == you will be called back when the resource is available
  926.     //      other - there is an error.
  927.     //
  928.     // The priority of this request should be affected by the associated
  929.     // focus object -- that is, when SetFocus is called for that focus
  930.     // object (or a 'related' object) then my request should be put through.
  931.     //
  932.     // A filter should pass the filter's IUnknown here. The filtergraph
  933.     // will match filters to the filtergraph, and will attempt to trace
  934.     // filters to common source filters when checking focus objects.
  935.     // The Focus object must be valid for the entire lifetime of the request
  936.     // -- until you call CancelRequest or NotifyRelease(id, p, FALSE)
  937.     HRESULT
  938.     RequestResource(
  939.         [in] LONG idResource,
  940.         [in] IUnknown* pFocusObject,
  941.         [in] IResourceConsumer* pConsumer
  942.         );
  943.  
  944.  
  945.     // notify the resource manager that an acquisition attempt completed.
  946.     // Call this method after an AcquireResource method returned
  947.     // S_FALSE to indicate asynchronous acquisition.
  948.     // HR should be S_OK if the resource was successfully acquired, or a
  949.     // failure code if the resource could not be acquired.
  950.     HRESULT
  951.     NotifyAcquire(
  952.         [in] LONG idResource,
  953.         [in] IResourceConsumer* pConsumer,
  954.         [in] HRESULT hr);
  955.  
  956.     // Notify the resource manager that you have released a resource. Call
  957.     // this in response to a ReleaseResource method, or when you have finished
  958.     // with the resource. bStillWant should be TRUE if you still want the
  959.     // resource when it is next available, or FALSE if you no longer want
  960.     // the resource.
  961.     HRESULT
  962.     NotifyRelease(
  963.         [in] LONG idResource,
  964.         [in] IResourceConsumer* pConsumer,
  965.         [in] BOOL bStillWant);
  966.  
  967.     // I don't currently have the resource, and I no longer need it.
  968.     HRESULT
  969.     CancelRequest(
  970.         [in] LONG idResource,
  971.         [in] IResourceConsumer* pConsumer);
  972.  
  973.     // Notify the resource manager that a given object has been given the
  974.     // user's focus. In ActiveMovie, this will normally be a video renderer
  975.     // whose window has received the focus. The filter graph will switch
  976.     // contended resources to (in order):
  977.     //      requests made with this same focus object
  978.     //      requests whose focus object shares a common source with this
  979.     //      requests whose focus object shares a common filter graph
  980.     // After calling this, you *must* call ReleaseFocus before the IUnknown
  981.     // becomes invalid, unless you can guarantee that another SetFocus
  982.     // of a different object is done in the meantime. No addref is held.
  983.     //
  984.     // The resource manager will hold this pointer until replaced or cancelled,
  985.     // and will use it to resolve resource contention. It will call
  986.     // QueryInterface for IFilter at least and if found will call methods on
  987.     // that interface.
  988.     HRESULT
  989.     SetFocus(
  990.         [in] IUnknown* pFocusObject);
  991.  
  992.     // Sets the focus to NULL if the current focus object is still
  993.     // pFocusObject. Call this when
  994.     // the focus object is about to be destroyed to ensure that no-one is
  995.     // still referencing the object.
  996.     HRESULT
  997.     ReleaseFocus(
  998.         [in] IUnknown* pFocusObject);
  999.  
  1000.  
  1001.  
  1002. // !!! still need
  1003. //      -- app override (some form of SetPriority)
  1004. //      -- enumeration and description of resources
  1005.  
  1006. }
  1007.  
  1008.  
  1009. //
  1010. // Interface representing an object that can be notified about state
  1011. // and other changes within a filter graph. The filtergraph will call plug-in
  1012. // distributors that expose this optional interface so that they can
  1013. // respond to appropriate changes.
  1014. //
  1015. // Implement if: you are a plug-in distributor (your class id is found
  1016. // under HKCR\Interface\<IID>\Distributor= for some interface).
  1017. //
  1018. // Use if: you are the filtergraph.
  1019. [
  1020.     object,
  1021.     uuid(56a868af-0ad4-11ce-b03a-0020af0ba770),
  1022.     pointer_default(unique)
  1023. ]
  1024. interface IDistributorNotify : IUnknown
  1025. {
  1026.     // called when graph is entering stop state. Called before
  1027.     // filters are stopped.
  1028.     HRESULT Stop(void);
  1029.  
  1030.     // called when graph is entering paused state, before filters are
  1031.     // notified
  1032.     HRESULT Pause(void);
  1033.  
  1034.     // called when graph is entering running state, before filters are
  1035.     // notified. tStart is the stream-time offset parameter that will be
  1036.     // given to each filter's IFilter::Run method.
  1037.     HRESULT Run(REFERENCE_TIME tStart);
  1038.  
  1039.     // called when the graph's clock is changing, with the new clock. Addref
  1040.     // the clock if you hold it beyond this method. Called before
  1041.     // the filters are notified.
  1042.     HRESULT SetSyncSource(
  1043.         [in] IReferenceClock * pClock);
  1044.  
  1045.     // called when the set of filters or their connections has changed.
  1046.     // Called on every AddFilter, RemoveFilter or ConnectDirect (or anything
  1047.     // that will lead to one of these).
  1048.     // You don't need to rebuild your list of interesting filters at this point
  1049.     // but you should release any refcounts you hold on any filters that
  1050.     // have been removed.
  1051.     HRESULT NotifyGraphChange(void);
  1052. }
  1053.  
  1054.  
  1055.