/*++

    Copyright (c) 2002 Microsoft Corporation

    Module Name:

        sbe.idl

    Abstract:

        This module the StreamBuffer interface definitions & CLSIDs, public

--*/

import "unknwn.idl" ;
import "wtypes.idl" ;
import "objidl.idl";
import "strmif.idl" ;

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

//  interfaces
interface   IStreamBufferSink ;                     //  get recording objects
interface   IStreamBufferSource ;                   //  associates with IStreamBufferSink
interface   IStreamBufferRecordControl ;            //  recording control
interface   IStreamBufferRecordingAttribute ;       //  StreamBuffer attribute creation
interface   IEnumStreamBufferRecordingAttrib ;      //  StreamBuffer attribute enumeration
interface   IStreamBufferConfigure ;                //  configuration interface
interface   IStreamBufferMediaSeeking ;             //  IMediaSeeking but with different GUID
interface   IStreamBufferPolicy ;                   //  StreamBuffer policies
interface   IStreamBufferInitialize ;               //  allows 3rd party app to set HKEY

[
    object,
    uuid(9ce50f2d-6ba7-40fb-a034-50b1a674ec78),
    pointer_default(unique)
]
[local] interface IStreamBufferInitialize : IUnknown
{
    /*++
        ------------------------------------------------------------------------
        SetHKEY ()

        Implemented on StreamBufferStreamSink and StreamBufferSource filters.
        Gives a hosting application the ability to specify HKEY root in
          registry.  This method must called **early**: after the filter is
          instantiated, but before StreamBufferSource is locked (explicitly or
          implicitely) if calling the method on StreamBufferSource, or before
          a source is set (via IStreamBufferSource or IFileSourceFilter) if
          calling the method on StreamBufferStreamSource.  If a call is made
          after either filter has been initialized internally, the call will
          fail with E_UNEXPECTED.  The hosting application is responsible for
          ensuring that the HKEY passed in is writable & readable per the
          logged-on user privileges.  The HKEY is duplicated internally,
          so the caller can close it after making this call.
    --*/
    HRESULT
    SetHKEY (
        [in]    HKEY    hkeyRoot
        ) ;

    /*++
        ------------------------------------------------------------------------
        SetSIDs ()

        Implemented on StreamBufferStreamSink and StreamBufferSource filters.
        Provides a way for the hosting application to specify security-level
          sharing between capture and render processes and contexts.  By
          default security attributes are inherited from the hosting process,
          unless the application overrides the defaults and provides them via
          this method.
    --*/
    HRESULT
    SetSIDs (
        [in]                    DWORD   cSIDs,
        [in, size_is (cSIDs)]   PSID *  ppSID
        ) ;
} ;

/*++
    ============================================================================
    ============================================================================
    IStreamBufferSink

    Stream Source interface;
    implemented on the StreamBufferSink filter;
    Only way to get a recorder object's IUnknown (object will subsequently
        be associated with this Sink)
--*/

enum {
    RECORDING_TYPE_CONTENT = 0,         //  no post-recording or overlapped
    RECORDING_TYPE_REFERENCE,           //  allows post-recording & overlapped
} ;

[
    object,
    uuid(afd1f242-7efd-45ee-ba4e-407a25c9a77a),
    pointer_default(unique)
]
interface IStreamBufferSink : IUnknown
{
    /*++
        ------------------------------------------------------------------------
        LockProfile ()

        1.  Locks the profile;
        2.  No *new* input pin connections will be accepted;
        3.  Existing pins that are, or have ever been, connected can be
            reconnected if the media type is exactly the same as the first
            successful connection;
        4.  Can be called multiple times safely with NULL parameter, but only
            once with non-NULL parameter; returns E_UNEXPECTED if called more
            than once with non-NULL param, or after the hosting filter has run;
        5.  Must be called before the filter that implements this interface is
            ever run; when it is run, it locks implicitely and this method has
            no effect if called with NULL parameters, or fails if called with
            non-NULL parameter for the reasons listed above;
        6.  Errors with VFW_E_UNSUPPORTED_STREAM if there are no streams in the
            profile;

        Parameter Detail
        ----------------

        pszStreamBufferFilename

            Is a NULL-terminated filename string.  If the content written by
            this sink is to be shared cross-process, this parameter specifies a
            filename that will be opened by any reader(s) to read & render the
            content sent into the sink.

            Can be NULL (not specified)

            Must be a full-path filename; if no path is specified, the file is
            created in a "current" directory

            If the file already exists, the call fails

            Is opened with DELETE_ON_CLOSE flag, so is automatically deleted
            when the sink is unlocked, or when the hosting process terminates
    --*/
    HRESULT
    LockProfile (
        [in]    LPCWSTR pszStreamBufferFilename
        ) ;

