hxsmartptr.h

著名的 helix realplayer 基于手机 symbian 系统的 播放器全套源代码

/* ***** BEGIN LICENSE BLOCK ***** 
 * Version: RCSL 1.0/RPSL 1.0 
 *  
 * Portions Copyright (c) 1995-2002 RealNetworks, Inc. All Rights Reserved. 
 *      
 * The contents of this file, and the files included with this file, are 
 * subject to the current version of the RealNetworks Public Source License 
 * Version 1.0 (the "RPSL") available at 
 * http://www.helixcommunity.org/content/rpsl unless you have licensed 
 * the file under the RealNetworks Community Source License Version 1.0 
 * (the "RCSL") available at http://www.helixcommunity.org/content/rcsl, 
 * in which case the RCSL will apply. You may also obtain the license terms 
 * directly from RealNetworks.  You may not use this file except in 
 * compliance with the RPSL or, if you have a valid RCSL with RealNetworks 
 * applicable to this file, the RCSL.  Please see the applicable RPSL or 
 * RCSL for the rights, obligations and limitations governing use of the 
 * contents of the file.  
 *  
 * This file is part of the Helix DNA Technology. RealNetworks is the 
 * developer of the Original Code and owns the copyrights in the portions 
 * it created. 
 *  
 * This file, and the files included with this file, is distributed and made 
 * available on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 
 * EXPRESS OR IMPLIED, AND REALNETWORKS HEREBY DISCLAIMS ALL SUCH WARRANTIES, 
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS 
 * FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 
 * 
 * Technology Compatibility Kit Test Suite(s) Location: 
 *    http://www.helixcommunity.org/content/tck 
 * 
 * Contributor(s): 
 *  
 * ***** END LICENSE BLOCK ***** */

/*!
  @header hxsmartptr.h
  
  @abstract Macro implementation of smart pointers to COM interfaces
            Based on pnmisc\pub\smartptr.h
 
  @discussion
 	A SmartPointer is a class that contains a pointer, but acts like it 
 	<em>is</em> the contained pointer.  When used it helps enforce correct usage 
 	of the pointer it contains.  In this case it provides the following 
 	safeguards:<ul>
 	    <li>ASSERT if the contained pointer is NULL when you attempt to 
 		use it.
 	    <li>ASSERT if you attempt to replace a valid pointer without 
 		releasing it.
 	    <li>Automatically AddRef() a pointer during assignment.
 	    <li>Automatically QI() an incoming pointer to the correct type 
 		during assignment.
 	    <li>Automatically Release() an existing pointer during assignment.
 	    <li>Automatically Release() an existing pointer during destruction.
       </ul>
 
 	SmartPointers also simplify usage. Example:
 
    <pre><code>
    HX_SMART_POINTER_INLINE( SPIHXBuffer, IHXBuffer );
    ReadDone(HX_RESULT status, IUnknown* pbufData)
    {
        SPIHXBufferPtr spBufData = pbufData;
        if(spBufData.IsValid())
        {
            cout << spBufData->GetBuffer() << endl;
        }
    }
    </code></pre>
 	This example has no memory leaks.  In the Assignment the IUnknown 
 	pointer is QI'd for the IHXBuffer.  If the QI had failed, then 
 	the IsValid test would fail too.  Even if the IsValid Test was 
 	omitted, spbufData->GetBuffer() would cause an assertion if 
 	the QI had failed.
 
   Usage Tips:
 	
 	Cannot use SmartPointers as List elements.
 
   Note that there are specific macros for creating smart pointers to 
   IUnknowns - plugging IUnknown into the standard smart pointer 
   generation macros will cause compile errors.
 
   The interface has been cut down to a minimum. In particular, the 
   automatic conversion operators have been removed to avoid the 
   possibility of unexpected conversions happening automatically. It 
   is still possible to get to the raw pointer if it is necessary.
 
 */

/*!
    @class SPIUnknown
    @description A smart pointer to an IUnknown. This will always contain the unique IUnknown 
      - i.e. it will QI any pointer passed to it (including IUnknown pointers) to make sure it gets 
      the unique IUnknown.
*/

/*!
    @class SPCIUnknown
    @description A const smart pointer to an IUnknown. This will always contain the unique IUnknown 
      - i.e. it will QI any pointer passed to it (including IUnknown pointers) to make sure it gets 
      the unique IUnknown.
*/

/*!
    @function CLASS_NAME()
*/

/*!
    @function CLASS_NAME( const CLASS_NAME& rspact )
*/

/*!
    @function CLASS_NAME(INTERFACE* pact)
*/

/*!
    @function ~CLASS_NAME()
*/

