Reference Counting Rules

a. In-Out parameters to functions: The caller must AddRef() the

      actual parameter, because it will be Release()'d by the callee
      when the out-value is stored on top of it.

      LPOLEOBJECT lpObject;
         .
         .  // Get pointer to IOleObject.
         .
      LPVIEWOBJECT lpView = lpObject;

      lpObject->AddRef()

      // GetViewObject is a theoretical function that takes a
      // pointer to anything derived from IUnknown, and then
      // returns a pointer to IViewObject in the same variable
      // passed as the parameter. The AddRef() above is needed so
      // that the original pointer to IOleObject is not freed.

      GetViewObject(lpView);

   b. Fetching a global variable: The local copy of an interface
      pointer fetched from an existing copy of the pointer in a global
      variable must be independently reference counted because called
      functions might destroy the copy in the global while the local
      copy is still alive.

      void function()
      {
      // Get a pointer to IOleObject from a global variable.
      LPOLEOBJECT lpOleObject = glpObject;

      // This AddRef() is needed so that the interface
      // pointed to by the global variable, glpObject,
      // does not get released by a different part of
      // the applications code.

      lpOleObject->AddRef();
         .
         . // use lpOleObject;
         .
      lpOleObject->Release();
      }

   c. New pointers synthesized out of "thin air": A function that
      synthesizes an interface pointer using special internal
      knowledge rather than obtaining it from some other source must
      do an initial AddRef() on the newly synthesized pointer.
      Important examples of such routines include instance creation
      routines, implementations of IUnknown::QueryInterface, and so
      forth.

      STDMETHDOIMP IUnknown::QueryInteface( REFIID iidInterface,
                                         LPVOID FAR *ppvObj)
      {
      *ppvObj = NULL;
      SCODE sc = E_NOINTERFACE;

      if (iidInterface == IUnknown)
          {
          *ppvObj = this;

          // This AddRef() is needed because a new pointer
          // was just created.

          AddRef();
         sc = S_OK;
          }

      return ResultFromScode(sc);
      }

   d. Returning a copy of an internally stored pointer: Once the
      pointer has been returned, the callee has no idea how its
      lifetime relates to that of the internally stored copy of the
      pointer. Thus, the callee must AddRef() the pointer copy before
      returning to it.

      // m_lpOleObject is a private member variable of a C++ class.
      // GetOleObject is a member function to return access to this
      // pointer.

      void GetOleObject (LPVOID FAR *ppObject)
      {
          *ppObject = m_lpOleObject;

          // This AddRef() is needed due to this rule.

          m_lpOleObject->AddRef();
       }