windows-server-2003/public/sdk/inc/wmspacket.idl

//***************************************************************************** 
// 
// Microsoft Windows Media 
// Copyright (C) Microsoft Corporation. All rights reserved. 
//
// FileName:            wmspacket.idl
//
// Abstract:
//
//*****************************************************************************

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 wmspacket.idl" )
cpp_quote("//")
cpp_quote("// DO NOT EDIT THIS FILE.")
cpp_quote("//")
cpp_quote("//*****************************************************************************") 

cpp_quote("#if _MSC_VER > 1000")
cpp_quote("#pragma once")
cpp_quote("#endif // _MSC_VER > 1000")

import "objidl.idl";

import "WMSBuffer.idl";
import "WMSContext.idl";

cpp_quote( "EXTERN_GUID( IID_IWMSPacket, 0x3309C901,0x10A4,0x11d2,0x9E,0xEE,0x00,0x60,0x97,0xD2,0xD7,0xCF );" )
cpp_quote( "EXTERN_GUID( IID_IWMSPacketList, 0x3309C902,0x10A4,0x11d2,0x9E,0xEE,0x00,0x60,0x97,0xD2,0xD7,0xCF );" )
cpp_quote( "EXTERN_GUID( IID_IWMSPacketParser, 0x8b59f7e1, 0x5411, 0x11d2, 0x9e, 0xff, 0x0, 0x60, 0x97, 0xd2, 0xd7, 0xcf );" )
cpp_quote( "EXTERN_GUID( IID_IWMSPacketListCallback, 0x49c2a6f1, 0x64b8, 0x11d2, 0x9f, 0xe, 0x0, 0x60, 0x97, 0xd2, 0xd7, 0xcf );" )
cpp_quote( "EXTERN_GUID( IID_IWMSStreamSignalHandler, 0x7B10F261,0x26AA,0x11d2,0x9E,0xF2,0x00,0x60,0x97,0xD2,0xD7,0xCF );" )


// These are the defined packet attributes.
// WMSPACKETDESC structure is using the fact that first N fields have exact order.
// DO NOT MODIFY ORDER ON ENUM WITHOUT UPDATING WMSPACKETDESC 
typedef [public] enum WMS_PACKET_ATTRIBUTES
{
    WMS_PACKET_PACKET_NUM = 0,
    WMS_PACKET_NUM_BUFFERS,
    WMS_PACKET_LENGTH,
    WMS_PACKET_SEND_TIME_HI,
    WMS_PACKET_SEND_TIME,
    WMS_PACKET_STREAM_NUM,
    WMS_PACKET_FLAGS,
    WMS_PACKET_NET_SEQUENCE_NUMBER,
    WMS_PACKET_PRESENT_TIME_HI,
    WMS_PACKET_PRESENT_TIME,
    WMS_PACKET_RECV_TIME,
    WMS_PACKET_NUM_NACKS,
    WMS_PACKET_DURATION,
    WMS_PACKET_ERASURES_DETECTED,
    WMS_PACKET_SEND_TIME_ADJUSTMENT,
    WMS_PACKET_PACKETIZED_HDRLEN,
    [hidden] WMS_LAST_PACKET_ATTRIBUTE  = WMS_PACKET_PACKETIZED_HDRLEN,
} WMS_PACKET_ATTRIBUTES;


// These are the packet flags.
typedef [public] enum WMS_PACKET_FLAG_TYPES
{
    WMS_KEY_FRAME_PACKET                    = 0x0001,               // used by server, intrinsic media packet property
    WMS_RETRANSMITTED_PACKET                = 0x0002,               // used by network receiver and netsource
    WMS_PACKET_REPORTED                     = 0x0004,               // used by netsource
    WMS_PACKET_PACKETIZED                   = 0x0008,               // used by network sender
    WMS_RECOVERED_PACKET                    = 0x0010,               // used by fec protocol parser and netsource
    WMS_FEC_PACKET                          = 0x0020,               // used by networksender 
    WMS_FEC_ENCODED_PACKET                  = 0x0040,               // used by network sender and makes sense only if it is a fecpacket
    WMS_PACKET_BURST_FLAG                   = 0x0080,               // used by network sender and control protocol packetizer
    WMS_PACKET_FIRST_PAYLOAD_FLAG           = 0x0100,	            // used by server, intrinsic media packet property
} WMS_PACKET_FLAG_TYPES;


