Muokkaa

Jaa

Reference-Counting Conventions for COM Objects

  • Artikkeli

The methods in the audio interfaces follow a general set of rules for counting references on the COM objects that they take as input parameters or return as output parameters. These rules, and their exceptions, are summarized below. For more information about COM interfaces, see the COM section of the Microsoft Windows SDK documentation.

Reference Counting on Input Parameters

When calling a method that takes a reference to an object X as an input parameter, the caller must hold its own reference on the object for the duration of the call. This behavior is necessary to ensure that the method's pointer to object X remains valid until it returns. If the object Y that implements this method needs to hold a reference to object X beyond the return from this method, the method should call AddRef on object X before returning. When object Y later finishes using object X, it should call Release on object X.

For example, the IServiceGroup::AddMember method calls AddRef on the IServiceSink object that it adds to its service group. To complement this behavior, the IServiceGroup::RemoveMember method calls Release on the IServiceSink object that it removes from the service group.

Reference Counting on Output Parameters

A method that passes an object reference to the caller through an output parameter should call AddRef on the object before it returns (or before it releases its own reference to the object). This behavior is necessary to ensure that the caller holds a valid reference upon return from the call. The caller is responsible for calling Release on the object when it has finished using it.

For example, the IMiniportWaveCyclic::NewStream method calls AddRef on the stream, service group, and DMA channel objects that it outputs to the caller (the WaveCyclic port driver). The caller is responsible for releasing these references when it no longer needs them. For an implementation of the IMiniportWaveCyclic::NewStream method that shows this behavior, see the Sb16 sample adapter in earlier versions of the Microsoft Windows Driver Kit (WDK).

Exceptions to the Rules

For a description of the unconventional reference counting that this method performs on its DmaChannel output parameter, see IMiniportWavePci::NewStream.