//------------------------------------------------------------------------------
// File: AXCore.idl
//
// Desc: Core streaming interfaces.  Other ActiveMovie-only interfaces
//       are in AXExtend.idl.
//
// Copyright (c) 1992-2002, Microsoft Corporation.  All rights reserved.
//------------------------------------------------------------------------------


// include unknwn.idl and objidl.idl first

#define CHARS_IN_GUID 39  // 128 bits, plus { - } punctuation and terminal null
                          // chars NOT BYTES in the standard representation
                          // e.g. {D3588AB0-0781-11ce-B03A-0020AF0BA770} + null

cpp_quote("#define CHARS_IN_GUID     39")


//=====================================================================
//=====================================================================
// media types & formats
//=====================================================================
//=====================================================================

// There is a high-level media type (audio, compressed video,
// mpeg video, midi). Within each type, there is a subtype (cinepak, pcm)
// and a length+untyped data block defining the format in a
// type-specific manner. EG for video/cinepak, the data block would be
// a bitmapinfo.
// The contents of the format block are defined by the formattype GUID.
// For example, FORMAT_VideoInfo, FORMAT_WaveFormatEx. In the future, this
// may be a pointer to an object supporting property style interfaces
// in which case the GUID may be something like FORMAT_IUnknown. When
// you are passed a media type you should check the format type, if
// it isn't a type you recognize, then don't touch the format block

typedef struct _AMMediaType {
    GUID     majortype;
    GUID     subtype;
    BOOL     bFixedSizeSamples;
    BOOL     bTemporalCompression;
    ULONG    lSampleSize;
    GUID     formattype;
    IUnknown *pUnk;
    ULONG    cbFormat;
    [size_is(cbFormat)] BYTE * pbFormat;
} AM_MEDIA_TYPE;

//=====================================================================
//=====================================================================
// pin information
//=====================================================================
//=====================================================================

// is this an input or output pin
typedef enum _PinDirection {
    PINDIR_INPUT,
    PINDIR_OUTPUT
} PIN_DIRECTION;

// other types that need defining
#define MAX_PIN_NAME     128
cpp_quote("#define MAX_PIN_NAME     128")
cpp_quote("#define MAX_FILTER_NAME  128")
#define MAX_FILTER_NAME  128


//=====================================================================
//=====================================================================
// time information
//
// This represents a time (either reference or stream) in 100ns units.
// The class library contains a CRefTime helper class
// that supports simple comparison and arithmetic operations
//=====================================================================
//=====================================================================

typedef LONGLONG REFERENCE_TIME;
typedef double REFTIME;

// Win32 HANDLEs have to be cast to these as the MIDL compiler doesn't
// like the HANDLE type or in fact anything remotely associated with
// them. If this ever gets ported to a MAC environment then these will
// have to become an alertable synchronisation object that it supports

typedef DWORD_PTR HSEMAPHORE;
typedef DWORD_PTR HEVENT;

//=====================================================================
//=====================================================================
// Allocator properties
//
// Used to describe the actual properties of an allocator,
// and used to request properties from an allocator or from an upstream
// filter that could create an allocator. See IMemAllocator and
// IMemInputPin.
//=====================================================================
//=====================================================================
typedef struct _AllocatorProperties {
        long cBuffers;  // count of buffers at this allocator
        long cbBuffer;  // size of each buffer, excluding any prefix

        // alignment of the buffer - buffer start will be aligned on a multiple of
        // this amount
        long cbAlign;

        // prefix amount. Each buffer is immediately preceeded by cbPrefix bytes.
        // note that GetPointer points to the beginning of the buffer proper.
        // the prefix is aligned, i.e. (GetPointer() - cbPrefix) is aligned on cbAlign.
        long cbPrefix;
} ALLOCATOR_PROPERTIES;





// forward declarations (in alphabetical order - we were getting duplicates)
interface IAMovieSetup;
interface IEnumFilters;
interface IEnumMediaTypes;
interface IEnumPins;
interface IBaseFilter;
interface IFilterGraph;
interface IMediaFilter;
interface IMediaSample;
interface IMemAllocator;
interface IMemAllocatorCallbackTemp;
interface IMemAllocatorNotifyCallbackTemp;
interface IMemInputPin;
interface IPin;
interface IReferenceClock;



//=====================================================================
//=====================================================================
// Defines IPin interface
//
// interface representing a single, unidirection connection point on a
// filter. A Pin will connect to exactly one other pin on another filter.
// This interface represents the interface other objects can call on
// this pin. The interface between the filter and the pin is private to
// the implementation of a specific filter.
//
// During the connection process, one pin will be instructed to take
// the lead: the connect interface on this pin will be calling, passing
// the IPin* for the other pin. This connecting pin will call the
// ReceiveConnection member function on the other pin, as well as presumably
// other format-enumeration and queryinterface calls to establish whether
// the connection is possible.
//=====================================================================
//=====================================================================

[
object,
uuid(56a86891-0ad4-11ce-b03a-0020af0ba770),
pointer_default(unique)
]
interface IPin : IUnknown {

