Name

ICCallbackProc --- Registers a callback procedure for streaming video compression or decompression

Syntax

#include <mme/mme_api.h>
MMRESULT ICCallbackProc(HIC hic,
      void (∗CallbackProc)(),
      DWORD dwInstance);

Arguments

HIC hic
Specifies a handle to a decompressor.

void (∗CallbackProc)()
Specifies a callback procedure to use.

DWORD dwInstance
Specifies the user instance data which the compressor will pass back to the callback procedure.
 

Description

This function registers a callback procedure. Once a callback procedure is registered, ICCompress and ICDecompress routines are no longer blocking routines. Instead, they return data asynchronously to the registered callback. 

If the CallbackProc is NULL, then a previously registered CallbackProc is deregistered and operations return to synchronous behavior. 

The registration must occur before compression or decompression begins. A new callback procedure may be registered after compression or decompression has ended but before a new sequence has begun. 
 

Extensions

The ICCallbackProc function is a Digital extension to the Microsoft multimedia API specification. 
 
 

Return Values

Returns ICERR_OK if the function is successful; otherwise, it returns one of the following error codes:

Callback for Streaming Video CODECs

#include <mme/mme_api.h>
void CALLBACK icmFunc(HIC hic,
                      DWORD wMsg,
                      DWORD dwInstance,
                      LPARAM ∗ lParam1,
                      DWORD errorFlags);

Callback Arguments

HIC hic
Specifies a handle to a decompressor.

DWORD wMsg
Specifies the ICM streaming message. The following messages are defined:

ICM_CB_COMP_DATA
Sent when the compressor has completed the compression operation.

ICM_CB_DCMP_DATA
Sent when the decompressor has completed the decompression operation.

DWORD dwInstance
Specifies the data passed to the ICCallbackProc. 

LPARAM lParam1
Specifies either a pointer to a ICCOMPRESSDATA structure or a pointer to the decompressed output image buffer, depending on whether the message is ICM_CB_COMP_DATA or ICM_CB_DCMP_DATA, respectively.  The ICCOMPRESSDATA data structure is only valid while the callback function is executing. 

DWORD errorFlags
Specifies ICERR_OK on success or an error that occurred during the operation.

If an error is specified, the lpOutput pointer will still be the pointer originally specified to ICCompress or ICDecompress for the application’s reference. 

For compression, if an error is specified, the biSizeImage field will be set to 0. 

Error flags are the same as those returned from ICCompress or ICDecompress. 
 

Callback Description for Compression

The ICCOMPRESSDATA data structure is allocated by the mmeserver.  The ICCOMPRESSDATA data structure is defined as follows:

typedef struct {
    DWORD       lpdwFlags;
    DWORD       biSizeImage;
    LPVOID      lpOutput;
} ICCOMPRESSDATA;

DWORD lpdwFlags
Specifies the return flags for the AVI index. See the lpdwFlags parameter of ICCompress for further details. Note that while the name of the field is lpdwFlags to match that in the lpdwFlags parameter of the ICCompress function, this field is not a pointer. 

DWORD biSizeImage
Specifies the size of the data in the lpOutput buffer. This will be 0 on an error. See the lpbiOutput.biSizeImage parameter of ICCompress for further details. 

LPARAM lpOutput
Specifies a pointer to the buffer where the compressed data has been written, if no error occurred. See the lpData parameter of ICCompress for further details. 
 
 

Callback Description for Decompression

For decompression, the callback lParam1 field specifies:

LPARAM lpOutput
Specifies a pointer to the buffer where the decompressed data has been written if no error occurred. See the lpBits parameter of ICDecompress. 
 

Callback for Bitstreaming CODECs

#include <mme/mme_api.h>
 void CALLBACK icmFunc(HIC hic,
                      DWORD wMsg,
                      DWORD dwInstance,
                      LPARAM ∗lParam1,
                      DWORD errorFlags);

Callback Arguments

HIC hic
Specifies a handle to the compressor or decompressor.

DWORD wMsg
Specifies ICM bitstreaming. The following messages are defined:

ICM_CB_RELEASE_BUFFER  (compression and decompression)
Indicates that the CODEC has finished with a buffer, and the buffer may be reused. The dwDataType field indicates what the buffer was used for, and the lpData field points to the buffer. For compression, the dwDataUsed field indicates how many bytes of the ICM_CB_DATA_COMPRESSED-type buffer were used. 

ICM_CB_END_BUFFERS (compression and decompression)
Indicates that the CODEC has run out of a buffer to work with. Use the lpData field in the callback structure to pass the pointer of a new data buffer of the type indicated by the dwDataType field. You must first allocate the buffer using the mmeAllocBuffer function and specify the buffer size, in bytes, in the dwDataSize field. 

ICM_CB_SEQ_HEADER (decompression only)
Indicates that a descriptive (sequence) header has been encountered in the bitstream. The lpFormat field points to a data structure of the following type:
 

BITMAPINFOHEADER, if the <EMPHASIS>(dwDataTypeBOLD) field is equal to ICM_CB_DATA_IMAGE

WAVEFORMATEX, if the dwDataType field is equal to ICM_DATA_AUDIO

ICM_CB_SEQ_END (decompression only)
Indicates that an end-of-sequence code has been encountered in the bitstream.

ICM_CB_FRAME_FOUND (decompression only)
Indicates that the start of a frame has been found in the bitstream. The application sets the dwAction field to one of the following:
 

ICM_CB_ACTION_CONTINUE, if the frame is to be decompressed

ICM_CB_ACTION_DROP, if the frame is to be dropped (skipped)

ICM_CB_FRAME_READY (compression and decompression)
Indicates that a frame has been compressed or decompressed. The lpData field points to the buffer containing the frame.  The lpDataType field indicates if the frame is ICM_CB_DATA_IMAGE or ICM_CB_DATA_AUDIO. The lpFlags field indicates if the frame is key. 

ICM_CB_CODEC_DONE (compression and decompression)
Signals the application, after a call to the ICDecompressEnd function or the ICCompressEnd function, that a CODEC has ended. The CODEC has finished with all the buffers and no more callbacks will occur until ICDecompressBegin or ICCompressBegin is called. 

DWORD dwInstance
This argument is not used.

LPARAM ∗lParam1
Specifies a pointer to an ICCALLBACKINFO data structure. 

DWORD errorFlags
This argument is not used.
 
 

Return Values

Returns ICERR_OK if the function is successful; otherwise, it returns one of the following error codes:

See Also

ICCompress(3mms), ICCompressBegin(3mms), ICCompressEnd(3mms), ICDecompress(3mms), ICDecompressBegin(3mms), ICDecompressEnd(3mms)