KsAddItemToObjectBag function (ks.h)

Article
03/15/2022

The KsAddItemToObjectBag function adds an object or block of memory to the given object bag.

Syntax

KSDDKAPI NTSTATUS KsAddItemToObjectBag(
  [in]           KSOBJECT_BAG           ObjectBag,
  [in]           __drv_aliasesMem PVOID Item,
  [in, optional] PFNKSFREE              Free
);

Parameters

[in] ObjectBag

The KSOBJECT_BAG (equivalent to type PVOID) to which to add the requested item. Every AVStream object (for example, KSFILTER and KSPIN) contains a member called Bag. Pass that member in this parameter.

[in] Item

A pointer to the item to add to the object bag.

[in, optional] Free

A function that is called when the item is removed from the object bag or when the object bag is deleted. This function typically is used to free any dynamic memory associated with Item. The function should be prototyped as follows:

void Free (IN PVOID Data);

If the caller does not specify this optional parameter, Item is freed with ExFreePool when removed from the object bag or when the object bag is deleted.

Return value

Either returns STATUS_SUCCESS indicating that the addition went normally or STATUS_INSUFFICIENT_RESOURCES indicating that there are insufficient system resources for the operation to proceed.

Remarks

Before calling KsAddItemToObjectBag, the minidriver must acquire the mutex associated with the specific object bag. If ObjectBag is a member of a KSDEVICE or KSFILTERFACTORY, acquire the device mutex. If the bag is a member of a KSFILTER, acquire the filter control mutex. If the bag is a member of a KSPIN object, acquire the parent KSFILTER's filter control mutex.

For more information, see Object Bags and Mutexes in AVStream.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows XP and later operating systems and DirectX 8.0 and later DirectX versions.
Target Platform	Universal
Header	ks.h (include Ks.h)
Library	Ks.lib
IRQL	PASSIVE_LEVEL