addRef method

int addRef()

Increments the reference count of this COM object.

Call this method for every new copy of an interface pointer that you make. For example, if you return a copy of a pointer from a method, then you must call addRef on it before returning. Similarly, if you pass a pointer as an in-out parameter to a method, you should call addRef on it before the call. This ensures the method has a valid reference to the object and can safely call release before replacing the original pointer with the out-value.

Each call to addRef must be balanced by a corresponding call to release to properly manage the object's lifetime.

Example:

// Create a new COM object instance (e.g., IFileDialog).
final fileDialog = createInstance<IFileDialog>(FileOpenDialog);

// Increment the reference count before assigning the object to a VARIANT.
fileDialog.addRef();

// Create a VARIANT to hold the COM object.
final variant = Variant.unknown(fileDialog);

// Pass the VARIANT to a native function.
// ...

// Clear the VARIANT eagerly, releasing its resources (including calling
// release on the COM object).
variant.free();

// Release the final reference to the COM object.
fileDialog.release();

To learn more, see learn.microsoft.com/windows/win32/api/unknwn/nf-unknwn-iunknown-addref.

Implementation

@pragma('vm:prefer-inline')
int addRef() => _AddRefFn(ptr);