// These are the defined packet list attributes.
typedef [public] enum WMS_PACKET_LIST_ATTRIBUTES
{
    WMS_PACKET_LIST_FLAGS                   = 0,
    WMS_STREAM_SIGNAL                       = 1,
    WMS_PACKET_LIST_GENID                   = 2,
    WMS_PACKET_LIST_SEND_TIME               = 3,
    WMS_PACKET_LIST_SEND_TIME_HI            = 4,
    WMS_PACKET_LIST_PLAYLIST_GEN_ID         = 5,
    [hidden] WMS_LAST_PACKET_LIST_ATTRIBUTE = WMS_PACKET_LIST_PLAYLIST_GEN_ID
} WMS_PACKET_LIST_ATTRIBUTES;


// These are the packet list flags.
typedef [public] enum WMS_PACKET_LIST_FLAG_TYPES
{
    WMS_PACKET_LIST_NEEDS_FIXUP                 = 0x0001,
    WMS_PACKET_LIST_UDP_RESEND                  = 0x0002,
    WMS_PACKET_LIST_PRESTUFF                    = 0x0004,
    WMS_PACKET_LIST_PLAYLIST_CHANGE_RECEDING    = 0x0008,
} WMS_PACKET_LIST_FLAG_TYPES;

typedef [public] enum WMS_PACKET_LIST_EX_FLAGS
{
    WMS_NO_ADDREF                   = 0x80000000,
    WMS_PACKET_NO_ADDREF            = 0x80000000,
    WMS_PACKET_NO_RELEASE           = 0x40000000,
    WMS_PLIST_BUFFER_NO_ADDREF      = 0x80000000,
    WMS_PLIST_BUFFER_NO_RELEASE     = 0x40000000,
    WMS_PLIST_NO_ADDREF             = 0x80000000,
} WMS_PACKET_LIST_EX_FLAGS;

typedef [public] enum WMS_PACKET_BUFFER_FLAGS
{
    WMS_INSERT_BUFFER_AT_END    = 0xFFFFFFFF
} WMS_PACKET_BUFFER_FLAGS;

typedef [public] enum WMS_PACKET_BUFFER_EX_FLAGS
{
    WMS_BUFFER_NO_ADDREF        = 0x80000000,
    WMS_BUFFER_NO_RELEASE       = 0x40000000,
    WMS_BUFFER_NO_REFCOUNT      = 0x20000000,
    WMS_BUFFER_COMBINE = 0x10000000,
} WMS_PACKET_BUFFER_EX_FLAGS;

typedef [public] enum WMS_PACKET_STATUS_FLAGS
{
    WMS_START_NEXT_READ         = 0x0001,
    WMS_WRITE_COMPLETED         = 0x0002,
    WMS_REQUEST_BUFFER          = 0x0004,
    WMS_HEADER_BUFFER           = 0x0008,
} WMS_PACKET_STATUS_FLAGS;

typedef [public] enum WMS_PARSER_FLAG_TYPES
{
    WMS_PARSER_PRESERVE_PADDING  = 0x0001,
} WMS_PARSER_FLAG_TYPES;

typedef unsigned __int64    QWORD;

interface IWMSPacketParser;
interface IWMSPacketList;
interface IWMSPacketListCallback;



//////////////////////////////////////////////////////////////////////////////
//
//                              PACKETS
//
//////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(3309C901-10A4-11d2-9EEE-006097D2D7CF),
    version(9.0),
    helpstring("Contains methods for managing the buffers, attributes, and headers associated with a packet.")
]
interface IWMSPacket : IUnknown
{
    typedef struct 
    {
        INSSBuffer * pBuffer;
        DWORD dwBufferOffset;
        DWORD dwBufferLen;
        WORD wFlags;
    } WMSBUFFERDESC;

