include/realmedia/rmaformt.h

   1 /****************************************************************************
   2  *
   3  *  $Id: rmaformt.h 7 2003-05-30 02:18:02Z gabest $
   4  *
   5  *  Copyright (C) 1995-1999 RealNetworks, Inc. All rights reserved.
   6  *
   7  *  http://www.real.com/devzone
   8  *
   9  *  This program contains proprietary
  10  *  information of Progressive Networks, Inc, and is licensed
  11  *  subject to restrictions on use and distribution.
  12  *
  13  *
  14  *  RealMedia Architecture Broadcast Format Plug-in Interfaces.
  15  *
  16  */
  17
  18 #ifndef _RMAFORMT_H_
  19 #define _RMAFORMT_H_
  20
  21 #include "rmafiles.h"
  22
  23 /*
  24  * Forward declarations of some interfaces defined here-in.
  25  */
  26 typedef _INTERFACE      IRMAFileFormatObject        IRMAFileFormatObject;
  27 typedef _INTERFACE      IRMABroadcastFormatObject   IRMABroadcastFormatObject;
  28 typedef _INTERFACE      IRMAFormatResponse          IRMAFormatResponse;
  29 typedef _INTERFACE      IRMAFileObject              IRMAFileObject;
  30 typedef _INTERFACE      IRMANetworkServices         IRMANetworkServices;
  31 typedef _INTERFACE      IRMAPacket                  IRMAPacket;
  32 typedef _INTERFACE      IRMAValues                  IRMAValues;
  33 typedef _INTERFACE      IRMAPacketTimeOffsetHandler IRMAPacketTimeOffsetHandler;
  34 typedef _INTERFACE      IRMAPacketTimeOffsetHandlerResponse
  35                                                     IRMAPacketTimeOffsetHandlerResponse;
  36 typedef _INTERFACE      IRMALiveFileFormatInfo      IRMALiveFileFormatInfo;
  37
  38
  39 /****************************************************************************
  40  *
  41  *  Interface:
  42  *
  43  *      IRMAFileFormatObject
  44  *
  45  *  Purpose:
  46  *
  47  *      Object that allows a Controller to communicate with a specific
  48  *      File Format plug-in session
  49  *
  50  *  IID_IRMAFileFormatObject:
  51  *
  52  *      {00000F00-0901-11d1-8B06-00A024406D59}
  53  *
  54  */
  55 DEFINE_GUID(IID_IRMAFileFormatObject, 0x00000F00, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
  56                         0xa0, 0x24, 0x40, 0x6d, 0x59);
  57
  58 #undef  INTERFACE
  59 #define INTERFACE   IRMAFileFormatObject
  60
  61 DECLARE_INTERFACE_(IRMAFileFormatObject, IUnknown)
  62 {
  63     /*
  64      *  IUnknown methods
  65      */
  66     STDMETHOD(QueryInterface)           (THIS_
  67                                         REFIID riid,
  68                                         void** ppvObj) PURE;
  69
  70     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
  71
  72     STDMETHOD_(ULONG,Release)           (THIS) PURE;
  73
  74     /*
  75      *  IRMAFileFormatObject methods
  76      */
  77
  78     /************************************************************************
  79      *  Method:
  80      *      IRMAFileFormatObject::GetFileFormatInfo
  81      *  Purpose:
  82      *      Returns information vital to the instantiation of file format
  83      *      plugins.
  84      */
  85     STDMETHOD(GetFileFormatInfo)(THIS_
  86                                 REF(const char**) /*OUT*/ pFileMimeTypes,
  87                                 REF(const char**) /*OUT*/ pFileExtensions,
  88                                 REF(const char**) /*OUT*/ pFileOpenNames
  89                                 ) PURE;
  90
  91     STDMETHOD(InitFileFormat)
  92                         (THIS_
  93                         IRMARequest*            /*IN*/  pRequest,
  94                         IRMAFormatResponse*     /*IN*/  pFormatResponse,
  95                         IRMAFileObject*         /*IN*/  pFileObject) PURE;
  96
  97     STDMETHOD(GetFileHeader)    (THIS) PURE;
  98
  99     STDMETHOD(GetStreamHeader)  (THIS_
 100                                 UINT16 unStreamNumber) PURE;
 101
 102     STDMETHOD(GetPacket)        (THIS_
 103                                 UINT16 unStreamNumber) PURE;
 104
 105     STDMETHOD(Seek)             (THIS_
 106                                 ULONG32 ulOffset) PURE;
 107
 108     STDMETHOD(Close)            (THIS) PURE;
 109 };
 110
 111
 112 /****************************************************************************
 113  *
 114  *  Interface:
 115  *
 116  *      IRMABroadcastFormatObject
 117  *
 118  *  Purpose:
 119  *
 120  *      Object that allows a Controller to communicate with a specific
 121  *      Broadcast Format plug-in session
 122  *
 123  *  IID_IRMABroadcastFormatObject:
 124  *
 125  *      {00000F01-0901-11d1-8B06-00A024406D59}
 126  *
 127  */
 128 DEFINE_GUID(IID_IRMABroadcastFormatObject, 0x00000F01, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 129                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 130
 131 #undef  INTERFACE
 132 #define INTERFACE   IRMABroadcastFormatObject
 133
 134 DECLARE_INTERFACE_(IRMABroadcastFormatObject, IUnknown)
 135 {
 136     /*
 137      *  IUnknown methods
 138      */
 139     STDMETHOD(QueryInterface)           (THIS_
 140                                         REFIID riid,
 141                                         void** ppvObj) PURE;
 142
 143     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 144
 145     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 146
 147     /*
 148      *  IRMABroadcastFormatObject methods
 149      */
 150
 151     /************************************************************************
 152      *  Method:
 153      *      IRMABroadcastFormatObject::GetBroadcastFormatInfo
 154      *  Purpose:
 155      *      Returns information vital to the instantiation of broadcast format
 156      *      plugins.
 157      */
 158     STDMETHOD(GetBroadcastFormatInfo)(THIS_
 159                                 REF(const char*) /*OUT*/ pToken) PURE;
 160
 161     STDMETHOD(InitBroadcastFormat) (THIS_
 162                                  const char*            /*IN*/  pURL,
 163                                  IRMAFormatResponse*    /*IN*/  pFormatResponse
 164                                 ) PURE;
 165
 166     STDMETHOD(GetFileHeader)    (THIS) PURE;
 167
 168     STDMETHOD(GetStreamHeader)  (THIS_
 169                                 UINT16 unStreamNumber) PURE;
 170
 171     STDMETHOD(StartPackets)     (THIS_
 172                                 UINT16 unStreamNumber) PURE;
 173
 174     STDMETHOD(StopPackets)      (THIS_
 175                                 UINT16 unStreamNumber) PURE;
 176 };
 177
 178
 179 /****************************************************************************
 180  *
 181  *  Interface:
 182  *
 183  *      IRMAFormatResponse
 184  *
 185  *  Purpose:
 186  *
 187  *      Object that allows a specific File Format Object to communicate
 188  *      with its user
 189  *
 190  *  IID_IRMAFormatResponse:
 191  *
 192  *      {00000F02-0901-11d1-8B06-00A024406D59}
 193  *
 194  */
 195 DEFINE_GUID(IID_IRMAFormatResponse, 0x00000F02, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 196                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 197
 198 #undef  INTERFACE
 199 #define INTERFACE   IRMAFormatResponse
 200
 201 DECLARE_INTERFACE_(IRMAFormatResponse, IUnknown)
 202 {
 203     /*
 204      *  IUnknown methods
 205      */
 206     STDMETHOD(QueryInterface)           (THIS_
 207                                         REFIID riid,
 208                                         void** ppvObj) PURE;
 209
 210     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 211
 212     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 213
 214     /*
 215      *  IRMAFormatResponse methods
 216      */
 217     STDMETHOD(InitDone)                 (THIS_
 218                                         PN_RESULT       status) PURE;
 219
 220     STDMETHOD(PacketReady)              (THIS_
 221                                         PN_RESULT       status,
 222                                         IRMAPacket*     pPacket) PURE;
 223
 224     STDMETHOD(SeekDone)                 (THIS_
 225                                         PN_RESULT       status) PURE;
 226
 227     STDMETHOD(FileHeaderReady)          (THIS_
 228                                         PN_RESULT       status,
 229                                         IRMAValues*     pHeader) PURE;
 230
 231     STDMETHOD(StreamHeaderReady)        (THIS_
 232                                         PN_RESULT       status,
 233                                         IRMAValues*     pHeader) PURE;
 234
 235     STDMETHOD(StreamDone)               (THIS_
 236                                         UINT16          unStreamNumber) PURE;
 237 };
 238
 239 /****************************************************************************
 240  *
 241  *  Interface:
 242  *
 243  *      IRMAPacketFormat
 244  *
 245  *  Purpose:
 246  *
 247  *      Interface that modifies the behavior of an IRMAFileFormat by defining
 248  *      the packet format it will be creating.
 249  *
 250  *  IID_IRMAPacketFormat:
 251  *
 252  *      {00000F03-0901-11d1-8B06-00A024406D59}
 253  *
 254  */
 255 DEFINE_GUID(IID_IRMAPacketFormat, 0x00000F03, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 256                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 257
 258 #undef  INTERFACE
 259 #define INTERFACE   IRMAPacketFormat
 260
 261 DECLARE_INTERFACE_(IRMAPacketFormat, IUnknown)
 262 {
 263     /*
 264      *  IUnknown methods
 265      */
 266     STDMETHOD(QueryInterface)           (THIS_
 267                                         REFIID riid,
 268                                         void** ppvObj) PURE;
 269
 270     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 271
 272     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 273
 274     /*
 275      *  IRMAPacketFormat methods
 276      */
 277     STDMETHOD(GetSupportedPacketFormats)
 278                                         (THIS_
 279                                         REF(const char**) pFormats) PURE;
 280
 281     STDMETHOD(SetPacketFormat)          (THIS_
 282                                         const char*     pFormat) PURE;
 283 };
 284
 285 /****************************************************************************
 286  *
 287  *  Interface:
 288  *
 289  *      IRMAPacketTimeOffsetHandler
 290  *
 291  *  Purpose:
 292  *
 293  *      Provides methods for handling the changing of a packets timestamp.
 294  *
 295  *  IID_IRMAPacketTimeOffsetHandler:
 296  *
 297  *      {00000F04-0901-11d1-8B06-00A024406D59}
 298  *
 299  */
 300 DEFINE_GUID(IID_IRMAPacketTimeOffsetHandler, 0x00000F04, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 301                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 302
 303
 304 DECLARE_INTERFACE_(IRMAPacketTimeOffsetHandler, IUnknown)
 305 {
 306     /*
 307      * IUnknown methods
 308      */
 309     STDMETHOD(QueryInterface)   (THIS_
 310                                 REFIID riid,
 311                                 void** ppvObj) PURE;
 312
 313     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 314
 315     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 316
 317     /*
 318      * IRMAPacketTimeOffsetHandler methods
 319      */
 320
 321     /************************************************************************
 322      *  Method:
 323      *      IRMAPacketTimeOffsetHandler::Init
 324      *  Purpose:
 325      *      Initialize the IRMAPacketTimeOffsetHandler and set the response.
 326      *      Implementors should look up the MimeType.
 327      */
 328     STDMETHOD(Init)             (THIS_
 329                                 IRMAPacketTimeOffsetHandlerResponse* pResponse,
 330                                 IRMAValues* pHeader,
 331                                 IUnknown* pContext) PURE;
 332
 333     /************************************************************************
 334      *  Method:
 335      *      IRMAPacketTimeOffsetHandler::SetTimeOffset
 336      *  Purpose:
 337      *      Called to set the time offset.  Uses a bool and a UINT32 instead
 338      *      of and INT32 so that the time offset wraps around after 47 days
 339      *      instead of 24.  bPlus says whether to add or subtract.
 340      */
 341     STDMETHOD(SetTimeOffset)    (THIS_
 342                                 UINT32 ulTimeOffset,
 343                                 BOOL bPlus) PURE;
 344
 345     /************************************************************************
 346      *  Method:
 347      *      IRMAPacketTimeOffsetHandler::HandlePacket
 348      *  Purpose:
 349      *      give the IRMAPacketTimeOffsetHandler a packet to modify for the
 350      *      time offset.
 351      */
 352     STDMETHOD(HandlePacket)     (THIS_
 353                                 IRMAPacket* pPacket) PURE;
 354
 355 };
 356
 357 /****************************************************************************
 358  *
 359  *  Interface:
 360  *
 361  *      IRMAPacketTimeOffsetHandlerResponse
 362  *
 363  *  Purpose:
 364  *
 365  *      Provides methods for the IRMAPacketTimeOffsetHandler to respond to.
 366  *
 367  *  IID_IRMAPacketTimeOffsetHandlerResponse:
 368  *
 369  *      {00000F05-0901-11d1-8B06-00A024406D59}
 370  *
 371  */
 372 DEFINE_GUID(IID_IRMAPacketTimeOffsetHandlerResponse, 0x00000F05, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 373                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 374
 375
 376 DECLARE_INTERFACE_(IRMAPacketTimeOffsetHandlerResponse, IUnknown)
 377 {
 378     /*
 379      * IUnknown methods
 380      */
 381     STDMETHOD(QueryInterface)   (THIS_
 382                                 REFIID riid,
 383                                 void** ppvObj) PURE;
 384
 385     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 386
 387     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 388
 389     /*
 390      * IRMAPacketTimeOffsetHandler methods
 391      */
 392
 393     /************************************************************************
 394      *  Method:
 395      *      IRMAPacketTimeOffsetHandler::PacketReady
 396      *  Purpose:
 397      *      Called by IRMAPacketTimeOffsetHandler to pass back the packet
 398      *      when it is done with it.
 399      */
 400     STDMETHOD(TimeOffsetPacketReady)    (THIS_
 401                                         IRMAPacket* pPacket) PURE;
 402
 403 };
 404
 405 /****************************************************************************
 406  *
 407  *  Interface:
 408  *
 409  *      IRMALiveFileFormatInfo
 410  *
 411  *  Purpose:
 412  *
 413  *      Provides miscellaneous information needed to transmit a live stream.
 414  *      Optionally implemented by the file format object.
 415  *
 416  *  IID_IRMALiveFileFormatInfo:
 417  *
 418  *      {00000F06-0901-11d1-8B06-00A024406D59}
 419  *
 420  */
 421 DEFINE_GUID(IID_IRMALiveFileFormatInfo, 0x00000F06, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 422                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 423
 424 #undef  INTERFACE
 425 #define INTERFACE   IRMALiveFileFormatInfo
 426
 427 DECLARE_INTERFACE_(IRMALiveFileFormatInfo, IUnknown)
 428 {
 429     /*
 430      *  IUnknown methods
 431      */
 432     STDMETHOD(QueryInterface)           (THIS_
 433                                         REFIID riid,
 434                                         void** ppvObj) PURE;
 435
 436     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 437
 438     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 439
 440     /*
 441      *  IRMALiveFileFormatInfo methods
 442      */
 443
 444     /************************************************************************
 445      *  Method:
 446      *      IRMALiveFileFormatInfo::VerifyFileCompatibility
 447      *  Purpose:
 448      *      Compares two file headers and returns PNR_OK if these two
 449      *      files can be transmitted sequentially in a single live
 450      *      presentation.
 451      */
 452     STDMETHOD(VerifyFileCompatibility)      (THIS_
 453                                             IRMAValues* pFileHeader1,
 454                                             IRMAValues* pFileHeader2) PURE;
 455
 456     /************************************************************************
 457      *  Method:
 458      *      IRMALiveFileFormatInfo::VerifyStreamCompatibility
 459      *  Purpose:
 460      *      Compares two stream headers and returns PNR_OK if these two
 461      *      streams can be transmitted sequentially in a single live
 462      *      presentation.
 463      */
 464     STDMETHOD(VerifyStreamCompatibility)    (THIS_
 465                                             IRMAValues* pStreamHeader1,
 466                                             IRMAValues* pStreamHeader2) PURE;
 467
 468     /************************************************************************
 469      *  Method:
 470      *      IRMALiveFileFormatInfo::IsLiveResendRequired
 471      *  Purpose:
 472      *      Returns TRUE if this stream requires the latest packet to be
 473      *      resent periodically in a live presentation.
 474      */
 475     STDMETHOD_(BOOL,IsLiveResendRequired)   (THIS_
 476                                             UINT16 unStreamNumber) PURE;
 477
 478     /************************************************************************
 479      *  Method:
 480      *      IRMALiveFileFormatInfo::GetResendBitrate
 481      *  Purpose:
 482      *      If periodic live resends are required for this stream, this
 483      *      method returns the rate at which we should resend packets. The
 484      *      resend rate is measured in bits per second.
 485      */
 486     STDMETHOD(GetResendBitrate)             (THIS_
 487                                             UINT16 unStreamNumber,
 488                                             REF(UINT32) ulBitrate) PURE;
 489
 490     /************************************************************************
 491      *  Method:
 492      *      IRMALiveFileFormatInfo::GetResendDuration
 493      *  Purpose:
 494      *      If periodic live resends are required for this stream, this
 495      *      method returns the number of milliseconds for which this packet
 496      *      should be resent.
 497      */
 498     STDMETHOD(GetResendDuration)            (THIS_
 499                                             IRMAPacket* pPacket,
 500                                             REF(UINT32) ulDuration) PURE;
 501
 502     /************************************************************************
 503      *  Method:
 504      *      IRMALiveFileFormatInfo::FormResendPacket
 505      *  Purpose:
 506      *      Forms a live resend packet based upon the original packet passed
 507      *      as the first parameter. This allows the file format plugin to
 508      *      make resend packets distinguishable from original packets.
 509      */
 510     STDMETHOD(FormResendPacket)         (THIS_
 511                                         IRMAPacket* pOriginalPacket,
 512                                         REF(IRMAPacket*) pResendPacket) PURE;
 513 };
 514
 515
 516
 517
 518 #endif  /* _RMAFORMT_H_ */