    // initiate a connection to another pin. calls ReceiveConnection on the
    // other pin. Verifies that the connection is possible and may reject
    // it.
    // The mediatype parameter is optional. If it is not null, the pin must
    // connect using that media type if possible. The subtype and/or format
    // type can be GUID_NULL, meaning that the pin can fill them in as desired.
    // This allows an application to partially specify the media type to be
    // used for the connection, insisting on eg YUV 422 but leaving details
    // (such as the image size) to be negotiated between the pins.
    HRESULT Connect(
        [in] IPin * pReceivePin,        // connect yourself to this pin
        [in] const AM_MEDIA_TYPE * pmt  // (optional) connect using this type
    );

    // called by a connecting pin to make a connection
    HRESULT ReceiveConnection(
        [in] IPin * pConnector,
        [in] const AM_MEDIA_TYPE *pmt   // this is the media type we will exchange
    );

    // break a connection - no params since there is only one connection
    // possible on this pin
    HRESULT Disconnect(void);

    // Find the pin this pin is connected to (if any)
    // The pointer returned is AddRef()d
    // Fails if the pin is not connected
    HRESULT ConnectedTo(
        [out] IPin **pPin
    );

    // Return the media type of a connection if the pin is connected
    HRESULT ConnectionMediaType(
        [out] AM_MEDIA_TYPE *pmt
    );

    // get information about the pin itself
    typedef struct _PinInfo {
    IBaseFilter *pFilter;   // the filter this pin is on
    PIN_DIRECTION dir;  // am I an input or output pin?
    WCHAR achName[MAX_PIN_NAME];    // the name of this pin within this filter
    } PIN_INFO;

    HRESULT QueryPinInfo(
        [out] PIN_INFO * pInfo
    );

    // We often want to know the direction.  Rather than use the
    // relatively expensive QueryPinInfo, use this
    HRESULT QueryDirection(
        [out] PIN_DIRECTION *pPinDir
    );

    // Get an identifier for the pin (allows connections to be saved).
    // The storage will be allocated by the filter using CoTaskMemAlloc
    // The caller should free it using CoTaskMemFree
    HRESULT QueryId(
        [out] LPWSTR * Id
    );

    // will the pin accept the format type, S_OK yes, S_FALSE no
    HRESULT QueryAccept(
        [in] const AM_MEDIA_TYPE *pmt
    );

    // return an enumerator for this pin's preferred media types
    HRESULT EnumMediaTypes(
        [out] IEnumMediaTypes **ppEnum
    );

    // return an array of IPin* - the pins that this pin internally connects to
    // All pins put in the array must be AddReffed (but no others)
    // Errors: "Can't say" - FAIL; not enough slots - return S_FALSE
    // Default: return E_NOTIMPL
    // The filter graph will interpret E_NOTIMPL as any input pin connects to
    // all visible output pins and vise versa.
    // apPin can be NULL if nPin==0 (not otherwise).
    HRESULT QueryInternalConnections(
        [out] IPin* *apPin,     // array of IPin*
        [in, out] ULONG *nPin   // on input, the number of slots
                                // on output  the number of pins
    );

    // notify the pin that no more data is expected until a new run
    // command is issued. End of stream should be queued and delivered after
    // all queued data is delivered. Pass through if there is no queued data.
    // Flush should flush any queued EOS.
    // returns S_OK unless there is some error.
    // input pins only: output pins will normally return E_UNEXPECTED.
    HRESULT EndOfStream(void);

    // Flush

    // Enter flush state: do the following steps (in order)
    // -- prevent any more Receives succeeding (set a flushing flag)
    // -- discard any queued data
    // -- free anyone blocked on Receive in your filter
    // -- pass BeginFlush to any downstream pins
    HRESULT BeginFlush(void);

    // End flush state: do the following steps in order
    // -- ensure no more data will be pushed by your filter
    //    (sync with thread if you have one, stop it pushing and
    //     discard any queued data)
    // -- re-enable Receive (clear internal flushing flag)
    // -- pass EndFlush to any downstream pins
    HRESULT EndFlush(void);

    // informational: all data arriving after this call is part of a segment
    // from StartTime to StopTime, played at rate. This allows filters that
    // process buffers containing more than one sample to clip the rendering
    // to within the start and stop times.
    //
    // A source pin will call a destination pin on this method after completing
    // delivery of any previous data, and before any Receive calls for the
    // new data
    HRESULT NewSegment(
                [in] REFERENCE_TIME tStart,
                [in] REFERENCE_TIME tStop,
                [in] double dRate);
}

typedef IPin *PPIN;


//=====================================================================
//=====================================================================
// Defines IEnumPins interface
//
// interface returned from IBaseFilter::EnumPins(). based on IEnumXXXX
//=====================================================================
//=====================================================================

[
object,
uuid(56a86892-0ad4-11ce-b03a-0020af0ba770),
pointer_default(unique)
]
interface IEnumPins : IUnknown {

    HRESULT Next(
        [in] ULONG cPins,                       // place this many pins...
        [out, size_is(cPins)] IPin ** ppPins,   // ...in this array
        [out] ULONG * pcFetched                 // actual count passed
    );

    HRESULT Skip(
        [in] ULONG cPins);

    HRESULT Reset(void);

    HRESULT Clone(
        [out] IEnumPins **ppEnum
    );
}

typedef IEnumPins *PENUMPINS;


//=====================================================================
//=====================================================================