View source for MCI BUFFER

{{DISPLAYTITLE:MCI_BUFFER}}
This message allows an application to allocate (or deallocate) buffers for use with the audio device. Buffers are limited to 64K on Intel machines.

==Syntax==
<PRE>
param1
ULONG ulParam1; /* Flags for buffer operation. */

param2
PMCI_BUFFER_PARMS pParam2; /* Pointer to the MCI_BUFFER_PARMS data structure. */
</PRE>

==Parameters==
;''ulParam1'' ([[ULONG]]) - input
:This parameter can contain any of the following flags:
:* '''MCI_NOTIFY''' A notification message will be posted to the window specified in the ''hwndCallback'' field of the data structure pointed to by the ''pParam2'' parameter. The notification will be posted when the action indicated by this message is completed or when an error occurs.
:* '''MCI_WAIT''' Control is not to be returned until the action indicated by this message is completed or an error occurs.
:* '''MCI_ALLOCATE_MEMORY''' Allocates memory for the mixer.
:* '''MCI_DEALLOCATE_MEMORY''' Deallocates memory from the mixer.

;''pParam2'' ([[PMCI_BUFFER_PARMS]]) - input
:A pointer to an [[MCI_BUFFER_PARMS]] data structure.

==Returns==
;''rc'' ([[ULONG]]) - returns
:Return codes indicating success or type of failure:
:* '''MCIERR_SUCCESS''' If the function succeeds, 0 is returned.
:* '''MCIERR_INVALID_DEVICE_ID''' Invalid device ID given.
:* '''MCIERR_INVALID_FLAG''' Invalid flag specified for this command.
:* '''MCIERR_INVALID_BUFFER''' Buffer specified in the ''pBufList'' field of the [[MCI_BUFFER_PARMS]] structure is invalid.
:* '''MCIERR_INVALID_MODE''' Command invalid for current mode.
:* '''MCIERR_OUT_OF_MEMORY''' Memory could not be allocated.

==Remarks==
On input, [[MCI_BUFFER_PARMS]] should contain the number of buffers to be allocated, the size for each buffer, and a pointer to an array of [[MCI_MIX_BUFFER]] structures (one per buffer).

The mixer will attempt to allocate the number of buffers and size of buffers to use. If the mixer cannot satisfy the entire request, it will update the ''ulNumBuffers'' field with the total number of buffers that it was able to allocate. If no memory could be allocated, **MCIERR_OUT_OF_MEMORY** will be returned. If memory has already been allocated, and the **MCI_ALLOCATE_BUFFER** flag is used, **MCIERR_INVALID_MODE** is returned.

==Example Code==
<PRE>
 MCI_MIX_BUFFER  MyBuffers[ MAX_BUFFERS ];
 MCI_BUFFER_PARMS BufferParms;
 ULONG usDeviceID;
 ULONG rc;
 ULONG ulNumBuffers;
 ULONG ulLoop;
 HMMIO hmmio; /* Assume this is opened */

 BufferParms.ulNumBuffers = 40;
 BufferParms.ulBufferSize = 4096;
 BufferParms.pBufList = MyBuffers;

 rc = mciSendCommand( usDeviceID,
                      MCI_BUFFER,
                      MCI_WAIT | MCI_ALLOCATE_MEMORY,
                      ( PVOID ) &BufferParms,
                      0 );

 if ( ULONG_LOWD( rc ) != MCIERR_SUCCESS )
    {
    printf( "Error allocating memory. rc is: %d", rc );
    exit ( 1 );
    }

 /* MCI driver will return the number of buffers   */
 /* it was able to allocate.                         */
 /* It will also return the size of the information  */
 /* allocated with each buffer.                      */

 ulNumBuffers = BufferParms.ulNumBuffers;

 for ( ulLoop = 0; ulLoop < ulNumBuffers; ulLoop++ )
    {
    rc = mmioRead ( hmmio,
                      MyBuffers[ ulLoop ].pBuffer,
                      MyBuffers[ ulLoop ].ulBufferLength );

    if ( !rc )
      {
      exit( rc );
      }
    MyBuffers[ ulLoop ].ulUserParm = ulLoop;

    }
</PRE>

== Related Methods==
* [[MCI_MIXSETUP]]

[[Category:MCI]]