Messages for Configuring the Driver State

The video compression-specific and decompression-specific configuration messages are typically initiated by the client application or from dialog boxes displayed by your driver. Your driver should use these messages to configure the driver.

If your driver is configurable, it should support the ICM_CONFIGURE message for driver configuration. It should also use this message to set parameters for compression or decompression. Any options the user selects in the dialog box displayed for ICM_CONFIGURE should be saved as part of the state information referenced by the ICM_GETSTATE and ICM_SETSTATE messages.

The ICM_GETSTATE and ICM_SETSTATE messages query and set the internal state of your compression or decompression driver. State information is device dependent, and your driver must define its own data structure for it. While the client application reserves a memory block for the information, it will obtain the size needed for the memory block from your driver. If your driver receives ICM_GETSTATE with a NULL pointer for dwParam1, the client application is requesting that your driver return the size of its state information. Conversely, if your driver receives ICM_GETSTATE with dwParam1 pointing to a block of memory, and dwParam2 specifying the size of the memory block, the client application is requesting that your driver transfer the state information to the memory block.

When your driver receives ICM_SETSTATE, with dwParam1 pointing to a block of memory and dwParam2 specifying the size of the memory block, the client application is requesting that your driver restore its configuration from the state information contained in the memory block. Before setting the state, your driver should verify that the state information applies to your driver. One technique for verifying the data is to reserve the first DWORD in the state data structure for the four-character code used to identify your driver. If you set this DWORD for data returned for ICM_GETSTATE, you can use it to verify the data supplied with ICM_SETSTATE. If ICM_SETSTATE has a NULL pointer for dwParam1, it indicates that your driver should return to its default state.

State information should not contain any data that is absolutely required for data decompression—any such data should be part of the format you return for the ICM_DECOMPRESS_GET_FORMAT message.