//***************************************************************************** 
// 
// Microsoft Windows Media 
// Copyright (C) Microsoft Corporation. All rights reserved. 
//
// FileName:            streamCache.idl
//
// Abstract:            Cache/Proxy Interface definition
//
//*****************************************************************************

cpp_quote("//*****************************************************************************") 
cpp_quote("//") 
cpp_quote("// Microsoft Windows Media") 
cpp_quote("// Copyright (C) Microsoft Corporation. All rights reserved.") 
cpp_quote("//")
cpp_quote("// Automatically generated by Midl from streamCache.idl" )
cpp_quote("//")
cpp_quote("// DO NOT EDIT THIS FILE.")
cpp_quote("//")
cpp_quote("//*****************************************************************************") 

import "objidl.idl";
import "nsscore.idl";
import "DataContainerVersion.idl";
import "event.idl";
import "WMSProxy.idl";

interface IWMSCacheProxy;
interface IWMSCacheProxyCallback;
interface IWMSCacheProxyServer;
interface IWMSCacheProxyServerCallback;
interface IWMSCacheItemDescriptor;
interface IWMSCacheItemCollection;

cpp_quote( "EXTERN_GUID( IID_IWMSCacheProxy,               0x2E34AB83,0x0D3D,0x11d2,0x9E,0xEE,0x00,0x60,0x97,0xD2,0xD7,0xCF );" )
cpp_quote( "EXTERN_GUID( IID_IWMSCacheProxyCallback,       0x2E34AB84,0x0D3D,0x11d2,0x9E,0xEE,0x00,0x60,0x97,0xD2,0xD7,0xCF );" )
cpp_quote( "EXTERN_GUID( IID_IWMSCacheProxyServer,         0x68F2A550,0xD815,0x11D2,0xBE,0xF6,0x00,0xA0,0xC9,0x5E,0xC3,0x43 );" )
cpp_quote( "EXTERN_GUID( IID_IWMSCacheProxyServerCallback, 0x68F2A551,0xD815,0x11D2,0xBE,0xF6,0x00,0xA0,0xC9,0x5E,0xC3,0x43 );" )
cpp_quote( "EXTERN_GUID( IID_IWMSCacheItemDescriptor,      0xC3CBA330,0xAC05,0x11D2,0xBE,0xF0,0x00,0xA0,0xC9,0x5E,0xC3,0x43 );" )
cpp_quote( "EXTERN_GUID( IID_IWMSCacheItemCollection,      0xE6E05D80,0xF45C,0x11D2,0xBE,0xFE,0x00,0xA0,0xC9,0x5E,0xC3,0x43 );" )

///////////////////////////////////////////////////////////////////////////////
typedef [public] enum WMS_CACHE_QUERY_MISS_RESPONSE
{
    WMS_CACHE_QUERY_MISS_SKIP,
    WMS_CACHE_QUERY_MISS_DISCONNECT,
    WMS_CACHE_QUERY_MISS_REDIRECT,
    WMS_CACHE_QUERY_MISS_REDIRECT_TO_PROXY,
    WMS_CACHE_QUERY_MISS_PLAY_BROADCAST,
    WMS_CACHE_QUERY_MISS_PLAY_ON_DEMAND,
    WMS_CACHE_QUERY_MISS_FORWARD_REQUEST,
    WMS_CACHE_QUERY_MISS_PROCESS_REQUEST
} WMS_CACHE_QUERY_MISS_RESPONSE;


///////////////////////////////////////////////////////////////////////////////
typedef [public] enum WMS_CACHE_QUERY_RESPONSE
{
    WMS_CACHE_QUERY_HIT_PLAY_ON_DEMAND,
    WMS_CACHE_QUERY_HIT_PLAY_BROADCAST,
    WMS_CACHE_QUERY_HIT_PROCESS_REQUEST,
    WMS_CACHE_QUERY_MISS
} WMS_CACHE_QUERY_RESPONSE;

///////////////////////////////////////////////////////////////////////////////
typedef [public] enum WMS_CACHE_VERSION_COMPARE_RESPONSE
{    
    WMS_CACHE_VERSION_FAIL_TO_CHECK_VERSION,
    WMS_CACHE_VERSION_CACHE_STALE,
    WMS_CACHE_VERSION_CACHE_UP_TO_DATE,
} WMS_CACHE_VERSION_COMPARE_RESPONSE;

///////////////////////////////////////////////////////////////////////////////
typedef [public] enum WMS_CACHE_CONTENT_TYPE_FLAGS
{
    WMS_CACHE_CONTENT_TYPE_BROADCAST           = 0x1,   // else on-demand
    WMS_CACHE_CONTENT_TYPE_PLAYLIST            = 0x2
} WMS_CACHE_CONTENT_TYPE_FLAGS;