    // Every packet can be a scatter/gather list. Packets
    // are variable size, but the raw IO reads fixed sized
    // buffers. Note, the buffer pointer is not marshalled,
    // so this won't work over dcom.

	[helpstring("Retrieves an array of WMSBUFFERDESC structures. Each WMSBUFFERDESC structure contains the location and size of a specific buffer region that contains the packet's data.")] HRESULT 
    GetAllBuffers(
                [in] DWORD dwMaxNumBuffers, 
                [out] WMSBUFFERDESC *pDesc,
                [out] DWORD *pdwNumBuffers,
                [in] DWORD dwExFlags
                );  
    [helpstring("Retrieves the location of a specific buffer region that contains the packet's data.")] HRESULT 
    GetBuffer(
                [in] DWORD dwBufferNum, 
                [out] INSSBuffer **ppBuffer,
                [out] DWORD *pdwBufferOffset,
                [out] DWORD *pdwBufferLen,
                [out] WORD *pwFlags,
                [in, defaultvalue(0)] DWORD dwExFlags
                );
    [helpstring("Adds a new region in a buffer to the collection of buffer regions associated with the packet.")] HRESULT             
    InsertBuffer( 
                [in] DWORD dwBufferNum, // -1 means at the end
                [in] INSSBuffer *pBuffer,
                [in] DWORD dwBufferOffset,
                [in] DWORD dwBufferLen,
                [in] WORD wFlags,
                [in, defaultvalue(0)] DWORD dwExFlags
                );
    [helpstring("Removes the specified region in a buffer from the collection of buffer regions associated with the packet.")] HRESULT 
    RemoveBuffer( [in] DWORD dwBufferNum);
    [helpstring("Removes all of the buffer regions associated with the packet.")] HRESULT 
    RemoveAllBuffers();

    // Packet attributes. Different parts of the server may read
    // and write these attributes.
    [helpstring("Retrieves the value for a packet attribute defined by WMS_PACKET_ATTRIBUTES.")] HRESULT 
    GetAttribute( [in] DWORD dwValueName, [out] DWORD *pdwValue );
    [helpstring("Specifies the value for a packet attribute defined by WMS_PACKET_ATTRIBUTES.")] HRESULT 
    SetAttribute( [in] DWORD dwValueName, [in] DWORD dwValue );

	[helpstring("Retrieves the value for an extended packet attribute defined by a plug-in.")] HRESULT 
    GetExtendedAttribute( 
                [in] DWORD dwValueName, 
                [out] VARIANT *pVariantValue );

    [helpstring("Retrieves the name and value for an extended packet attribute defined by a plug-in.")] HRESULT             
    GetExtendedAttributeByIndex( 
                [in] DWORD dwIndex, 
                [out] DWORD * pdwValueName,
                [out] VARIANT *pVariantValue );

    [helpstring("Specifies the name and value for an extended packet attribute defined by a plug-in.")] HRESULT             
    SetExtendedAttribute( 
                [in] DWORD dwValueName, 
                [in] VARIANT VariantValue );
                
    [helpstring("Retrieves the number of extended packet attributes.")] HRESULT             
    GetExtendedAttributeCount( 
                [out] DWORD * pdwAttrs );

	[helpstring("Copies the specified attributes to another packet.")] HRESULT 
    CopyAttributes( 
                [in] IWMSPacket * pDest, 
                [in, defaultvalue(NULL)] DWORD * pdwAttrNames, 
                [in, defaultvalue(0)] DWORD dwNumAttr,
                [in, defaultvalue(FALSE)] BOOL fCopyExtAttr );