    /*++
        ------------------------------------------------------------------------
        CreateRecorder ()

        1.  Returns a *new* recorder object's IUnknown;
        2.  Caller can call QueryInterface() on the returned pointer to get
            interface pointers to configure & control the recording;
        3.  Returned IUnknown pointer is ref'd & must be Release()'d by the
            caller
        4.  IStreamBufferSink interface must have been locked (explicitely or
            implicitely) prior to call

        To create an ordinary recording, specify RECORDING_TYPE_CONTENT for the
        dwRecordType parammeter.  This will record the content directly into
        the specified file.  These recording types only accept start and stop
        times that occur in the future.

        A recording of type RECORDING_TYPE_REFERENCE generates a small file
        that references content saved in temporary storage.  Recordings of this
        type can have start and stop times that occurs in the past, and can
        overlap other same-type recordings.

        Reference recording *content* will be saved in the same subdirectory as
        the specified reference file, but with hidden and system attributes.
        The naming convention of the files will append a _1.sbe, _2.sbe, etc...
        to the filename (minus extension) specified in the call e.g. a
        "seinfeld01.sbe" reference file will have saved content in hidden
        and system files "seinfeld01_1.sbe", "seinfeld01_2.sbe", etc...

    --*/
    HRESULT
    CreateRecorder (
        [in]    LPCWSTR     pszFilename,
        [in]    DWORD       dwRecordType,       //  RECORDING_TYPE_CONTENT or RECORDING_TYPE_REFERENCE
        [out]   IUnknown ** pRecordingIUnknown
        ) ;

    /*++
        ------------------------------------------------------------------------
        IsProfileLocked ()

        1.  Returns S_OK if the profile is locked and S_FALSE if it is not.
        2.  Returns E_FAIL on error.
    --*/
    HRESULT
    IsProfileLocked (
        ) ;
} ;

/*++
    ============================================================================
    ============================================================================
    IStreamBufferSource ()

    Stream Source reader interface;
    Implemented on the StreamBufferSource filter;
--*/
[
    object,
    uuid(1c5bd776-6ced-4f44-8164-5eab0e98db12),
    pointer_default(unique)
]
interface IStreamBufferSource : IUnknown
{
    /*++
        ------------------------------------------------------------------------
        SetStreamSink ()

        1.  Sets the StreamBuffer Sink that streams from this Source;
        2.  IStreamBufferSink object must be in the same process as this object;
        3.  Interface is AddRef()'d if the call succeeds;

        Parameter Detail
        ----------------

        pIStreamBufferSink

            Sink that will stream to this Source
    --*/
    HRESULT
    SetStreamSink (
        [in]    IStreamBufferSink *    pIStreamBufferSink
        ) ;
} ;

/*++
    ============================================================================
    ============================================================================
    IStreamBufferRecordControl

    obtained by QIing IStreamBufferSink::CreateRecorder()-returned IUnknown *
--*/
[
    object,
    uuid(ba9b6c99-f3c7-4ff2-92db-cfdd4851bf31),
    pointer_default(unique)
]
interface IStreamBufferRecordControl : IUnknown
{
    /*++
        ------------------------------------------------------------------------
        Start ()

        1.  Starts a recording;
        2.  Will save to the filename that is specified when this interface's
            IUnknown is requested (IStreamBufferSink::CreateRecorder());

        Parameter Detail
        ----------------

        rtStart

            Start time relative to "now;

            If the recording type is a content recording, can only refer to
            seconds in the future; allowed seconds are [0,5]

            If the recording type is a reference recording, can refer to any
            time that still has valid content i.e. content that has not yet
            become stale

            If the recording is a reference recording and (* prtStart) is
            earlier than the earliest still-valid content, the call will reset
            it to the earliest content; the value when the recording was
            actually started will be [out]
    --*/
    HRESULT
    Start (
        [in,out]    REFERENCE_TIME *    prtStart
        ) ;

    /*++
        ------------------------------------------------------------------------
        Stop ()

        1.  Stops a recording;
        2.  Closes out the file;

        Parameter Detail
        ----------------

        rtStart

            Stop time relative to "now;

            If the recording type is a content recording, can only refer to
            seconds in the future; allowed seconds are [0,5]

            If the recording type is a reference recording, can refer to any
            time that still has valid content i.e. content that has not yet
            become stale; stop time cannot be <= start time
    --*/
    HRESULT
    Stop (
        [in]    REFERENCE_TIME  rtStop
        ) ;

    /*++
        ------------------------------------------------------------------------
        GetRecordingStatus ()

        1.  Retrieves the status of the recording

        Parameter Detail
        ----------------

        phResult

            The (current) status of writing or closing the recording file;

            Can be NULL;

        pbStarted

            If supplied, set to a non-zero value if the recording has been
            started

            Can be NULL;