///////////////////////////////////////////////////////////////////////////////
typedef [public] enum WMS_CACHE_QUERY_TYPE_FLAGS
{
    WMS_CACHE_QUERY_OPEN                       = 0x1,
    WMS_CACHE_QUERY_GET_CONTENT_INFO           = 0x2,
    WMS_CACHE_QUERY_CACHE_EVENT                = 0x4,
    WMS_CACHE_QUERY_REVERSE_PROXY              = 0x8,
    WMS_CACHE_QUERY_LOCAL_EVENT                = 0x10
} WMS_CACHE_QUERY_TYPE_FLAGS;


///////////////////////////////////////////////////////////////////////////////
typedef [public] enum WMS_CACHE_CONTENT_DOWNLOAD_FLAGS
{
    WMS_CONTENT_DOWNLOAD_ABORT_IF_BCAST        = 0x1
} WMS_CACHE_CONTENT_DOWNLOAD_FLAGS;

///////////////////////////////////////////////////////////////////////////////
typedef [public] enum WMS_CACHE_REMOTE_EVENT_FLAGS
{
    WMS_CACHE_REMOTE_OPEN                      = 0x1,
    WMS_CACHE_REMOTE_CLOSE                     = 0x2,
    WMS_CACHE_REMOTE_LOG                       = 0x4
} WMS_CACHE_REMOTE_EVENT_FLAGS;



#if (__midl >= 501)
midl_pragma warning( disable: 2279 )
#endif


//////////////////////////////////////////////////////////////////////////////
//
// This is built by a cache plugin.
// It is called by the server's cache manager.
//
//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(2E34AB83-0D3D-11d2-9EEE-006097D2D7CF),
    version(9.0),
    helpstring("Contains methods that administer a cache. This interface is implemented by a cache / proxy plug-in and called by the server.")
]
interface IWMSCacheProxy : IUnknown
{
    [helpstring("Called by the server to direct the plug-in to search the cache for specific content.")] HRESULT 
    QueryCache(
                [in] BSTR bstrOriginUrl,
                [in] IWMSContext *pUserContext,
                [in] IWMSCommandContext *pCommandContext,
                [in] IWMSContext *pPresentationContext,
                [in] long lQueryType, 
                [in] IWMSCacheProxyCallback *pCallback,
                [in] VARIANT varContext
                );

    [helpstring("Called by the server to direct the plug-in to specify its cache-miss policy.")] HRESULT 
    QueryCacheMissPolicy(
                [in] BSTR bstrOriginUrl,
                [in] IWMSContext *pUserContext,
                [in] IWMSCommandContext *pCommandContext,
                [in] IWMSContext *pPresentationContext,
                [in] IUnknown *pCachePluginContext,
                [in] long lQueryType, 
                [in] IWMSCacheProxyCallback *pCallback,
                [in] VARIANT varContext
                );

    //////////////////////////////////////////////////////////
    [helpstring("Called by the server to remove a specific cache item.")] HRESULT 
    RemoveCacheItem( 
                [in] BSTR bstrOriginUrl,
                [in] IWMSCacheProxyCallback *pCallback,
                [in] VARIANT varContext
                );

    [helpstring("Called by the server to remove all content from the cache.")] HRESULT 
    RemoveAllCacheItems(
                [in] IWMSCacheProxyCallback *pCallback,
                [in] VARIANT varContext
                );

    [helpstring("Adds content to the cache.")] HRESULT 
    AddCacheItem(
                [in] BSTR bstrOriginUrl,
                [in] BSTR bstrPrestuffUrl,
                [in] long lExpiration,
                [in] long lBandwidth,
                [in] long lRemoteEventFlags,
                [in] IWMSCacheProxyCallback *pCallback,
                [in] VARIANT varContext
                );
    
    // not used by the cache manager, just used for object model
    [helpstring("Called by the server to retrieve a Boolean value indicating whether the cache has adequate storage for a specific content item.")] HRESULT 
    QuerySpaceForCacheItem(
                [in]  long lContentSizeLow,
                [in]  long lContentSizeHigh, 
                [out] VARIANT_BOOL *pvarfSpaceAvail
                );

    [helpstring("Called by the server to retrieve information about a specific cache item.")] HRESULT 
    FindCacheItem(
                [in]  BSTR bstrOriginUrl,
                [out] IWMSCacheItemDescriptor **ppCacheItemDescriptor
                );

    [helpstring("Called by the server to create an IWMSCacheItemCollection object and retrieve a pointer to it.")] HRESULT 
    CreateCacheItemCollection(
                [out] IWMSCacheItemCollection **ppCacheItemCollection
                );


