include/realmedia/rmacomm.h

   1 /****************************************************************************
   2  *
   3  *  $Id: rmacomm.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 Common Utility interfaces
  15  *
  16  */
  17
  18 #ifndef _RMACOMM_H_
  19 #define _RMACOMM_H_
  20
  21 #include "rmaengin.h" // For RMATimeval
  22
  23 /*
  24  * Forward declarations of some interfaces defined here-in.
  25  */
  26
  27 typedef _INTERFACE      IRMACommonClassFactory          IRMACommonClassFactory;
  28 typedef _INTERFACE      IRMAStatistics                  IRMAStatistics;
  29 typedef _INTERFACE      IRMARegistryID                  IRMARegistryID;
  30 typedef _INTERFACE      IRMAServerFork                  IRMAServerFork;
  31 typedef _INTERFACE      IRMAServerControl               IRMAServerControl;
  32 typedef _INTERFACE      IRMAReconfigServerResponse      IRMAReconfigServerResponse;
  33 typedef _INTERFACE      IRMABuffer                      IRMABuffer;
  34 typedef _INTERFACE      IRMAWantServerReconfigNotification
  35                                                 IRMAWantServerReconfigNotification;
  36 typedef _INTERFACE      IRMAFastAlloc                   IRMAFastAlloc;
  37
  38
  39
  40 /****************************************************************************
  41  *
  42  *  Interface:
  43  *
  44  *      IRMACommonClassFactory
  45  *
  46  *  Purpose:
  47  *
  48  *      RMA interface that manages the creation of common RMA classes.
  49  *
  50  *  IID_IRMACommonClassFactory:
  51  *
  52  *      {00000000-0901-11d1-8B06-00A024406D59}
  53  *
  54  */
  55 DEFINE_GUID(IID_IRMACommonClassFactory, 0x00000000, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
  56                         0xa0, 0x24, 0x40, 0x6d, 0x59);
  57
  58 #undef  INTERFACE
  59 #define INTERFACE   IRMACommonClassFactory
  60
  61 DECLARE_INTERFACE_(IRMACommonClassFactory, 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      *  IRMACommonClassFactory methods
  76      */
  77
  78     /************************************************************************
  79      *  Method:
  80      *      IRMACommonClassFactory::CreateInstance
  81      *  Purpose:
  82      *      Creates instances of common objects supported by the system,
  83      *      like IRMABuffer, IRMAPacket, IRMAValues, etc.
  84      *
  85      *      This method is similar to Window's CoCreateInstance() in its
  86      *      purpose, except that it only creates objects of a well known
  87      *      types.
  88      *
  89      *      NOTE: Aggregation is never used. Therefore and outer unknown is
  90      *      not passed to this function, and you do not need to code for this
  91      *      situation.
  92      */
  93     STDMETHOD(CreateInstance)           (THIS_
  94                                         REFCLSID    /*IN*/  rclsid,
  95                                         void**      /*OUT*/ ppUnknown) PURE;
  96
  97     /************************************************************************
  98      *  Method:
  99      *      IRMAController::CreateInstanceAggregatable
 100      *  Purpose:
 101      *      Creates instances of common objects that can be aggregated
 102      *      supported by the system, like IRMASiteWindowed
 103      *
 104      *      This method is similar to Window's CoCreateInstance() in its
 105      *      purpose, except that it only creates objects of a well known
 106      *      types.
 107      *
 108      *      NOTE 1: Unlike CreateInstance, this method will create internal
 109      *              objects that support Aggregation.
 110      *
 111      *      NOTE 2: The output interface is always the non-delegating
 112      *              IUnknown.
 113      */
 114     STDMETHOD(CreateInstanceAggregatable)
 115                                     (THIS_
 116                                     REFCLSID        /*IN*/  rclsid,
 117                                     REF(IUnknown*)  /*OUT*/ ppUnknown,
 118                                     IUnknown*       /*IN*/  pUnkOuter) PURE;
 119 };
 120
 121
 122 /****************************************************************************
 123  *
 124  *  Interface:
 125  *
 126  *      IRMAStatistics
 127  *
 128  *  Purpose:
 129  *
 130  *      This interface allows update of the client statistics.
 131  *
 132  *  IID_IRMAStatistics:
 133  *
 134  *      {00000001-0901-11d1-8B06-00A024406D59}
 135  *
 136  */
 137 DEFINE_GUID(IID_IRMAStatistics, 0x00000001, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 138             0xa0, 0x24, 0x40, 0x6d, 0x59);
 139
 140 #undef  INTERFACE
 141 #define INTERFACE   IRMAStatistics
 142
 143 DECLARE_INTERFACE_(IRMAStatistics, IUnknown)
 144 {
 145     /*
 146      *  IUnknown methods
 147      */
 148     STDMETHOD(QueryInterface)           (THIS_
 149                                         REFIID riid,
 150                                         void** ppvObj) PURE;
 151
 152     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 153
 154     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 155
 156     /*
 157      *  IRMAStatistics methods
 158      */
 159
 160     /************************************************************************
 161      *  Method:
 162      *      IRMAStatistics::Init
 163      *  Purpose:
 164      *      Pass registry ID to the caller
 165      *
 166      */
 167     STDMETHOD(InitializeStatistics)     (THIS_
 168                                         UINT32  /*IN*/  ulRegistryID) PURE;
 169
 170     /************************************************************************
 171      *  Method:
 172      *      IRMAStatistics::Update
 173      *  Purpose:
 174      *      Notify the client to update its statistics stored in the registry
 175      *
 176      */
 177     STDMETHOD(UpdateStatistics)         (THIS) PURE;
 178 };
 179
 180
 181 /****************************************************************************
 182  *
 183  *  Interface:
 184  *
 185  *      IRMARegistryID
 186  *
 187  *  Purpose:
 188  *
 189  *      This interface is implemented by IRMAPlayer, IRMAStreamSource,
 190  *      and IRMAStream.  It allows the user to get the registry Base ID,
 191  *      for an object that you have a pointer to.
 192  *
 193  *  IID_IRMARegistryID:
 194  *
 195  *      {00000002-0901-11d1-8B06-00A024406D59}
 196  *
 197  */
 198 DEFINE_GUID(IID_IRMARegistryID, 0x00000002, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 199             0xa0, 0x24, 0x40, 0x6d, 0x59);
 200
 201 #undef  INTERFACE
 202 #define INTERFACE   IRMARegistryID
 203
 204 DECLARE_INTERFACE_(IRMARegistryID, IUnknown)
 205 {
 206     /*
 207      *  IUnknown methods
 208      */
 209     STDMETHOD(QueryInterface)           (THIS_
 210                                         REFIID riid,
 211                                         void** ppvObj) PURE;
 212
 213     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 214
 215     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 216
 217     /*
 218      *  IRMARegistryID methods
 219      */
 220
 221     /************************************************************************
 222      *  Method:
 223      *      IRMARegistryID::GetID
 224      *  Purpose:
 225      *      Get the registry ID of the object.
 226      *
 227      */
 228     STDMETHOD(GetID)    (THIS_
 229                         REF(UINT32)     /*OUT*/  ulRegistryID) PURE;
 230 };
 231
 232 /****************************************************************************
 233  *
 234  *  Interface:
 235  *
 236  *      IRMAServerFork
 237  *
 238  *  Purpose:
 239  *
 240  *      This interface is implemented by the server context on Unix
 241  *      platforms.  This interface allows your plugin to fork off a
 242  *      process.  Note that the process that is forked off cannot use
 243  *      any RMA APIs.  The fork() system call is prohibited from within
 244  *      a RMA plugin.
 245  *
 246  *  IID_IRMAServerFork:
 247  *
 248  *      {00000003-0901-11d1-8B06-00A024406D59}
 249  *
 250  */
 251 DEFINE_GUID(IID_IRMAServerFork, 0x00000003, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 252             0xa0, 0x24, 0x40, 0x6d, 0x59);
 253
 254 #undef  INTERFACE
 255 #define INTERFACE   IRMAServerFork
 256
 257 DECLARE_INTERFACE_(IRMAServerFork, IUnknown)
 258 {
 259     /*
 260      *  IUnknown methods
 261      */
 262     STDMETHOD(QueryInterface)           (THIS_
 263                                         REFIID riid,
 264                                         void** ppvObj) PURE;
 265
 266     STDMETHOD_(ULONG,AddRef)            (THIS) PURE;
 267
 268     STDMETHOD_(ULONG,Release)           (THIS) PURE;
 269
 270     /*
 271      *  IRMAServerFork methods
 272      */
 273
 274     /************************************************************************
 275      *  Method:
 276      *      IRMAServerFork::Fork
 277      *  Purpose:
 278      *      Fork off a child process.  The child process cannot use any RMA
 279      *      APIs.  Upon successful completion, Fork returns 0 to the child
 280      *      process and the PID of the child to the parent.  A return value
 281      *      of -1 indicates an error.
 282      *
 283      *      Note:  The child process should *NOT* Release any interfaces.
 284      *          The cleanup of the IRMAServerFork() interface and other
 285      *          RMA interfaces is done by the parent.
 286      *
 287      */
 288     STDMETHOD_(INT32, Fork)     (THIS) PURE;
 289 };
 290
 291 /*
 292  *
 293  *  Interface:
 294  *
 295  *      IRMAServerControl
 296  *
 297  *  Purpose:
 298  *
 299  *      This inteface provides access to the RealMedia server's controls
 300  *      for shutting down (for now).
 301  *
 302  *      Note:  This registry is not related to the Windows system registry.
 303  *
 304  *  IID_IRMAServerControl:
 305  *
 306  *      {00000004-0901-11d1-8B06-00A024406D59}
 307  *
 308  */
 309 DEFINE_GUID(IID_IRMAServerControl, 0x00000004, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 310             0xa0, 0x24, 0x40, 0x6d, 0x59);
 311
 312 #define CLSID_IRMAServerControl IID_IRMAServerControl
 313
 314 #undef  INTERFACE
 315 #define INTERFACE   IRMAServerControl
 316
 317 DECLARE_INTERFACE_(IRMAServerControl, IUnknown)
 318 {
 319     /*
 320      *  IUnknown methods
 321      */
 322     STDMETHOD(QueryInterface)   (THIS_
 323                                 REFIID riid,
 324                                 void** ppvObj) PURE;
 325
 326     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 327
 328     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 329
 330     /*
 331      *  IRMAServerControl methods
 332      */
 333
 334     /************************************************************************
 335      *  Method:
 336      *      IRMAServerControl::ShutdownServer
 337      *  Purpose:
 338      *      Shutdown the server.
 339      */
 340     STDMETHOD(ShutdownServer)           (THIS_
 341                                         UINT32 status) PURE;
 342 };
 343
 344 /*
 345  *
 346  *  Interface:
 347  *
 348  *      IRMAServerControl2
 349  *
 350  *  Purpose:
 351  *
 352  *      Interface for extended server control methods.
 353  *
 354  *
 355  *  IID_IRMAServerControl2:
 356  *
 357  *      {00000005-0901-11d1-8B06-00A024406D59}
 358  *
 359  */
 360 DEFINE_GUID(IID_IRMAServerControl2, 0x00000005, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 361             0xa0, 0x24, 0x40, 0x6d, 0x59);
 362
 363
 364 #undef  INTERFACE
 365 #define INTERFACE   IRMAServerControl2
 366
 367 DECLARE_INTERFACE_(IRMAServerControl2, IUnknown)
 368 {
 369     /*
 370      *  IUnknown methods
 371      */
 372     STDMETHOD(QueryInterface)   (THIS_
 373                                 REFIID riid,
 374                                 void** ppvObj) PURE;
 375
 376     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 377
 378     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 379
 380     /*
 381      *  IRMAServerControl2 methods
 382      */
 383
 384     /************************************************************************
 385      * IRMAServerControl2::RestartServer
 386      *
 387      * Purpose:
 388      *
 389      *      Completely shutdown the server, then restart.  Mainly used to
 390      * cause not hot setting config var changes to take effect.
 391      */
 392     STDMETHOD(RestartServer) (THIS) PURE;
 393
 394     /************************************************************************
 395      * IRMAServerControl2::ReconfigServer
 396      *
 397      * Purpose:
 398      *
 399      *      Used to cause the server to re-read in config from file or registry
 400      * (however it was started) and attempt to use the values.
 401      */
 402     STDMETHOD(ReconfigServer)   (THIS_ IRMAReconfigServerResponse* pResp) PURE;
 403
 404 };
 405
 406 /*
 407  *
 408  *  Interface:
 409  *
 410  *      IRMAReconfigServerResponse
 411  *
 412  *  Purpose:
 413  *
 414  *      Response interface for IRMAServerControl2::ReconfigServer
 415  *
 416  *
 417  *  IID_IRMAReconfigServerResponse:
 418  *
 419  *      {00000006-0901-11d1-8B06-00A024406D59}
 420  *
 421  */
 422 DEFINE_GUID(IID_IRMAReconfigServerResponse, 0x00000006, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 423             0xa0, 0x24, 0x40, 0x6d, 0x59);
 424
 425
 426 #undef  INTERFACE
 427 #define INTERFACE   IRMAReconfigServerResponse
 428
 429 DECLARE_INTERFACE_(IRMAReconfigServerResponse, IUnknown)
 430 {
 431     /*
 432      *  IUnknown methods
 433      */
 434     STDMETHOD(QueryInterface)   (THIS_
 435                                 REFIID riid,
 436                                 void** ppvObj) PURE;
 437
 438     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 439
 440     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 441
 442     /************************************************************************
 443      * IRMAReconfigServerResponse::ReconfigServerDone
 444      *
 445      * Purpose:
 446      *
 447      *      Notification that reconfiguring the server is done.
 448      */
 449     STDMETHOD(ReconfigServerDone)   (THIS_
 450                                     PN_RESULT res,
 451                                     IRMABuffer** pInfo,
 452                                     UINT32 ulNumInfo) PURE;
 453 };
 454
 455 /*
 456  *
 457  *  Interface:
 458  *
 459  *      IRMAServerReconfigNotification
 460  *
 461  *  Purpose:
 462  *
 463  *      Register with the server that you want notification when a reconfig
 464  *  request comes in and want/need to take part in the reconfiguration.  This
 465  *  is used when you have configuration info outside the server config file
 466  *  which needs to be re-initialized.
 467  *
 468  *
 469  *  IID_IRMAServerReconfigNotification:
 470  *
 471  *      {00000007-0901-11d1-8B06-00A024406D59}
 472  *
 473  */
 474 DEFINE_GUID(IID_IRMAServerReconfigNotification, 0x00000007, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 475             0xa0, 0x24, 0x40, 0x6d, 0x59);
 476
 477
 478 #undef  INTERFACE
 479 #define INTERFACE   IRMAServerReconfigNotification
 480
 481 DECLARE_INTERFACE_(IRMAServerReconfigNotification, IUnknown)
 482 {
 483     /*
 484      *  IUnknown methods
 485      */
 486     STDMETHOD(QueryInterface)   (THIS_
 487                                 REFIID riid,
 488                                 void** ppvObj) PURE;
 489
 490     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 491
 492     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 493
 494     /************************************************************************
 495      * IRMAServerReconfigNotification::WantReconfigNotification
 496      *
 497      * Purpose:
 498      *
 499      *      Tell the server that you want reconfig notification.
 500      */
 501     STDMETHOD(WantReconfigNotification) (THIS_
 502                 IRMAWantServerReconfigNotification* pResponse) PURE;
 503
 504     /************************************************************************
 505      * IRMAServerReconfigNotification::CancelReconfigNotification
 506      *
 507      * Purpose:
 508      *
 509      *      Tell the server that you no longer want reconfig notification.
 510      */
 511     STDMETHOD(CancelReconfigNotification)   (THIS_
 512                 IRMAWantServerReconfigNotification* pResponse) PURE;
 513
 514 };
 515
 516 /*
 517  *
 518  *  Interface:
 519  *
 520  *      IRMAWantServerReconfigNotification
 521  *
 522  *  Purpose:
 523  *
 524  *      Tell user that the server got a reconfig request and it is time to
 525  *  do your reconfiguration.  NOTE: You should not need this if all of your
 526  *  configuration is stored in the config file; that is taken care of through
 527  *  IRMAActiveRegistry.
 528  *
 529  *  IID_IRMAWantServerReconfigNotification:
 530  *
 531  *      {00000008-0901-11d1-8B06-00A024406D59}
 532  *
 533  */
 534 DEFINE_GUID(IID_IRMAWantServerReconfigNotification, 0x00000008, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 535             0xa0, 0x24, 0x40, 0x6d, 0x59);
 536
 537
 538 #undef  INTERFACE
 539 #define INTERFACE   IRMAWantServerReconfigNotification
 540
 541 DECLARE_INTERFACE_(IRMAWantServerReconfigNotification, IUnknown)
 542 {
 543     /*
 544      *  IUnknown methods
 545      */
 546     STDMETHOD(QueryInterface)   (THIS_
 547                                 REFIID riid,
 548                                 void** ppvObj) PURE;
 549
 550     STDMETHOD_(ULONG,AddRef)    (THIS) PURE;
 551
 552     STDMETHOD_(ULONG,Release)   (THIS) PURE;
 553
 554     /************************************************************************
 555      * IRMAWantServerReconfigNotification::ServerReconfig
 556      *
 557      * Purpose:
 558      *
 559      *      Notify user that a server reconfig request had come in and it
 560      * is now your turn to do external (not server config) reconfiguration.*
 561      */
 562     STDMETHOD(ServerReconfig)   (THIS_
 563         IRMAReconfigServerResponse* pResponse) PURE;
 564
 565 };
 566
 567
 568 #endif /*_RMACOMM_H_*/