/*!
    @function CLASS_NAME(IHXCommonClassFactory* pIObjectSource, REFCLSID clsid, HX_RESULT* pResult = NULL )
    @description Create an object from a factory and attempt to assign it 
      to this smart pointer. If the created object supports the interface 
      this smart pointer refers, the smart pointer will point to that object. 
      If the created object does not support the interface, the smart pointer 
      will end up as NULL and the created object will be immediately destroyed.
    @param pIObjectSource The class factory to use
    @param clsid The clsid of the object to create
    @param pResult The result of the CreateInstance call - if this parameter 
      is NULL the result will not be returned.
*/

/*!
    @function INTERFACE* operator -> () const
*/

/*!
    @function INTERFACE& operator * () const
*/

/*!
    @function CLASS_NAME& operator =( const CLASS_NAME& rspact )
*/

/*!
    @function CLASS_NAME& operator =( INTERFACE* pNew )
*/

/*!
    @function BOOL IsValid() const
*/

/*!
    @function INTERFACE* Ptr() const
    @description Returns a non-addrefed version of the internal 
      pointer. This is designed to be used as an easy way of 
      passing the pointer to functions that take an unadorned 
      pointer. If the pointer is assigned to a local variable, 
      please bear in mind that it is not addrefed and should 
      be treated accordingly. The best way to get an AddReffed 
      pointer assigned to a local variable is to use the AsPtr 
      method.
*/

/*!
    @function AsPtr( INTERFACE*  ) const
    @description Returns an addrefed version of the internal 
      pointer. Onlu available on non-const smart pointers (if
      this was available for a const smart pointer it would 
      have to return a const pointer which then couldn't be 
      released ).
*/

/*!
    @function void AsUnknown( IUnknown** ppIUnknown ) const
    @description Returns an addrefed version of the pointer as an 
      IUnknown*.
*/

/*!
     @function Query( IUnknown* pIUnk )
     @description If possible, set the value of this smart pointer to the
	given pointer. The value of this smart pointer will only be changed if the
	supplied pointer is non-NULL and it supports the interface corresponding to
	this smart pointer. If either of these conditions is not true the value of
	the smart pointer will be unchanged.
     @param pIUnk The pointer to try and assign to this.
     @result There are three possible results:
         1. If the pointer passed in was non-NULL and the object supported the
	    appropriate interface, a SUCCEEDED result will be returned (corresponding
	    to the result of the internal QI).
         2. If the pointer passed in was non_NULL but the object did not 
	    support the appropriate interface, a FAILED result will be returned 
	    (corresponding to the result of the internal QI).
         3. If the pointer passed in was NULL, HXR_INVALID_PARAMETER will be returned.
*/

/*!
     @function Clear()
     @description Releases the smart pointers reference to the underlying pointer and 
       set the smart pointer to NULL.
*/

/*!
     @function AsInOutParam()
     @description Clears the smart pointer, then returns a pointer to the underlying 
       pointer. This is suitable for passing to functions which pass back an AddReffed 
       pointer as output. E.g.

      void SomeFunction( IHXSomeInterface** ppOutput );

      SPIHXSomeInterface spI;

      SomeFunction( spi>AsInOutParam() );
*/


#ifndef _HXSMARTPTR_H_
#define _HXSMARTPTR_H_

#include "hxassert.h"
#include "hxcom.h"
#include "hxccf.h"

/*!
    @defined HX_SMART_POINTER_INLINE
    @abstract 
	Declare a smart pointer of name CLASS_NAME which points to an 
	interface INTERFACE. Inline definitions of all functions.
*/
#define HX_SMART_POINTER_INLINE( CLASS_NAME, INTERFACE )		\
	HX_PRIVATE_SMART_POINTER_INLINE( CLASS_NAME, INTERFACE, HX_PRIVATE_BLANK, HX_PRIVATE_NON_IUNKNOWN_FUNCTIONS( CLASS_NAME, INTERFACE, HX_PRIVATE_BLANK ) )

/*!
    @defined HX_CONST_SMART_POINTER_INLINE
    @abstract 
	Declare a const smart pointer of name CLASS_NAME which points to an 
	interface INTERFACE. Inline definitions of all functions.
*/
#define HX_CONST_SMART_POINTER_INLINE( CLASS_NAME, INTERFACE )		\
	HX_PRIVATE_SMART_POINTER_INLINE( CLASS_NAME, INTERFACE, const, HX_PRIVATE_NON_IUNKNOWN_FUNCTIONS( CLASS_NAME, INTERFACE, const ) )

/*!
    @defined HX_IUNKNOWN_SMART_POINTER_INLINE
    @abstract 
	Declare a smart pointer of name CLASS_NAME which points to an 
	IUnknown interface. Inline definitions of all functions.
*/
#define HX_IUNKNOWN_SMART_POINTER_INLINE( CLASS_NAME )		\