    //////////////////////////////////////////////////////////
    [helpstring("Called by the server when a particular piece of content is finished being streamed from the cache.")] HRESULT 
    OnCacheClientClose(
                [in] HRESULT resultHr,
                [in] IWMSContext *pUserContext,
                [in] IWMSContext *pPresentationContext
                );
};

#if (__midl >= 501)
midl_pragma warning( default: 2279 )
#endif



//////////////////////////////////////////////////////////////////////////////
//
// This is built by the server's cache manager. 
// It is called by a cache plugin.
//
//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(2E34AB84-0D3D-11d2-9EEE-006097D2D7CF),
    version(9.0),
    helpstring("Contains methods that enable a cache / proxy plug-in to respond to calls that the server makes through the IWMSCacheProxy interface. This interface is implemented by the server and called by a cache / proxy plug-in.")
]
interface IWMSCacheProxyCallback : IUnknown
{
    [helpstring("Called by the plug-in to respond when the server calls IWMSCacheProxy::QueryCache.")] HRESULT 
    OnQueryCache(
                [in] long lHr,  // HRESULT
                [in] WMS_CACHE_QUERY_RESPONSE Response,
                [in] BSTR bstrCacheUrl,
                [in] IWMSContext *pContentInfo,
                [in] IUnknown *pCachePluginContext,
                [in] VARIANT varContext
                );

    [helpstring("Called by the plug-in to respond when the server calls IWMSCacheProxy::QueryCacheMissPolicy.")] HRESULT 
    OnQueryCacheMissPolicy(
                [in] long lHr, // HRESULT
                [in] WMS_CACHE_QUERY_MISS_RESPONSE CacheMissPolicy,
                [in] BSTR bstrUrl,
                [in] IWMSProxyContext * pProxyContext,
                [in] IWMSContext *pContentInfo,
                [in] VARIANT varContext
                );

    //////////////////////////////////////////////////////////

    [helpstring("Called by the plug-in to respond when the server calls IWMSCacheProxy::RemoveCacheItem.")] HRESULT 
    OnRemoveCacheItem(
                [in] long lHr, // HRESULT
                [in] VARIANT varContext
                );

    [helpstring("Called by the plug-in to respond when the server calls IWMSCacheProxy::RemoveAllCacheItems.")] HRESULT 
    OnRemoveAllCacheItems(
                [in] long lHr, // HRESULT
                [in] VARIANT varContext
                );

    [helpstring("Called by the plug-in to respond when the server calls IWMSCacheProxy::AddCacheItem.")] HRESULT 
    OnAddCacheItem(
                [in] long lHr, // HRESULT
                [in] IWMSCacheItemDescriptor *pCacheItemDescriptor,
                [in] VARIANT varServerContext
                );
};



//////////////////////////////////////////////////////////////////////////////
//
// This is built by the server's cache manage.
// It is called by a cache plugin.
//
//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(68F2A550-D815-11D2-BEF6-00A0C95EC343),
    version(9.0),
    helpstring("Contains methods that validate client authorization, retrieve information about cached content, determine whether the content is current, and download content to a cache. This interface is implemented by the server and called by a cache / proxy plug-in.")
]
interface IWMSCacheProxyServer : IUnknown
{
    [helpstring("Called by the plug-in to retrieve content information.")] HRESULT 
    GetContentInformation(
                [in] BSTR bstrOriginUrl,
                [in] IWMSContext *pPresentationContext,
                [in] IWMSCacheProxy *pICacheProxy,
                [in, optional] IWMSProxyContext *pIProxyContext,
                [in, optional] IWMSCacheProxyServerCallback *pCallback,
                [in, optional] VARIANT varContext
                );

    [helpstring("Called by the plug-in to determine whether content is up to date.")] HRESULT 
    CompareContentInformation(
                [in] BSTR bstrOriginUrl,
                [in] IWMSContext *pContentInfo,
                [in] IWMSContext *pPresentationContext,
                [in] IWMSCacheProxy *pICacheProxy,
                [in, optional] IWMSProxyContext *pIProxyContext,
                [in, optional] IWMSCacheProxyServerCallback *pCallback,
                [in, optional] VARIANT varContext
                );

    [helpstring("Called by the plug-in to download content to a cache.")] HRESULT 
    DownloadContent(
                [in] BSTR bstrOriginUrl,
                [in] BSTR bstrCacheUrl,
                [in] long lBandwidth,
                [in] long lQuotaLow,
                [in] long lQuotaHigh,
                [in] long lBitFlags,
                [in] IWMSCacheProxy *pICacheProxy,
                [in, optional] IWMSProxyContext *pIProxyContext,
                [in, optional] IWMSCacheProxyServerCallback *pCallback,
                [in, optional] VARIANT varContext
                );

