CMRelease

 (Available in 01 TS COM - TS_COM_DelegateIUnknown)

Purpose

Decrement 'Ref-count' on the interface

Syntax

oDelegateIUnknown:CMRelease( )

Description

Before storing the object in a new variable, the application should increment the 'ref-count' of the object by callinf 'AddRef()'. When the variable ( in witch the object is stored ) is no longer accessable, the program should decrement 'ref-count' by calling the 'CMRelease()' method. The instance of the object will be destroyed ( and it's memory will be freed ) when the actual value of 'ref-count' reaches zero.

MSDN ==== IUnknown::Release Decrements the reference count for the calling interface on a object. If the reference count on the object falls to 0, the object is freed from memory.

ULONG Release(void);

Return Value Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks If IUnknown::AddRef has been called on this object's interface n times and this is the n+1th call to IUnknown::Release, the implementation of IUnknown::AddRef must cause the interface pointer to free itself. When the released pointer is the only existing reference to an object (whether the object supports single or multiple interfaces), the implementation must free the object.

Note Aggregation of objects restricts the ability to recover interface pointers.

Notes to Callers Call this function when you no longer need to use an interface pointer. If you are writing a function that takes an in-out parameter, call IUnknown::Release on the pointer you are passing in before copying the out-value on top of it.

Returns

RefCount = LONG ( Is not always the actual value, See 'Inside COM' )

Example

ACCESS AIThis AS TS_AbstractIUnknown PASCAL CLASS SomeIObject
LOCAL oAIUnknown AS TS_AbstractIUnknown
   IF SELF:FInit
      oAIUnknown:=SELF:_AIUnknown
      IF oAIUnknown<>NULL_OBJECT
         oAIUnknown:AddRef( )
      ELSE
         TSTrace Fatal "oAIUnknown==NULL_OBJECT"
      END
   ELSE
      TSTrace Warning "!SELF:FInit"
      oAIUnknown:=NULL_OBJECT
   END
RETURN oAIUnknown

FUNCTION DoSomeThing( oSomeIObject AS SomeIObject )
LOCAL oAIUnknown AS TS_AbstractIUnknown
// The method that passes the interface to this function
// uses 'AddRef()' to increment the 'ref-count'
   oAIUnknown:=oSomeIObject:IUnknown
// Use the interface in 'IUnknown'
   ... 
// When we are done using the interface, we need to use
// the 'Release()' method to decrement the 'ref-count'
   oAIUnknown:Release( )
   RETURN...

Source

METHOD CMRelease( ) AS LONG PASCAL CLASS TS_DelegateIUnknown
LOCAL loRefCount AS LONG
   TSTrace Enter
   IF SELF:FInit
      #IFDEF TS_TRACETIMED_ENABLE
         _TS_TraceTimedEnter( TS_TT_SYM_EXTERNAL, TS_TT_SYM_IUNKNOWN, #Release )
      #ENDIF
      loRefCount:=SELF:_AIUnknown:Release( )
      #IFDEF TS_TRACETIMED_ENABLE
         _TS_TraceTimedLeave( TS_TT_SYM_EXTERNAL, TS_TT_SYM_IUNKNOWN, #Release )
      #ENDIF
      SELF:_RefCount-=1
   ELSE
      TSTrace Warning "!SELF:FInit"
      loRefCount:=0
   END
   TSTrace Leave
RETURN loRefCount