include/realmedia/rmaplugn.h

   1 /****************************************************************************
   2  *
   3  *  $Id: rmaplugn.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  *  Plugin init / inspector interfaces
  15  *
  16  */
  17
  18 #ifndef _RMAPLUGN_H_
  19 #define _RMAPLUGN_H_
  20
  21 /*
  22  * Forward declarations of some interfaces defined or used here-in.
  23  */
  24 typedef _INTERFACE  IUnknown                        IUnknown;
  25 typedef _INTERFACE  IRMAPlugin                      IRMAPlugin;
  26 typedef _INTERFACE  IRMAPluginEnumerator            IRMAPluginEnumerator;
  27 typedef _INTERFACE  IRMAPluginChallenger            IRMAPluginChallenger;
  28 typedef _INTERFACE  IRMABuffer                      IRMABuffer;
  29 typedef _INTERFACE  IRMAValues                      IRMAValues;
  30
  31 /****************************************************************************
  32  *
  33  *  Function:
  34  *
  35  *      RMACreateInstance()
  36  *
  37  *  Purpose:
  38  *
  39  *      Function implemented by all plugin DLL's to create an instance of
  40  *      any of the objects supported by the DLL. This method is similar to
  41  *      Window's CoCreateInstance() in its purpose, except that it only
  42  *      creates objects from this plugin DLL.
  43  *
  44  *      NOTE: Aggregation is never used. Therefore an outer unknown is
  45  *      not passed to this function, and you do not need to code for this
  46  *      situation.
  47  *
  48  */
  49 #ifdef _MACINTOSH
  50 #pragma export on
  51 #endif
  52
  53 STDAPI RMACreateInstance
  54                 (
  55                     IUnknown**  /*OUT*/ ppIUnknown
  56                 );
  57
  58 #ifdef _MACINTOSH
  59 #pragma export off
  60 #endif
  61
  62
  63 /****************************************************************************
  64  *
  65  *  Function:
  66  *
  67  *      RMAShutdown()
  68  *
  69  *  Purpose:
  70  *
  71  *      Function implemented by all plugin DLL's to free any *global*
  72  *      resources. This method is called just before the DLL is unloaded.
  73  *
  74  */
  75 #ifdef _MACINTOSH
  76 #pragma export on
  77 #endif
  78
  79 STDAPI RMAShutdown(void);
  80
  81 #ifdef _MACINTOSH
  82 #pragma export off
  83 #endif
  84
  85
  86 /****************************************************************************
  87  *
  88  *  Interface:
  89  *
  90  *      IRMAPlugin
  91  *
  92  *  Purpose:
  93  *
  94  *      Interface exposed by a plugin DLL to allow inspection of objects
  95  *      supported by the plugin DLL.
  96  *
  97  *  IID_IRMAPlugin:
  98  *
  99  *      {00000C00-0901-11d1-8B06-00A024406D59}
 100  *
 101  */
 102
 103 DEFINE_GUID(IID_IRMAPlugin, 0x00000C00, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 104                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 105
 106 #undef  INTERFACE
 107 #define INTERFACE   IRMAPlugin
 108
 109 DECLARE_INTERFACE_(IRMAPlugin, IUnknown)
 110 {
 111     /*
 112      *  IUnknown methods
 113      */
 114     STDMETHOD(QueryInterface)           (THIS_
 115                                         REFIID riid,
 116                                         void** ppvObj) PURE;
 117
 118     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 119
 120     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 121
 122     /*
 123      *  IRMAPlugin methods
 124      */
 125
 126     /************************************************************************
 127      *  Method:
 128      *      IRMAPlugin::GetPluginInfo
 129      *  Purpose:
 130      *      Returns the basic information about this plugin. Including:
 131      *
 132      *      bMultipleLoad       Whether or not this plugin can be instantiated
 133      *                          multiple times. All File Formats must set
 134      *                          this value to TRUE.  The only other type of
 135      *                          plugin that can specify bMultipleLoad=TRUE is
 136      *                          a filesystem plugin.  Any plugin that sets
 137      *                          this flag to TRUE must not use global variables
 138      *                          of any type.
 139      *
 140      *                          Setting this flag to TRUE implies that you
 141      *                          accept that your plugin may be instantiated
 142      *                          multiple times (possibly in different
 143      *                          address spaces).  Plugins are instantiated
 144      *                          multiple times only in the server (for
 145      *                          performance reasons).
 146      *
 147      *                          An example of a plugin, that must set this
 148      *                          flag to FALSE is a filesystem plugin that
 149      *                          uses a single TCP connection to communicate
 150      *                          with a database.
 151      *
 152      *      pDescription        which is used in about UIs (can be NULL)
 153      *      pCopyright          which is used in about UIs (can be NULL)
 154      *      pMoreInfoURL        which is used in about UIs (can be NULL)
 155      *      ulVersionNumber     The version of this plugin.
 156      */
 157     STDMETHOD(GetPluginInfo)    (THIS_
 158                                 REF(BOOL)        /*OUT*/ bMultipleLoad,
 159                                 REF(const char*) /*OUT*/ pDescription,
 160                                 REF(const char*) /*OUT*/ pCopyright,
 161                                 REF(const char*) /*OUT*/ pMoreInfoURL,
 162                                 REF(ULONG32)     /*OUT*/ ulVersionNumber) PURE;
 163
 164     /************************************************************************
 165      *  Method:
 166      *      IRMAPlugin::InitPlugin
 167      *  Purpose:
 168      *      Initializes the plugin for use. This interface must always be
 169      *      called before any other method is called. This is primarily needed
 170      *      so that the plugin can have access to the context for creation of
 171      *      IRMABuffers and IMalloc.
 172      */
 173     STDMETHOD(InitPlugin)   (THIS_
 174                             IUnknown*   /*IN*/  pContext) PURE;
 175
 176 };
 177
 178
 179 /****************************************************************************
 180  *
 181  *  Interface:
 182  *
 183  *      IRMAPluginEnumerator
 184  *
 185  *  Purpose:
 186  *
 187  *      provide methods to enumerate through all the plugins installed
 188  *
 189  *  IID_IRMAPluginEnumerator:
 190  *
 191  *      {00000C01-0901-11d1-8B06-00A024406D59}
 192  *
 193  */
 194
 195 DEFINE_GUID(IID_IRMAPluginEnumerator, 0x00000C01, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 196                 0xa0, 0x24, 0x40, 0x6d, 0x59);
 197
 198 #undef  INTERFACE
 199 #define INTERFACE   IRMAPluginEnumerator
 200
 201 DECLARE_INTERFACE_(IRMAPluginEnumerator, 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      *  IRMAPluginEnumerator methods
 216      */
 217
 218     /************************************************************************
 219      *  Method:
 220      *      IRMAPluginEnumerator::GetNumOfPlugins
 221      *
 222      *  Purpose:
 223      *      return the number of plugins available
 224      *
 225      */
 226     STDMETHOD_(ULONG32,GetNumOfPlugins) (THIS) PURE;
 227
 228     /************************************************************************
 229      *  Method:
 230      *      IRMAPluginEnumerator::GetPlugin
 231      *  Purpose:
 232      *      Return an instance (IUnknown) of the plugin
 233      *
 234      */
 235     STDMETHOD(GetPlugin)   (THIS_
 236                            ULONG32         /*IN*/  ulIndex,
 237                            REF(IUnknown*)  /*OUT*/ pPlugin) PURE;
 238
 239 };
 240
 241 /****************************************************************************
 242  *
 243  *  Interface:
 244  *
 245  *      IRMAPluginGroupEnumerator
 246  *
 247  *  Purpose:
 248  *
 249  *      Provide a way to enumerate through all of the plugins which
 250  *      implement a specific interface.
 251  *
 252  *  IID_IRMAPluginGroupEnumerator:
 253  *
 254  *      {00000C02-0901-11d1-8B06-00A024406D59}
 255  *
 256  */
 257
 258 DEFINE_GUID(IID_IRMAPluginGroupEnumerator, 0x00000C02, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 259                 0xa0, 0x24, 0x40, 0x6d, 0x59);
 260
 261 #undef  INTERFACE
 262 #define INTERFACE   IRMAPluginGroupEnumerator
 263
 264 #define CLSID_IRMAPluginGroupEnumerator IID_IRMAPluginGroupEnumerator
 265
 266 DECLARE_INTERFACE_(IRMAPluginGroupEnumerator, IUnknown)
 267 {
 268     /*
 269      * IUnknown methods
 270      */
 271
 272     /*
 273      * IRMAPluginGroupEnumerator methods
 274      */
 275     STDMETHOD(QueryInterface)           (THIS_
 276                                         REFIID riid,
 277                                         void** ppvObj) PURE;
 278
 279     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 280
 281     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 282
 283     /******************************************************************
 284      * Method:
 285      *      IRMAPluginGroupEnumerator::Init
 286      *
 287      * Purpose:
 288      *      tell the group enumerator which interface to group the plugins
 289      *     into, this method must be called before the other methods can
 290      *     be called.
 291      *
 292      */
 293     STDMETHOD(Init)         (THIS_
 294                             REFIID    iid) PURE;
 295
 296
 297     /******************************************************************
 298      * Method:
 299      *     IRMAPluginGroupEnumerator::GetNumOfPlugins
 300      *
 301      * Purpose:
 302      *     return the number of plugins available that support a
 303 particular
 304      *     interface.
 305      *
 306      */
 307     STDMETHOD_(ULONG32,GetNumOfPlugins) (THIS) PURE;
 308
 309
 310     /******************************************************************
 311      * Method:
 312      *     IRMAPluginGroupEnumerator::GetPlugin
 313      * Purpose:
 314      *     Return an instance (IUnknown) of the plugin
 315      *
 316      */
 317     STDMETHOD(GetPlugin)   (THIS_
 318       UINT32    /*IN*/  ulIndex,
 319       REF(IUnknown*)  /*OUT*/ pPlugin) PURE;
 320
 321 };
 322
 323
 324 /****************************************************************************
 325  *
 326  *  Interface:
 327  *
 328  *      IRMAPluginReloader
 329  *
 330  *  Purpose:
 331  *
 332  *      Tells the client core to reload all plugins.
 333  *
 334  *  IID_IRMAPluginReloader:
 335  *
 336  *      {00000C03-0901-11d1-8B06-00A024406D59}
 337  *
 338  */
 339
 340 DEFINE_GUID(IID_IRMAPluginReloader, 0x00000C03, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 341                 0xa0, 0x24, 0x40, 0x6d, 0x59);
 342
 343 #undef  INTERFACE
 344 #define INTERFACE   IRMAPluginReloader
 345
 346 DECLARE_INTERFACE_(IRMAPluginReloader, IUnknown)
 347 {
 348     /*
 349      *  IUnknown methods
 350      */
 351     STDMETHOD(QueryInterface)           (THIS_
 352                                         REFIID riid,
 353                                         void** ppvObj) PURE;
 354
 355     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 356
 357     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 358
 359     /*
 360      *  IRMAPluginReloader methods
 361      */
 362
 363     /************************************************************************
 364      *  Method:
 365      *      IRMAPluginReloader::ReloadPlugins
 366      *  Purpose:
 367      *      Causes the client core to reload all plugins.
 368      *
 369      */
 370     STDMETHOD(ReloadPlugins)    (THIS) PURE;
 371 };
 372
 373
 374
 375 /****************************************************************************
 376  *
 377  *  Interface:
 378  *
 379  *      IRMAPluginFactory
 380  *
 381  *  Purpose:
 382  *
 383  *      This interface is implemented by a plugin in order to have more then
 384  *          one "RMA plugin" in a single DLL.  I.e., a plugin author could
 385  *          use this interface to have 3 different file format plugins in
 386  *          a single DLL.
 387  *
 388  *  IID_IRMAPluginFactory:
 389  *
 390  *      {00000C04-0901-11d1-8B06-00A024406D59}
 391  *
 392  */
 393
 394 DEFINE_GUID(IID_IRMAPluginFactory, 0x00000C04, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 395                 0xa0, 0x24, 0x40, 0x6d, 0x59);
 396
 397 #undef  INTERFACE
 398 #define INTERFACE   IRMAPluginFactory
 399
 400 DECLARE_INTERFACE_(IRMAPluginFactory, IUnknown)
 401 {
 402     /*
 403      *  IUnknown methods
 404      */
 405     STDMETHOD(QueryInterface)           (THIS_
 406                                          REFIID riid,
 407                                          void** ppvObj) PURE;
 408
 409     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 410
 411     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 412
 413     /*
 414      *  IRMAPluginFactory methods
 415      */
 416
 417     /*****************************************************************
 418      *  Method:
 419      *      IRMAPluginFactory::GetNumPlugins
 420      *  Purpose:
 421      *      Report the number of Plugins within the DLL.
 422      *
 423      *  Parameters:
 424      */
 425     STDMETHOD_(UINT16, GetNumPlugins) (THIS)  PURE;
 426
 427     /*****************************************************************
 428      *  Method:
 429      *      IRMAPluginFactory::GetPlugin
 430      *  Purpose:
 431      *      Returns an IUnknown interface to the requested plugin.
 432      *
 433      *  Parameters:
 434      */
 435
 436     STDMETHOD(GetPlugin) (THIS_
 437                          UINT16         uIndex,
 438                          IUnknown**     pPlugin) PURE;
 439 };
 440
 441
 442
 443 /****************************************************************************
 444  *
 445  *  Interface:
 446  *
 447  *      IRMAGenericPlugin
 448  *
 449  *  Purpose:
 450  *
 451  *      Interface exposed by a plugin DLL to inform the client / server core
 452  *      that your plugin wishes to have InitPlugin called immediately.
 453  *
 454  *  IID_IRMAGenericPlugin:
 455  *
 456  *      {00000C09-0901-11d1-8B06-00A024406D59}
 457  *
 458  */
 459
 460 DEFINE_GUID(IID_IRMAGenericPlugin, 0x00000C09, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 461                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 462
 463 #undef  INTERFACE
 464 #define INTERFACE   IRMAGenericPlugin
 465
 466 DECLARE_INTERFACE_(IRMAGenericPlugin, IUnknown)
 467 {
 468     /*
 469      *  IUnknown methods
 470      */
 471     STDMETHOD(QueryInterface)           (THIS_
 472                                         REFIID riid,
 473                                         void** ppvObj) PURE;
 474
 475     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 476
 477     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 478
 479     /*
 480      *  IRMAGenericPlugin methods
 481      */
 482
 483     STDMETHOD(IsGeneric)        (THIS_
 484                                 REF(BOOL)        /*OUT*/ bIsGeneric) PURE;
 485 };
 486
 487
 488 DEFINE_GUID(IID_IRMAPluginHandler,      0x00000200, 0xb4c8, 0x11d0, 0x99, 0x95, 0x0, 0xa0, 0x24, 0x8d, 0xa5, 0xf0);
 489
 490 DEFINE_GUID(IID_IRMAPlugin2Handler,     0x00000201, 0xb4c8, 0x11d0, 0x99, 0x95, 0x0, 0xa0, 0x24, 0x8d, 0xa5, 0xf0);
 491
 492 #undef  INTERFACE
 493 #define INTERFACE   IRMAPlugin2Handler
 494
 495 DECLARE_INTERFACE_(IRMAPlugin2Handler, IUnknown)
 496 {
 497     /*
 498      *  IUnknown methods
 499      */
 500     STDMETHOD(QueryInterface)   (THIS_
 501                                 REFIID riid,
 502                                 void** ppvObj) PURE;
 503
 504     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 505
 506     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 507
 508     /*
 509      *  IRMAPlugin2Handler Methods
 510      */
 511
 512      /************************************************************************
 513      *  Method:
 514      *      IRMAPlugin2Handler::Init
 515      *
 516      *  Purpose:
 517      *      Specifies the context and sets the pluginhandler in motion.
 518      *
 519      */
 520     STDMETHOD(Init)    (THIS_ IUnknown* pContext) PURE;
 521
 522      /************************************************************************
 523      *  Method:
 524      *      IRMAPlugin2Handler::GetNumPlugins2
 525      *
 526      *  Purpose:
 527      *      Gets the info of a particular plugin.
 528      *
 529      */
 530     STDMETHOD_(ULONG32,GetNumOfPlugins2)    (THIS) PURE;
 531
 532     /************************************************************************
 533      *  Method:
 534      *      IRMAPlugin2Handler::GetPluginInfo
 535      *
 536      *  Purpose:
 537      *      Gets the info of a particular plugin.
 538      *
 539      */
 540     STDMETHOD(GetPluginInfo)    (THIS_
 541                                 UINT32 unIndex,
 542                                 REF(IRMAValues*) /*OUT*/ Values) PURE;
 543
 544     /************************************************************************
 545      *  Method:
 546      *      IRMAPlugin2Handler::FlushCache()
 547      *
 548      *  Purpose:
 549      *      Flushes the LRU cache -- Unloads all DLLs from memory
 550      *      which currenltly have a refcount of 0.
 551      */
 552
 553     STDMETHOD(FlushCache)       (THIS) PURE;
 554
 555     /************************************************************************
 556      *  Method:
 557      *      IRMAPlugin2Handler::SetCacheSize
 558      *
 559      *  Purpose:
 560      *      This function sets the size of the Cache. The cache is
 561      *      initally set to 1000KB. To disable the cache simply set
 562      *      the size to 0.If the cache is disabled a DLL will be
 563      *      unloaded whenever it's refcount becomes zero. Which MAY
 564      *      cause performance problems.
 565      */
 566
 567     STDMETHOD(SetCacheSize)     (THIS_ ULONG32 nSizeKB) PURE;
 568
 569     /************************************************************************
 570      *  Method:
 571      *      IRMAPlugin2Handler::GetInstance
 572      *
 573      *  Purpose:
 574      *
 575      *      This function will return a plugin instance given a plugin index.
 576      *
 577      */
 578
 579     STDMETHOD(GetInstance) (THIS_ UINT32 index, REF(IUnknown*) pUnknown) PURE;
 580
 581     /************************************************************************
 582      *  Method:
 583      *      IRMAPlugin2Handler::FindIndexUsingValues
 584      *
 585      *  Purpose:
 586      *      Finds a plugin  which matches the set of values given. An index
 587      *      is returned which can be used to either get the values (using
 588      *      GetPluginInfo) or an instance can be created using GetPluing().
 589      *
 590      */
 591
 592     STDMETHOD(FindIndexUsingValues)         (THIS_ IRMAValues*,
 593                                                     REF(UINT32) unIndex) PURE;
 594
 595     /************************************************************************
 596      *  Method:
 597      *      IRMAPlugin2Handler::FindPluginUsingValues
 598      *
 599      *  Purpose:
 600      *      Finds a plugin  which matches the set of values given. A Plugin
 601      *      instance is returned.
 602      *
 603      */
 604
 605     STDMETHOD(FindPluginUsingValues)        (THIS_ IRMAValues*,
 606                                                     REF(IUnknown*) pUnk) PURE;
 607
 608     /************************************************************************
 609      *  Method:
 610      *      IRMAPlugin2Handler::FindIndexUsingStrings
 611      *
 612      *  Purpose:
 613      *      Finds a plugin  which matches the set of values given. An index
 614      *      is returned which can be used to either get the values (using
 615      *      GetPluginInfo) or an instance can be created using GetPluing().
 616      *      NOTE: that a max of two values may be given.
 617      */
 618
 619     STDMETHOD(FindIndexUsingStrings)        (THIS_ char* PropName1,
 620                                                     char* PropVal1,
 621                                                     char* PropName2,
 622                                                     char* PropVal2,
 623                                                     char* PropName3,
 624                                                     char* PropVal3,
 625                                                     REF(UINT32) unIndex) PURE;
 626
 627     /************************************************************************
 628      *  Method:
 629      *      IRMAPlugin2Handler::FindPluginUsingStrings
 630      *
 631      *  Purpose:
 632      *      Finds a plugin  which matches the set of values given. A Plugin
 633      *      instance is returned.
 634      *      NOTE: that a max of two values may be given.
 635      */
 636
 637     STDMETHOD(FindPluginUsingStrings)       (THIS_ char* PropName1,
 638                                                     char* PropVal1,
 639                                                     char* PropName2,
 640                                                     char* PropVal2,
 641                                                     char* PropName3,
 642                                                     char* PropVal3,
 643                                                     REF(IUnknown*) pUnk) PURE;
 644
 645     /************************************************************************
 646      *  Method:
 647      *      IRMAPlugin2Handler::FindImplementationFromClassID
 648      *
 649      *  Purpose:
 650      *      Finds a CommonClassFactory plugin which supports the
 651      *      ClassID given. An instance of the Class is returned.
 652      */
 653
 654     STDMETHOD(FindImplementationFromClassID)
 655     (
 656         THIS_
 657         REFGUID GUIDClassID,
 658         REF(IUnknown*) pIUnknownInstance
 659     ) PURE;
 660
 661     /************************************************************************
 662      *  Method:
 663      *      IRMAPlugin2Handler::Close
 664      *
 665      *  Purpose:
 666      *      A function which performs all of the functions of delete.
 667      *
 668      *
 669      */
 670
 671     STDMETHOD(Close)            (THIS) PURE;
 672
 673     /************************************************************************
 674      *  Method:
 675      *      IRMAPlugin2Handler::SetRequiredPlugins
 676      *
 677      *  Purpose:
 678      *      This function sets the required plugin list
 679      *
 680      *
 681      */
 682
 683     STDMETHOD(SetRequiredPlugins) (THIS_ const char** ppszRequiredPlugins) PURE;
 684
 685
 686 };
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696 #endif /* _RMAPLUGN_H_ */