    [helpstring("Called by the plug-in to stop the download process.")] HRESULT 
    CancelDownloadContent(
                [in] IWMSContext *pArchiveContext,
                [in, optional] IWMSCacheProxyServerCallback *pCallback,
                [in, optional] VARIANT varContext
                );
};



//////////////////////////////////////////////////////////////////////////////
//
// This is built by the cache plugin.
// It is called by the server's cache manager.
//
//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(68F2A551-D815-11D2-BEF6-00A0C95EC343),
    version(9.0),
    helpstring("Contains methods that enable a cache / proxy plug-in to respond to calls that the server makes through the IWMSCacheProxyServer interface. This interface is implemented by a cache / proxy plug-in and called by the server.")
]
interface IWMSCacheProxyServerCallback : IUnknown
{
    [helpstring("Called by the server to respond when the plug-in calls IWMSCacheProxyServer::GetContentInformation.")] HRESULT 
    OnGetContentInformation(
                [in] long lHr, // HRESULT
                [in] IWMSContext *pContentInfo,
                [in] VARIANT varContext
                );
    
    [helpstring("Called by the server to respond when the plug-in calls IWMSCacheProxyServer::CompareContentInformation.")] HRESULT 
    OnCompareContentInformation(
                [in] long lHr, // HRESULT
                [in] WMS_CACHE_VERSION_COMPARE_RESPONSE CompareResponse,
                [in] IWMSContext *pNewContentInfo,
                [in] VARIANT varContext
                );

    [helpstring("Called by the server to provide progress when the plug-in calls IWMSCacheProxyServer::DownloadContent.")] HRESULT 
    OnDownloadContentProgress(
                [in] long lHr, // HRESULT
                [in] WMS_RECORD_PROGRESS_OPCODE opCode,
                [in] IWMSContext *pArchiveContext,
                [in] VARIANT varContext
                );

    [helpstring("Called by the server when media items have finished downloading to the cache.")] HRESULT 
    OnDownloadContentFinished(
                [in] long lHr, // HRESULT
                [in] SAFEARRAY(VARIANT) psaArchiveContexts,
                [in] VARIANT varContext
                );

    [helpstring("Called by the server to respond when the plug-in calls IWMSCacheProxyServer::CancelDownloadContent.")] HRESULT 
    OnCancelDownloadContent(
                [in] long lHr, // HRESULT
                [in] VARIANT varContext
                );
};



//////////////////////////////////////////////////////////////////////////////
//
// This is built by the cache plugin. 
// It is used by the ObjectModel (& Admin) to get information about
// what is currently cached.
//
//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(C3CBA330-AC05-11D2-BEF0-00A0C95EC343),
    version(9.0),
    helpstring("Retrieves the size, version number, expiration date, and URL of cached content. This interface is implemented by a cache / proxy plug-in and called by the server.")
]
interface IWMSCacheItemDescriptor : IUnknown
{
    [helpstring("Retrieves the URL on the origin server from which the cached content was obtained.")] HRESULT 
    GetOriginUrl( [out] BSTR *pbstrOriginUrl );
    [helpstring("Retrieves the URL identifying the location of the cached content on the server.")] HRESULT 
    GetCacheUrl( [out] BSTR *pbstrCacheUrl );
    [helpstring("Retrieves information about the cached content.")] HRESULT 
    GetContentInformation( [out] IWMSContext **ppContentInfo );
    [helpstring("Retrieves the size of the content, in bytes.")] HRESULT 
    GetContentSize( [out] long *plContentSizeLow, [out] long *plContentSizeHigh );
};



//////////////////////////////////////////////////////////////////////////////
//
// This is built by a plugin.
// It is used by the ObjectModel (& Admin) to get information about
// what is currently being cached.
//
// It is the plugins choice wrt how to implement the cache item collection
// In order to give the cache flexibility, it is possible that we could have 
// items disappear in this enumeration, i.e. GetItem will return NULL, or
// have the count grow .... 
//
//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(E6E05D80-F45C-11D2-BEFE-00A0C95EC343),
    version(9.0),
    helpstring("Contains a collection of IWMSCacheItemDescriptor objects. This interface is implemented by a cache / proxy plug-in and called by the server.")
]
interface IWMSCacheItemCollection : IUnknown
{
    [helpstring("Retrieves the number of items in the collection.")] HRESULT 
    GetCount( [out] long* plNumCacheItemDescriptors );
    [helpstring("Retrieves a specific item from the collection.")] HRESULT 
    GetItem( [in] long lIndex, [out] IWMSCacheItemDescriptor **ppCacheItemDescriptor );
};