    // Packet header manipulation. Appends header to first buffer in packet or creates new buffer and writes header to it 
    [helpstring("Appends header data to the first buffer region associated with the packet or to a new buffer.")] HRESULT 
    AppendHeader( 
                [in] IWMSBufferAllocator * pAlloc, 
                [in] DWORD dwHeaderLen, 
                [in] BYTE * pbHeader );

    // Packet header manipulation. Copies data to specific location within packet header
    [helpstring("Copies data to specific location within packet header.")] HRESULT 
    SetInHeader(
                [in] DWORD cbOffset,
                [in] BYTE * pbData,
                [in] DWORD cbData );
};




//////////////////////////////////////////////////////////////////////////////
//
//                              PACKET LISTS
//
// Each packet lists contains data from exactly one buffer.
//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(49C2A6F1-64B8-11d2-9F0E-006097D2D7CF),
    version(9.0),
    helpstring("Contains a method to respond to the IWMSPacketList::ReportStatus method call.")
]
interface IWMSPacketListCallback : IUnknown
{
	[helpstring("Specifies the results of the the IWMSPacketList::ReportStatus method call.")] HRESULT 
    OnReportPacketListStatus( [in] IWMSPacketList *pBuffer,
                                      [in] DWORD dwStatus );
};




//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(3309C902-10A4-11d2-9EEE-006097D2D7CF),
    version(9.0),
    helpstring("Contains methods for managing the packets, attributes, and buffers associated with a packet list.")
]
interface IWMSPacketList : IWMSBufferAllocator
{
    typedef struct 
    {
        IWMSPacket * pPacket;
        struct {
            DWORD dwPacketNum; // WMS_PACKET_PACKET_NUM = 0,
            DWORD dwPacketNumBuffers; //WMS_PACKET_NUM_BUFFERS,
            DWORD dwPacketLength; //WMS_PACKET_LENGTH,
            DWORD dwPacketSendTimeHi; //WMS_PACKET_SEND_TIME_HI,
            DWORD dwPacketSendTime; //WMS_PACKET_SEND_TIME,
            DWORD dwPacketStreamNum;//WMS_PACKET_STREAM_NUM,
            DWORD dwPacketFlags; //WMS_PACKET_FLAGS,
            DWORD dwPacketNetSequenceNum;//WMS_PACKET_NET_SEQUENCE_NUMBER,
        } Attrs;
    } WMSPACKETDESC;
    [helpstring("Retrieves the number of packets in the packet list.")] HRESULT 
    GetPacketCount( 
                [out] DWORD *pdwNumPackets );
                
    [helpstring("Retrieves a specific packet.")] HRESULT 
    GetPacket( 
                [in] DWORD dwPacketNum, 
                [out] IWMSPacket **ppPacket,
                [in, defaultvalue(0)] DWORD dwExFlags );

	[helpstring("Retrieves either an array of WMSPACKETDESC structures or an array of packets in the packet list.")] HRESULT 
    GetAllPackets( 
                [in] DWORD dwFirstPacket, 
                [in] DWORD dwMaxNumPackets, 
                [out] WMSPACKETDESC * pPacketDesc,
                [out] IWMSPacket ** ppPacket, 
                [out] DWORD * pdwDescNum, 
                [in] DWORD dwExFlags );

    [helpstring("Adds a packet to the packet list at the specified location.")] HRESULT 
    InsertPacket(
                [in] DWORD dwPacketNum, 
                [in] IWMSPacket *pPacket,
                [in, defaultvalue(0)] DWORD dwExFlags );
                
    [helpstring("Adds a packet to the end of the packet list.")] HRESULT             
    AppendPacket( 
                [in] IWMSPacket *pPacket, 
                [in, defaultvalue(0)] DWORD dwExFlags );

    [helpstring("Removes the specified packet from the packet list.")] HRESULT 
    RemovePacket( 
                [in] DWORD dwPacketNum );

	[helpstring("Removes all of the packets from the packet list.")] HRESULT 
    RemoveAllPackets(
                [in, defaultvalue(0)] DWORD dwExFlags );

