CMAddRef

 (Available in 01 TS COM - TS_COM_DelegateIUnknown)

Purpose

Increment 'Ref-count' on the interface

Syntax

oDIObject:CMAddRef( )

Description

Before storing the object in a new variable, the application should increment the 'ref-count' of the object by callinf 'CMAddRef()'. When the variable ( in witch the object is stored ) is no longer accessable, the program should decrement 'ref-count' by calling the 'CMRelease()' method.

MSDN ==== IUnknown::AddRef The IUnknown::AddRef method increments the reference count for an interface on an object. It should be called for every new copy of a pointer to an interface on a given object.

ULONG AddRef(void);

Return Value Returns an integer from 1 to n, the value of the new reference count. This information is meant to be used for diagnostic/testing purposes only, because, in certain situations, the value may be unstable.

Remarks Objects use a reference counting mechanism to ensure that the lifetime of the object includes the lifetime of references to it. You use IUnknown::AddRef to stabilize a copy of an interface pointer. It can also be called when the life of a cloned pointer must extend beyond the lifetime of the original pointer. The cloned pointer must be released by calling IUnknown::Release.

Objects must be able to maintain (2 (31) )-1 outstanding pointer references. Therefore, the internal reference counter that IUnknown::AddRef maintains must be a 32-bit unsigned integer.

Notes to Callers Call this function for every new copy of an interface pointer that you make. For example, if you are passing a copy of a pointer back from a function, you must call IUnknown::AddRef on that pointer. You must also call IUnknown::AddRef on a pointer before passing it as an in-out parameter to a function; the function will call IUnknown::Release before copying the out-value on top of it.

Returns

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

Source

METHOD CMAddRef( ) 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, #AddRef )
      #ENDIF
      loRefCount:=SELF:_AIUnknown:Addref( )
      #IFDEF TS_TRACETIMED_ENABLE
         _TS_TraceTimedLeave( TS_TT_SYM_EXTERNAL, TS_TT_SYM_IUNKNOWN, #AddRef )
      #ENDIF
      SELF:_RefCount+=1
   ELSE
      TSTrace Warning "!SELF:FInit"
      loRefCount:=0
   END
   TSTrace Leave
RETURN loRefCount