ICaptureGraphBuilder2::AllocCapFile

  • Article
 
Microsoft DirectShow 9.0

ICaptureGraphBuilder2::AllocCapFile

The AllocCapFile method preallocates a capture file to a specified size. For best results, always capture to a defragmented, preallocated capture file that is larger than the size of the capture data.

Syntax

  HRESULT AllocCapFile(
  LPCOLESTR lpwstr,
  DWORDLONG dwlSize
);

Parameters

lpwstr

[in] Pointer to a wide-character string that contains the name of the file to create or resize.

dwlSize

[in] Size of the file to allocate, in bytes.

Return Values

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.

Remarks

This method fails if the file is read-only.

It is best to allocate as much space as possible—ideally, more than needed. However, this can result in a very large file that contains relatively little data. For example, a 1-gigabyte (GB) capture file might contain a few megabytes of captured video. Use the ICaptureGraphBuilder2::CopyCaptureFile method to copy the data into a new file. That method copies only the data and ignores the empty portion of the original file.

  • **Note   **The AllocCapFile method takes longer on Microsoft® Windows NT® 4.x or Microsoft® Windows® 2000 than it does on other Windows platforms, because the method must write over the entire preallocated file. However, it is still recommended that you use this method, because it results in better capture performance.

If you use this method to preallocate the file, call IFileSinkFilter2::SetMode on the file-writer filter with the value zero. If the filter is set to AM_FILE_OVERWRITE, it will delete the preallocated file. Note that some file-writer filters do not support mode 0.

Requirements

Header: Declared in Strmif.h; include Dshow.h.

Library: Use Strmiids.lib.

See Also