    // Packet list attributes. Different parts of the server may read
    // and write these attributes.
    [helpstring("Retrieves the value for a packet list attribute defined by WMS_PACKET_LIST_ATTRIBUTES.")] HRESULT 
    GetAttribute( [in] DWORD dwValueName, [in] DWORD *pdwValue );
    [helpstring("Specifies the value for a packet list attribute defined by WMS_PACKET_LIST_ATTRIBUTES.")] HRESULT 
    SetAttribute( [in] DWORD dwValueName, [in] DWORD dwValue );

	[helpstring("Retrieves the stream signal defined by WMS_STREAM_SIGNAL_TYPE.")] HRESULT 
    GetStreamSignalParam( [out] VARIANT *pParameter );
    [helpstring("Specifies the stream signal defined by WMS_STREAM_SIGNAL_TYPE.")] HRESULT 
    SetStreamSignalParam( [in] VARIANT *pParameter );

    [helpstring("Retrieves the packet parser object that created the packet list.")] HRESULT 
    GetPacketParser( 
                [out] IWMSPacketParser **ppSource,
                [in, defaultvalue(0)] DWORD dwExFlags );

    [helpstring("Specifies the packet parser object that created the packet list.")] HRESULT             
    SetPacketParser( 
                [in] IWMSPacketParser *pSource );

	[helpstring("Retrieves the buffer associated with this packet list.")] HRESULT 
    GetBuffer( 
                [out] INSSBuffer **ppBuffer,
                [in, defaultvalue(0)] DWORD dwExFlags );

    [helpstring("Specifies the buffer associated with this packet list.")] HRESULT             
    SetBuffer( 
                [in] INSSBuffer *pBuffer );

	[helpstring("Specifies the callback object that is used to respond to the ReportStatus method call.")] HRESULT 
    SetCompletionCallback( [in] IWMSPacketListCallback *pCallback );
    [helpstring("Retrieves the callback object that is used to respond to the ReportStatus method call.")] HRESULT 
    GetCompletionCallback( [out] IWMSPacketListCallback **ppCallback );

    [helpstring("Retrieves the value for an extended packet list attribute defined by a plug-in.")] HRESULT 
    GetExtendedAttribute( 
                [in] DWORD dwValueName, 
                [out] VARIANT *pVariantValue );

    [helpstring("Retrieves the name and value for an extended packet attribute defined by a plug-in.")] HRESULT             
    GetExtendedAttributeByIndex( 
                [in] DWORD dwIndex, 
                [out] DWORD * pdwValueName,
                [out] VARIANT *pVariantValue );

    [helpstring("Specifies the value for an extended packet attribute defined by a plug-in.")] HRESULT             
    SetExtendedAttribute( 
                [in] DWORD dwValueName, 
                [in] VARIANT VariantValue );

    [helpstring("Retrieves the number of extended attributes.")] HRESULT             
    GetExtendedAttributeCount( 
                [out] DWORD * pdwAttrs );

	[helpstring("Requests the status for a packet list.")] HRESULT 
    ReportStatus( [in] DWORD dwStatus );

	[helpstring("Creates a copy of the packet list.")] HRESULT 
    ClonePacketList( [out] IWMSPacketList **ppClonedPacketList );
    
	[helpstring("Allocates a new packet.")] HRESULT 	
    AllocPacket( [out] IWMSPacket **ppPacket );
};





//////////////////////////////////////////////////////////////////////////////
//
//                              PACKET PARSERS
//
//////////////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(8B59F7E1-5411-11d2-9EFF-006097D2D7CF),
    version(9.0),
    helpstring("Provides methods to manipulate individual packets.  This interface is implemented by a media parser plug-in.")
]
interface IWMSPacketParser : IUnknown
{
    // Call this if you change packet attributes. 
    [helpstring("Updates the packet data to reflect the packets attribute values.")] HRESULT 
    UpdatePacket( [in] IWMSPacket *pPacket );

