mmioCFDeleteEntry
The mmioCFDeleteEntry function marks a Table of Contents (CTOC) entry for deletion within an open RIFF compound file.
Syntax
#define INCL_MMIOOS2 #include <os2.h> ULONG mmioCFDeleteEntry(HMMCF hmmcf, PMMCTOCENTRY pmmctocentry, ULONG ulFlags);
Parameters
- hmmcf (HMMCF) - input
- A RIFF compound-file handle returned by mmioCFOpen.
- pmmctocentry (PMMCTOCENTRY) - input
- A pointer to the MMCTOCENTRY structure containing the name of the element to be deleted. The element name is appended to the end of this structure. Ensure enough memory is allocated for the variable-size structure.
- ulFlags (ULONG) - input
- Reserved for future use and must be set to zero.
Return Values
- rc (ULONG)
- Returns the result of the operation:
- MMIO_CF_SUCCESS: Function succeeded (0).
- MMIOERR_INVALID_HANDLE: The provided handle is not valid.
- MMIOERR_INVALID_PARAMETER: A required parameter (like the element name) was missing or invalid.
- MMIOERR_READ_ONLY_FILE: The RIFF compound file is opened as read-only.
- MMIO_CF_FAILURE: The function failed. Call mmioGetLastError for details:
- MMIOERR_CF_ENTRY_NOT_FOUND: The specified element name was not found in the CTOC.
- MMIOERR_INTERNAL_SYSTEM: An internal system error occurred.
Remarks
The identifier used to locate the entry is the element name appended to the MMCTOCENTRY structure.
When this function is called, it does not physically erase data from the file. Instead:
- The entry in the CTOC is marked as deleted by setting its `ulMedType` field to `FOURCC_DEL`.
- The actual element data remains occupies space in the Compound-file Resource-Group (CGRP) chunk.
To physically remove the data and reclaim disk space, you must use mmioCFCopy or mmioCFCompact to create a new, compacted version of the compound file.
Example
HMMCF hmmcf1;
MMCTOCENTRY mmctocentry;
ULONG ulFlags = 0;
ULONG rc;
/* Initialize the structure and specify the element name */
memset(&mmctocentry, '\0', sizeof(MMCTOCENTRY));
/* (Populate mmctocentry with the target element name here) */
rc = mmioCFDeleteEntry(hmmcf1, &mmctocentry, ulFlags);
if (rc == MMIO_CF_SUCCESS) {
/* Entry marked as FOURCC_DEL in memory */
} else {
/* Handle error */
}