_KsEdit function (ks.h)

The KsEdit function guarantees that a given item is dynamically allocated and associated with an AVStream object through the object bag.

Syntax

KSDDKAPI NTSTATUS _KsEdit(
  [in]      KSOBJECT_BAG ObjectBag,
  [in, out] PVOID        *PointerToPointerToItem,
  [in]      ULONG        NewSize,
  [in]      ULONG        OldSize,
  [in]      ULONG        Tag
);

Parameters

[in] ObjectBag

The KSOBJECT_BAG (equivalent to type PVOID) to use in the check. If the item is not contained within the object bag, KsEdit dynamically allocates sufficient memory for the item, copies the old contents, and places the newly allocated memory in this object bag.

[in, out] PointerToPointerToItem

A pointer to a pointer to the item being edited.

[in] NewSize

The number of bytes to allocate for the item.

[in] OldSize

The number of bytes the item currently takes up.

[in] Tag

Contains the pool tag to use for the allocations. Drivers normally specify the pool tag as a string of up to four characters, delimited by single quotation marks. The string is usually specified in reversed order. The ASCII value of each character in the tag must be between 0 and 127.

Return value

Returns success or STATUS_INSUFFICIENT_RESOURCES.

Remarks

Note that KsEdit and KsEditSized are macros created to make _KsEdit easier to use. While _KsEdit allows you to resize an item, KsEdit does not. The macro KsEdit calls _KsEdit, specifying sizeof(** PointerToPointerToItem) as both sizes.

For example, consider a pin that needs to modify its allocator framing on creation. Because the descriptor is statically coded and new pins may use it, the solution is to modify the pin descriptor as follows:

KsEdit(Pin, &Pin->Descriptor, Tag);
Pin->Descriptor->AllocatorFraming = NewAllocatorFraming;

The call to KsEdit guarantees that Pin->Descriptor is dynamic memory that is associated with Pin. Note that arbitrary modification of descriptors and other AVStream structures can cause undesirable results. Minidrivers should exercise caution when using KsEdit on AVStream structures.

KsEditSized calls _KsEdit with the same parameters it receives, except that Object is replaced by Object->Bag and the pointer is typecast to PVOID.

Note that when calling _KsEdit, a caller must hold the mutex associated with the bag. 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