	[helpstring("Adds an array of packets to a packet list.")] HRESULT 
    CombinePackets(
                [in] DWORD dwNumInputPackets,
                [in] IWMSPacket **pInputPacketArray,
                [in] IWMSPacketList *pPacketList,
                [in] DWORD dwFlags
                );
}




//////////////////////////////////////////////////////////////////////////////
//
//                         STREAM EVENT INTERFACES
//
//////////////////////////////////////////////////////////////////////////////



// These specify types of stream signals
typedef [public] enum WMS_STREAM_SIGNAL_TYPE
{
    WMS_NO_STREAM_CHANGE,                                                           // 0x0

    // Param: None
    // There are different errors passed in hr:
    //   1. the source crashed
    //   2. we hit the last packet, but the source is still
    //         running so it may be seeked back to the beginning.
    WMS_STREAM_ERROR,                                                               // 0x1

    // Param: None
    // This happens when a stream error causes a fail-over in
    // a playlist. This will be followed by a playlistchange.
    WMS_STREAM_ERROR_HANDLED_BY_PLAYLIST,                                           // 0x2

    // Param: The header of the new stream
    // This happens when a playlist changes its active entry.
    WMS_PLAYLIST_CHANGED,                                                           // 0x3

    // Param: see below for EOS type or none
    WMS_END_OF_STREAM,                                                              // 0x4

    // Param: The header of the queued stream
    WMS_PLAYLIST_STREAM_QUEUED,                                                     // 0x5

    // Param: The expected amount of dead air in milliseconds
    WMS_BEGIN_NO_DATA_PERIOD,                                                       // 0x6

    // Param: The name of the event as a BSTR
    WMS_PLAYLIST_EVENT,                                                             // 0x7

    // Param: The name of the event as a BSTR
    WMS_PLAYLIST_CUE_EVENT,                                                         // 0x8

    // Param: The name of the event as a BSTR
    WMS_PLAYLIST_UNCUE_EVENT,                                                       // 0x9

    // Param: The name of the element as a BSTR
    WMS_PLAYLIST_BEGIN_ELEMENT_EVENT,                                               // 0xA

    // Param: The name of the element as a BSTR
    WMS_PLAYLIST_END_ELEMENT_EVENT,                                                 // 0xB

    // Param: None
    WMS_STREAM_SWITCH_DONE,                                                         // 0xC

    // Param: None
    WMS_RESET_TO_REAL_TIME,                                                         // 0xD

	// Param : QWORD, first DWORD contains the number of packets lost
	// while second DWORD contains the total packets recieved so far
    WMS_DATA_LOSS_DETECTED,                                                          // 0xE

    WMS_REUSE_ACCEL_PARAMS                                                           // 0xf
} WMS_STREAM_SIGNAL_TYPE;

// These are the EOS types.
typedef [public] enum WMS_STREAM_SIGNAL_EOS_TYPE
{
    WMS_STREAM_SIGNAL_EOS_RESERVED  = 1, //  internal type don't use
    WMS_STREAM_SIGNAL_EOS_RECEDING  = 2,

}WMS_STREAM_SIGNAL_EOS_TYPE;

//////////////////////////////////////////////////////////////////////////////
[
    object,
    pointer_default(unique),
    uuid(7B10F261-26AA-11d2-9EF2-006097D2D7CF),
    version(9.0),
    helpstring("Contains a method to provide notification of stream signals defined by WMS_STREAM_SIGNAL_TYPE.")
]
interface IWMSStreamSignalHandler : IUnknown
{
    //
    // The input parameter dwSignalType should have one of the enumerated values
    // in WMS_STREAM_SIGNAL_TYPE.
    //
	[helpstring("Provides notification of a stream signal defined by WMS_STREAM_SIGNAL_TYPE.")] HRESULT 
    OnStreamSignal(
                [in] DWORD dwSignalType,                // WMS_STREAM_SIGNAL_TYPE
                [in] VARIANT *pSignalParameter,
                [in] IWMSContext *pPresentation
                );
};